Add new documentation fully contained within the repo

.gitignore

@@ -17,6 +17,7 @@ static/sets/
 
 # Temporary
 *.csv
+/local/
 
 # Apple idiocy
 .DS_Store

README.md

@@ -2,230 +2,31 @@
 
 A web application for organizing and tracking LEGO sets, parts, and minifigures. Uses the Rebrickable API to fetch LEGO data and allows users to track missing pieces and collection status.
 
-> **Screenshots at the end of the readme!**
-
 <a href="https://www.buymeacoffee.com/frederikb" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="41" width="174"></a>
 
 ## Features
 
 - Track multiple LEGO sets with their parts and minifigures
 - Mark sets as checked/collected
+- Mark minifigures as collected for a set
 - Track missing pieces
 - View parts inventory across sets
 - View minifigures across sets
-- Automatic updates for LEGO data (themes, colors, sets)
 - Wishlist to keep track of what to buy
 
-## Prerequisites
+## Prefered setup: pre-build docker image
 
-- Docker
+Use the provided [compose.yaml](compose.yaml) file.
-- Docker Compose
-- Rebrickable API key (from [Rebrickable](https://rebrickable.com/api/))
 
-## Setup
+See [setup](docs/setup.md).
-
-1. Clone the repository:
-```bash
-git clone https://gitea.baerentsen.space/FrederikBaerentsen/BrickTracker.git
-cd BrickTracker
-mkdir static/{sets,instructions,parts,minifigs}
-```
-
-2. Create a `.env` file with your configuration:
-```
-REBRICKABLE_API_KEY=your_api_key_here
-DOMAIN_NAME=https://your.domain.com
-LINKS=True
-RANDOM=True
-```
-
-- If using locally, set `DOMAIN_NAME` to `http://localhost:3333`.
-
-- `LINKS`: Set to `True` in order for set numbers to be links to Rebrickable on the front page. 
-
-- `RANDOM`: Set to `True` in order for the sets to shuffle on the frontpage each load.
-
-3. Deploy with Docker Compose:
-```bash
-docker compose up -d
-```
-
-4. Access the web interface at `http://localhost:3333`
-
-5. The database is created, csv files are downloaded and you will be redirected to the `/create` page for inputting a set number.
-
-## Setup using pre-build Docker image
-
-1. Setup folders and files:
-```bash
-mkdir BrickTracker
-cd BrickTracker
-mkdir -p static/{sets,instructions,parts,minifigs}
-touch app.db
-```
-
-2. Create Docker Compose file:
-```bash
-services:
-  bricktracker:
-    container_name: BrickTracker
-    restart: unless-stopped
-    image: gitea.baerentsen.space/frederikbaerentsen/bricktracker:latest
-    ports:
-      - "3333:3333"
-    volumes:
-      - ./static/parts:/app/static/parts
-      - ./static/instructions:/app/static/instructions
-      - ./static/sets:/app/static/sets
-      - ./static/minifigs:/app/static/minifigs
-      - ./app.db:/app/app.db
-    environment:
-      - REBRICKABLE_API_KEY=your_api_key_here
-      - DOMAIN_NAME=https://your.domain.com
-      - LINKS=True #optional, enables set numbers to be Rebrickable links on the front page
-      - RANDOM=False #optional, set to True if you want your front page to be shuffled on load
-```
-
-If using locally, set `DOMAIN_NAME` to `http://localhost:3333`.
-
-3. Deploy with Docker Compose:
-```bash
-docker compose up -d
-```
-
-4. Access the web interface at `http://localhost:3333`
-
-5. The database is created, csv files are downloaded and you will be redirected to the `/create` page for inputting a set number.
-
-6. csv files are downloaded inside the container. If you delete the container, go to `/config` and redownload them again. 
 
 ## Usage
 
-### Adding Sets
+See [first steps](docs/first-steps.md).
-1. Go to the Create page
-2. Enter a LEGO set number (e.g., "42115")
-3. Wait for the set to be downloaded and processed
 
-### Managing Sets
+## Documentation
-- Mark sets as checked/collected using the checkboxes
-- Track missing pieces by entering quantities in the parts table
-    - Note, the checkbox for missing pieces is updated automatically, if the set has missing pieces. It cannot be manually checked off.
-- View all missing pieces across sets in the Missing page
-- View complete parts inventory in the Parts page
-- View all minifigures in the Minifigures page
-
-### Instructions
-
-Instructions can be added to the `static/instructions` folder. Instructions **must** be named:
-
-- SetNumber.pdf: `10312-1.pdf` or `7001-1.pdf`. Sets with multiple versions (eg. collectible minifigures use `-1`, `-2` etc) like `71039-1.pdf` and `71039-2.pdf`.
-- SetNumber-pdf_number.pdf: `10294-1-1.pdf`, `10294-1-2.pdf` and `10294-1-3.pdf` for all three PDFs of the `10294-1` set.
-
-Instructions are not automatically downloaded!
-
-Instructions can be uploaded from the webinterface (desktop-only) using the `Upload` button in the navbar. 
-
-## Docker Configuration
-
-The application uses two main configuration files:
-
-### docker-compose.yml
-```yaml
-services:
-  bricktracker:
-    container_name: BrickTracker
-    restart: unless-stopped
-    build: .
-    ports:
-      - "3333:3333"
-    volumes:
-      - .:/app
-    env_file:
-      - .env
-```
-
-### Dockerfile
-```dockerfile
-FROM python:slim
-WORKDIR /app
-COPY requirements.txt .
-RUN pip install -r requirements.txt
-COPY . .
-RUN bash lego.sh
-CMD ["gunicorn","--bind","0.0.0.0:3333","app:app","--worker-class","eventlet"]
-```
-
-## Development
-
-The application is built with:
-- Flask (Python web framework)
-- SQLite (Database)
-- Socket.IO (Real-time updates)
-- Rebrickable API (LEGO data)
-
-Key files:
-- `app.py`: Main application code
-- `db.py`: Database operations
-- `downloadRB.py`: Rebrickable data download utilities
-
-## Notes
-
-- The application stores images locally in the `static` directory
-- Database is stored in `app.db` (SQLite)
-- LEGO data is cached in CSV files from Rebrickable
-- Images are downloaded from Rebrickable when entering a set and then stored locally.
-- The code is AS-IS! I am not a professional programmer and this has been a hobby projects for a long time. Don't expect anything neat! 
-
-## Screenshots
-
-### Front page 
-![](https://xbackbone.baerentsen.space/LaMU8/koLAhiWe94.png/raw)
-
-Search your inventory and sort by theme, year, parts, id, name or sort by missing pieces. If you download instructions as PDF, add them to a specific folder and they show up [under each set](https://xbackbone.baerentsen.space/LaMU8/ZIyIQUdo31.png/raw)
-
-### Inventory
-
-![](https://xbackbone.baerentsen.space/LaMU8/MeXaYuVI44.png/raw)
-
-Filter by color, quantity, name. Add if a piece is missing. Press images to [show them](https://xbackbone.baerentsen.space/LaMU8/FIFOQicE66.png/raw). Filter by only [missing pieces](https://xbackbone.baerentsen.space/LaMU8/LUQeTETA28.png). Minifigures and their parts are listed [at the end](https://xbackbone.baerentsen.space/LaMU8/nEPujImi75.png/raw).
-
-### Missing pieces
-
-![](https://xbackbone.baerentsen.space/LaMU8/YEPEKOsE50.png/raw)
-
-List of all your missing pieces, with links to bricklink and rebrickable. 
-
-### All parts
-
-![](https://xbackbone.baerentsen.space/LaMU8/TApONAkA94.png/raw)
-List of all parts in your inventory.
-
-### Minifigures
-
-![](https://xbackbone.baerentsen.space/LaMU8/RuWoduFU08.png/raw)
-
-List of all minifigures in your inventory and quantity.
-
-### Multiple sets
-
-![](https://xbackbone.baerentsen.space/LaMU8/BUHAYOYe40.png/raw)
-
-Each set is given a unique ID, such that you can have multiple copies of a set with different pieces missing in each copy. Sets can also easily be [deleted](https://xbackbone.baerentsen.space/LaMU8/xeroHupE22.png/raw) from the inventory. 
-
-### Add set
-
-![](https://xbackbone.baerentsen.space/LaMU8/lAlUcOhE38.png/raw)
-
-Sets are added from rebrickable using your own API key. Set numbers are checked against sets.csv from rebrickable and can be updated from the [config page](https://xbackbone.baerentsen.space/LaMU8/lErImaCE12.png/raw). When a set is added, all images from rebrickable are downloaded and stored locally, so if multiple sets contains the same part/color, only one image is downloaded and stored. This also make no calls to rebrickable when just browsing and using the site. Only time rebrickable to used it when up adding a new set. 
-
-### Wishlist
-
-![](https://xbackbone.baerentsen.space/LaMU8/qUYeHAKU93.png/raw)
-
-Sets are added from rebrickable and again checked against sets.csv. If you can't add a brand new set, consider updating your data from the [`/config` page](https://xbackbone.baerentsen.space/LaMU8/lErImaCE12.png/raw). Press the delete button to remove a set. Known Issue: If multiple sets of the same number is added, they will all be deleted.
-
-Wishlist uses *unofficial* retirement data. 
-
-Each set number, links to bricklink for pricecheck. 
 
+Most of the pages should be self explanatory to use.
+However, you can find more specific documentation in the [docs](docs/) folder.
 
+You can find screenshots of the application in the [bricktracker](docs/bricktracker.md) documentation file.

compose.legacy.yml

@@ -0,0 +1,18 @@
+services:
+  bricktracker:
+    container_name: BrickTracker
+    restart: unless-stopped
+    image: gitea.baerentsen.space/frederikbaerentsen/bricktracker:1.0.0
+    ports:
+      - "3333:3333"
+    volumes:
+      - ./static/parts:/app/static/parts
+      - ./static/instructions:/app/static/instructions
+      - ./static/sets:/app/static/sets
+      - ./static/minifigs:/app/static/minifigs
+      - ./app.db:/app/app.db
+    environment:
+      - REBRICKABLE_API_KEY=your_api_key_here
+      - DOMAIN_NAME=https://your.domain.com
+      - LINKS=True #optional, enables set numbers to be Rebrickable links on the front page
+      - RANDOM=False #optional, set to True if you want your front page to be shuffled on load

compose.local.yaml

@@ -0,0 +1,22 @@
+services:
+  bricktracker:
+    container_name: BrickTracker
+    restart: unless-stopped
+    build: .
+    ports:
+      - "3334:3333"
+    volumes:
+      - ./local:/local
+      - ./local/instructions:/app/static/instructions/
+      - ./local/minifigures:/app/static/minifigures/
+      - ./local/parts:/app/static/parts/
+      - ./local/sets:/app/static/sets/
+    environment:
+      BK_DEBUG: true
+      BK_DATABASE_PATH: /local/app.db
+      BK_INSTRUCTIONS_FOLDER: instructions
+      BK_MINIFIGURES_FOLDER: minifigures
+      BK_PARTS_FOLDER: parts
+      BK_RETIRED_SETS_PATH: /local/retired_sets.csv
+      BK_SETS_FOLDER: sets
+      BK_THEMES_PATH: /local/themes.csv

compose.yaml

@@ -2,10 +2,26 @@ services:
   bricktracker:
     container_name: BrickTracker
     restart: unless-stopped
-    build: .
+    image: gitea.baerentsen.space/frederikbaerentsen/bricktracker:1.0.0
     ports:
       - "3333:3333"
     volumes:
-      - .:/app
+      - data:/data/
-    env_file:
+      - instructions:/app/static/instructions/
-      - .env
+      - minifigures:/app/static/minifigures/
+      - parts:/app/static/parts/
+      - sets:/app/static/sets/
+    # Or define those in your .env file
+    environment:
+      BK_DATABASE_PATH: /data/app.db
+      BK_MINIFIGURES_FOLDER: minifigures
+      BK_RETIRED_SETS_PATH: /data/retired_sets.csv
+      BK_THEMES_PATH: /data/themes.csv
+    env_file: ".env"
+
+volumes:
+  data:
+  instructions:
+  minifigures:
+  parts:
+  sets:

docs/authentication.md

@@ -0,0 +1,55 @@
+# Authentication
+
+> **Note**<br>
+> The following page is based on version `1.0.0` of BrickTracker.
+
+> **Warning**<br>
+> This is a lightweight access control feature and does not provide any strong layer of security to the application.
+
+By default, every feature of the application is available.
+Although it does not support individual accounts, it is possible to protect every "dangerous" feature under a password.
+This can be useful if you want other people to access your inventory of sets in a "read-only" fashion.
+
+To set up the authentication, you need to set the two following environment variables:
+
+- `BK_AUTHENTICATION_KEY`: a secret for the server to encrypt the session cookie. See [.env.sample](../.env.sample) for how to generate the value
+- `BK_AUTHENTICATION_PASSWORD`: the actual password
+
+> **Warning**<br>
+> The password is stored in **plaintext**. Be mindful.
+
+Once the authentication is set up, you should see a ![read-only](images/authentication-01.png) pill on the right side of the menu bar.
+
+
+
+If you click on it, or if you try to access a page requiring authentication, you will not be greeted with a login prompt.
+
+![](images/authentication-02.png)
+
+Once authenticated the pill will switch to ![authenticated](images/authentication-03.png).
+
+## Login out
+
+If you need to log out, click the ![authenticated](images/authentication-03.png) pill.
+Then press the **Logout** button in the Admin page.
+
+![](images/authentication-05.png)
+
+## Features require authentication
+
+If set up, the following will require an authentication:
+
+- Sets
+    - Add
+    - Bulk add
+    - Delete
+    - Change status
+    - Change the amount of missing parts
+- Instructions
+    - Upload
+    - Rename
+    - Delete
+- Wishlist
+    - Add
+    - Delete
+- Admin

docs/bricktracker.md

@@ -0,0 +1,130 @@
+# BrickTracker
+
+> **Note**<br>
+> The following page is based on version `1.0.0` of BrickTracker.
+
+## Frontpage
+
+![](images/bricktracker-01.png)
+
+If you are using `BK_RANDOM`, a random selection of sets and minifigures.
+Otherwise, the latest added sets and minifigures.
+
+You can click the card name or image to access a set or minifigure detail.
+
+## Sets
+
+> **Info**<br>
+> This does not do any pagination and loads **everything**. It can be slow depending on how many sets you have.
+
+![](images/bricktracker-02.png)
+
+Displays all your sets, with quick look at theme, year, parts, missing parts, minifigures count and status.
+You can search, filter and sort the grid. The sort order will be stored in a cookie and re-use on next page load.
+
+You can click the card name or image to access a set detail.
+
+### Multiple sets
+
+Each added set has a unique ID and you can have multiple copies of the same set added to your inventory.
+
+![](images/bricktracker-13.png)
+
+## Set details
+
+![](images/bricktracker-03.png)
+
+Gives you more detail about a specific set, including instructions and parts list.
+
+## Minifigure details
+
+![](images/bricktracker-04.png)
+
+Gives you generic detail about a minifigure across all your sets.
+
+## Part details
+
+![](images/bricktracker-05.png)
+
+Gives you generic detail about a part across all your sets.
+
+## Add
+
+![](images/bricktracker-09.png)
+
+If you are authenticated, lets you add a new set to your inventory.
+See [first steps](first-steps.md).
+
+### Bulk add
+
+![](images/bricktracker-10.png)
+
+If you need to add many sets at once, you can use the bulk add tool.
+Instead of a set number, it takes a comma separated list of set numbers.
+It will then process each number of the list sequentially as if you were doing it yourself one by one.
+If an error occur, it will put back in the input field the list of number that were not processed.
+
+## Parts
+
+> **Info**<br>
+> This does not do any pagination and loads **everything**. It can be slow depending on how many sets you have.
+
+![](images/bricktracker-06.png)
+
+Lists all your parts with details on quantity missing, number of sets missing it, number of minifigures missing it.
+You can sort columns, and search the table.
+
+Clicking on a part image will open it fullscreen.
+Clicking on a part name will load its details.
+
+## Missing (parts)
+
+> **Info**<br>
+> This does not do any pagination and loads **everything**. It can be slow depending on how missing parts you have.
+
+![](images/bricktracker-07.png)
+
+Lists all your missing parts with details on total quantity, quantity missing, number of sets using it, number of minifigures using it.
+You can sort columns, and search the table.
+
+Clicking on a part image will open it fullscreen.
+Clicking on a part name will load its details.
+
+## Minifigures
+
+> **Info**<br>
+> This does not do any pagination and loads **everything**. It can be slow depending on how many minifigures you have.
+
+![](images/bricktracker-08.png)
+
+Lists all your minifigures with details on quantity missing, number of missing parts, number of sets using it.
+You can sort columns, and search the table.
+
+Clicking on a minifigure image will open it fullscreen.
+Clicking on a minifigure name will load its details.
+
+## Instructions
+
+> **Info**<br>
+> This does not do any pagination and loads **everything**. It can be slow depending on how many instructions you have.
+
+![](images/bricktracker-08.png)
+
+Lists all your instructions and if they are matching a existing set, will display its name and image.
+If you are authenticated, you can upload new instruction files, rename existing ones or delete them.
+You can sort columns, and search the table.
+
+Clicking on a set image will open it fullscreen.
+
+## Wishlist
+
+> **Info**<br>
+> This does not do any pagination and loads **everything**. It can be slow depending on how many wished sets you have.
+
+![](images/bricktracker-12.png)
+
+Lists all your wished with details on theme, year, parts and *unofficial* retirement date.
+If you are authenticated, you can add new wished sets or delete existing ones.
+You can sort columns, and search the table.
+
+Clicking on a set image will open it fullscreen.

docs/common-errors.md

@@ -0,0 +1,84 @@
+# Common errors/problems
+
+> **Note**<br>
+> The following page is based on version `1.0.0` of BrickTracker.
+
+## I need a password to access some pages
+
+You have setup lightweight authentication. Your password is in your environement `BK_AUTHENTICATION_PASSWORD` variable.
+
+## I cannot access the Add page (Configuration missing!)
+
+![](images/common-errors-01.png)
+
+You need to pass the `BK_REBRICKABLE_API_KEY` environment to your application, depending on how you run the application.
+For instance:
+
+- Docker: `docker run -e BK_REBRICKABLE_API_KEY=xxxx`
+- Docker compose (directly in `compose.yaml`):
+
+```
+services:
+  bricktracker:
+    environment:
+      - BK_AUTHENTICATION_KEY=xxxx
+```
+
+- Docker compose (with an environement file, for instance `.env`)
+
+```
+-- .env
+BK_AUTHENTICATION_KEY=xxxx
+
+-- compose.yaml
+services:
+  bricktracker:
+    env_file: ".env"
+```
+
+> **Warning**<br>
+> Do not use quotes (", ') around your environment variables.
+> Docker will interpret them has being part of the **value** of the environment variable.
+> For instance...
+>
+> ```
+> services:
+>  bricktracker:
+>    environment:
+>      - BK_AUTHENTICATION_KEY="xxxx"
+> ```
+>
+> ...will make Docker believe that your API key is `"xxxx"`.
+
+## The socket is disconnected
+
+![](images/common-errors-02.png)
+
+If you are seeing the socket disconnected while you are on the **Add** or **Bulk add** pages, it can mean:
+
+- The application is not running anymore (it somehow stopped after you accessed the page): check that the application is running and its log for errors,
+- You restarted the application and it can take some time for the socket to be back up: just wait a bit it should automatically re-connect,
+- You are using the CORS allowed origin restriction (via the `BK_DOMAIN_NAME` environment variable) with a mismatching value: you should see a log line similar to this following one in your application logs.
+
+```
+http://127.0.0.1:3333 is not an accepted origin. (further occurrences of this error will be logged with level INFO)
+[2025-01-18 18:15:52,980] ERROR - http://127.0.0.1:3333 is not an accepted origin. (further occurrences of this error will be logged with level INFO)
+```
+
+Make sure the value you have set is matching the URL of your application.
+If it is not the case, adjust the value and restart the application.
+
+
+## No such file or directory: '<path>' when adding a set
+
+![](images/common-errors-03.png)
+
+The application doestake care of creating folders for static images and expects them to be writable.
+Make sure that the folder exists, and if it exists that it is writable by the application.
+
+## I'm seeing Unknown (<number>) instead of the set theme
+
+![](images/common-errors-04.png)
+
+Either the theme is too recent for your version of the themes file, or your theme file has not be initialized.
+Head to the **Admin** page, **Themes** section and update the file.

docs/development.md

@@ -0,0 +1,47 @@
+# Development
+
+> **Note**<br>
+> The following page is based on version `1.0.0` of BrickTracker.
+
+The application is written in Python version 3.
+It uses:
+
+- `flask` (Web framework)
+- `flask_socketio` (Socket.IO: Websocket library for real-time client-server communication)
+- `flask-login` (Lightweight Flask authentication library)
+- `sqlite3` (Light database management system)
+- `rebrick` API (Library to interact with the Rebrickable.com API)
+
+## Running a local debug instance
+
+You can use the [compose.local.yaml](../compose.local.yaml) file to build and run an instance with debug enabled and on a different port (`3334`).
+
+```
+$ mkdir local
+
+$ docker compose -f compose.local.yaml build
+[+] Building 0.6s (10/10) FINISHED                                                                                                         docker:default
+ => [bricktracker internal] load build definition from Dockerfile                                                                                    0.0s
+ => => transferring dockerfile: 211B                                                                                                                 0.0s
+ => [bricktracker internal] load metadata for docker.io/library/python:3-slim                                                                        0.4s
+ => [bricktracker internal] load .dockerignore                                                                                                       0.0s
+ => => transferring context: 307B                                                                                                                    0.0s
+ => [bricktracker 1/4] FROM docker.io/library/python:3-slim@sha256:23a81be7b258c8f516f7a60e80943cace4350deb8204cf107c7993e343610d47                  0.0s
+ => [bricktracker internal] load build context                                                                                                       0.0s
+ => => transferring context: 9.02kB                                                                                                                  0.0s
+ => CACHED [bricktracker 2/4] WORKDIR /app                                                                                                           0.0s
+ => CACHED [bricktracker 3/4] COPY . .                                                                                                               0.0s
+ => CACHED [bricktracker 4/4] RUN pip --no-cache-dir install -r requirements.txt                                                                     0.0s
+ => [bricktracker] exporting to image                                                                                                                0.0s
+ => => exporting layers                                                                                                                              0.0s
+ => => writing image sha256:5e913b01b10a51afae952187a45593d4c4a35635d084c8e9ba012476f21b2d0b                                                         0.0s
+ => => naming to docker.io/library/bricktracker-bricktracker                                                                                         0.0s
+ => [bricktracker] resolving provenance for metadata file                                                                                            0.0s
+
+$ docker compose -f compose.local.yaml up -d
+[+] Running 2/2
+ ✔ Network bricktracker_default  Created                                                                                                             0.4s
+ ✔ Container BrickTracker        Started                                                                                                            11.2s
+```
+
+You should have the app available on port `3334` (not `3333`!). For instance at http://127.0.0.1:3334.

docs/first-steps.md

@@ -0,0 +1,70 @@
+# First steps
+
+> **Note**<br>
+> The following page is based on version `1.0.0` of BrickTracker.
+
+## Database initialization
+
+Once the application is running and you can access it, you should be greated with an error message.
+This is perfectly normal as you are running the application for the first time and you need to initialize the database.
+
+![](images/first-steps-01.png)
+
+Click the **Administration** button to access the administration panel.
+The **Database** section should be opened by default.
+
+![](images/first-steps-02.png)
+
+Press the **Initialize the database** button.
+
+![](images/first-steps-03.png)
+
+## Themes initialization
+
+To have the themes identifier resolved into names, you need to do an initial update of the file.
+Open the **Themes** section.
+You will see an error message, this is expected.
+
+![](images/first-steps-07.png)
+
+Press the **Update the themes file** button to download an initial version of the themes file.
+
+![](images/first-steps-08.png)
+
+If everything went well you should see no more error message and some counters.
+
+## Add a set
+
+> **Important**<br>
+> Make sure you have set up your Rebrickable API key (`BK_REBRICKABLE_KEY`) for this to work (see [common errors](common-errors.md)).
+
+> **Important**<br>
+> If you are using the CORS allowed origin restriction (`BK_DOMAIN_NAME`), make sure it is matching your application URL (see [common errors](common-errors.md)).
+
+Use the menu bar to navigate to the **Add** page, make sure the socket is in a **connected** state.
+
+![](images/first-steps-04.png)
+
+Input a set number in the **Set number** field and press the **Add** button.
+You can either use the set number (e.g `608`) and it will automitcally assume that you want version `1` (e.g `608-1`),
+or you can use the complete number with the version (e.g `608-2`)
+
+It will load information about the set you are about to add, but not add it yet.
+
+![](images/first-steps-05.png)
+
+Use the **Confirm add** button to add the set, or the **Dismiss** button if it is not the one you wanted.
+
+> **Note**<br>
+> If you do not want to go through the confirmation process, check the **Add without confirmation** checkbox and the
+> set will be added when you press the **Add** button.
+
+![](images/first-steps-06.png)
+
+If everything goes well you should see a **Success** message with a direct link to your set.
+
+![](images/first-steps-09.png)
+
+## Learn more
+
+Consult the rest of the files in the [docs](.) folder.

docs/set.md

@@ -0,0 +1,62 @@
+# Managing your sets
+
+> **Note**<br>
+> The following page is based on version `1.0.0` of BrickTracker.
+
+## Set image
+
+If you click the set image, it will open fullscreen.
+
+![](images/set-06.png)
+
+## Set status
+
+You can track the following status for your sets:
+
+- Set is checked
+- Set is collected
+- Set minifigures are collected
+
+Simply click on the checkbox or label wherever applicable and it will be immediately saved to the database.
+A little status mark tells you if the operation was successful.
+
+![](images/set-01.png)
+
+# Instructions
+
+If you have uploaded instructions with a name matching the set, they will be available to consult on the set page.
+
+![](images/set-04.png)
+
+## Parts list
+
+When displaying a set, you can see the list of parts making the set.
+For each part, you can mark how many of those pieces are missing.
+As soon as you leave the field it will be immediately saved to the database.
+A little status mark tells you if the operation was successful.
+
+![](images/set-02.png)
+
+You can sort the part list by clicking the header of each column of the table.
+
+![](images/set-03.png)
+
+If you click a part image, it will open fullscreen.
+
+![](images/set-05.png)
+
+## Minifigures list
+
+If the set includes minifigures, they will be least after the parts list.
+For each minifigure kind, you will see the number of minifigures and their part list.
+The part list works exactly like the set parts list.
+
+![](images/set-07.png)
+
+If you click the minifigure image near the **Details** button, it will open fullscreen.
+
+![](images/set-08.png)
+
+You can also check the details of the minifigure pressing by clicking on the **Details** button.
+
+![](images/set-09.png)

docs/setup.md

@@ -0,0 +1,94 @@
+# Setup
+
+> **Note**<br>
+> The following page is based on version `1.0.0` of BrickTracker.
+
+## Prerequisites
+
+Check your operating system documentation to install `docker` and `docker compose`.
+
+## A note on environment variables
+
+You need to pass the `BK_<name>` environment to your application, depending on how you run the application.
+For instance:
+
+- Docker: `docker run -e BK_<name>=xxxx`
+- Docker compose (directly in `compose.yaml`):
+
+```
+services:
+  bricktracker:
+    environment:
+      - BK_<name>=xxxx
+```
+
+- Docker compose (with an environement file, for instance `.env`)
+
+```
+-- .env
+BK_<name>=xxxx
+
+-- compose.yaml
+services:
+  bricktracker:
+    env_file: ".env"
+```
+
+> **Warning**<br>
+> Do not use quotes (", ') around your environment variables.
+> Docker will interpret them has being part of the **value** of the environment variable.
+> For instance...
+>
+> ```
+> services:
+>  bricktracker:
+>    environment:
+>      - BK_AUTHENTICATION_KEY="xxxx"
+> ```
+>
+> ...will make Docker believe that your API key is `"xxxx"`.
+
+## Environment file and customization options
+
+The [.env.sample](../.env.sample) file provides ample documentation on all the configurable options. Have a look at it.
+You can make a copy of `.env.sample` as `.env` with your options or create an `.env` file from scratch.
+
+## Database file
+
+To accomodate for the original version of BrickTracker, the default database path is `./app.db`.
+This is not ideal for a setup with volumes because it is a single file.
+You can use a combination of a volume and the `BK_DATABASE_PATH` environment variable to accomodate for that.
+For instance:
+
+```
+services:
+  bricktracker:
+    volumes:
+      - database:/database/
+    environment:
+      BK_DATABASE_PATH: /database/app.db
+
+volumes:
+  database:
+```
+
+## Rebrickable API key
+
+Although not mandatory for the application to run, it is necessary to add any data to the application.
+It is set up with the `BK_REBRICKABLE_API_KEY` environment variable (or `REBRICKABLE_API_KEY` to accomodate for the original version of BrickTracker).
+
+## Static image and instructions files folders
+
+Since the images and instruction files are to be served by the webserver, it is expected they reside in the `/app/static` folder.
+You can control the name/path of each image type relative to `app/static` with the `BK_*_FOLDER` variables.
+
+## CSV files
+
+Some CSV files are used to resolve informations like theme names or retired set dates.
+In the original version of BrickTracker they were either shipped with the container or residing at the root of the application, meaning that any update to it would not survive a container update.
+
+You can use the `BK_RETIRED_SET_PATH` and `BK_THEMES_PATH` to relocate them into a volume.
+
+## Authentication
+
+See [authentication](authentication.md)