diff --git a/.gitignore b/.gitignore
index ba326ed..0d192d5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,6 +17,7 @@ static/sets/
# Temporary
*.csv
+/local/
# Apple idiocy
.DS_Store
diff --git a/README.md b/README.md
index 2a52b60..5b24ce5 100644
--- a/README.md
+++ b/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!**
-
## 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
-- Docker Compose
-- Rebrickable API key (from [Rebrickable](https://rebrickable.com/api/))
+Use the provided [compose.yaml](compose.yaml) file.
-## Setup
-
-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.
+See [setup](docs/setup.md).
## Usage
-### Adding Sets
-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
+See [first steps](docs/first-steps.md).
-### Managing Sets
-- 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
-
-
-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
-
-
-
-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
-
-
-
-List of all your missing pieces, with links to bricklink and rebrickable.
-
-### All parts
-
-
-List of all parts in your inventory.
-
-### Minifigures
-
-
-
-List of all minifigures in your inventory and quantity.
-
-### Multiple sets
-
-
-
-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
-
-
-
-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
-
-
-
-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.
+## Documentation
+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.
diff --git a/compose.legacy.yml b/compose.legacy.yml
new file mode 100644
index 0000000..adcb044
--- /dev/null
+++ b/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
diff --git a/compose.local.yaml b/compose.local.yaml
new file mode 100644
index 0000000..bf7a8d6
--- /dev/null
+++ b/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
diff --git a/compose.yaml b/compose.yaml
index 408e480..180a189 100644
--- a/compose.yaml
+++ b/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
- env_file:
- - .env
+ - data:/data/
+ - instructions:/app/static/instructions/
+ - 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:
diff --git a/docs/authentication.md b/docs/authentication.md
new file mode 100644
index 0000000..a49ad0a
--- /dev/null
+++ b/docs/authentication.md
@@ -0,0 +1,55 @@
+# Authentication
+
+> **Note**
+> The following page is based on version `1.0.0` of BrickTracker.
+
+> **Warning**
+> 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**
+> The password is stored in **plaintext**. Be mindful.
+
+Once the authentication is set up, you should see a  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.
+
+
+
+Once authenticated the pill will switch to .
+
+## Login out
+
+If you need to log out, click the  pill.
+Then press the **Logout** button in the Admin page.
+
+
+
+## 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
diff --git a/docs/bricktracker.md b/docs/bricktracker.md
new file mode 100644
index 0000000..9792f98
--- /dev/null
+++ b/docs/bricktracker.md
@@ -0,0 +1,130 @@
+# BrickTracker
+
+> **Note**
+> The following page is based on version `1.0.0` of BrickTracker.
+
+## Frontpage
+
+
+
+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**
+> This does not do any pagination and loads **everything**. It can be slow depending on how many sets you have.
+
+
+
+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.
+
+
+
+## Set details
+
+
+
+Gives you more detail about a specific set, including instructions and parts list.
+
+## Minifigure details
+
+
+
+Gives you generic detail about a minifigure across all your sets.
+
+## Part details
+
+
+
+Gives you generic detail about a part across all your sets.
+
+## Add
+
+
+
+If you are authenticated, lets you add a new set to your inventory.
+See [first steps](first-steps.md).
+
+### Bulk add
+
+
+
+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**
+> This does not do any pagination and loads **everything**. It can be slow depending on how many sets you have.
+
+
+
+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**
+> This does not do any pagination and loads **everything**. It can be slow depending on how missing parts you have.
+
+
+
+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**
+> This does not do any pagination and loads **everything**. It can be slow depending on how many minifigures you have.
+
+
+
+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**
+> This does not do any pagination and loads **everything**. It can be slow depending on how many instructions you have.
+
+
+
+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**
+> This does not do any pagination and loads **everything**. It can be slow depending on how many wished sets you have.
+
+
+
+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.
diff --git a/docs/common-errors.md b/docs/common-errors.md
new file mode 100644
index 0000000..91ebb49
--- /dev/null
+++ b/docs/common-errors.md
@@ -0,0 +1,84 @@
+# Common errors/problems
+
+> **Note**
+> 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!)
+
+
+
+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**
+> 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
+
+
+
+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: '' when adding a set
+
+
+
+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 () instead of the set theme
+
+
+
+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.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..752b4ba
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,47 @@
+# Development
+
+> **Note**
+> 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.
diff --git a/docs/first-steps.md b/docs/first-steps.md
new file mode 100644
index 0000000..b1e625e
--- /dev/null
+++ b/docs/first-steps.md
@@ -0,0 +1,70 @@
+# First steps
+
+> **Note**
+> 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.
+
+
+
+Click the **Administration** button to access the administration panel.
+The **Database** section should be opened by default.
+
+
+
+Press the **Initialize the database** button.
+
+
+
+## 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.
+
+
+
+Press the **Update the themes file** button to download an initial version of the themes file.
+
+
+
+If everything went well you should see no more error message and some counters.
+
+## Add a set
+
+> **Important**
+> Make sure you have set up your Rebrickable API key (`BK_REBRICKABLE_KEY`) for this to work (see [common errors](common-errors.md)).
+
+> **Important**
+> 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.
+
+
+
+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.
+
+
+
+Use the **Confirm add** button to add the set, or the **Dismiss** button if it is not the one you wanted.
+
+> **Note**
+> 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.
+
+
+
+If everything goes well you should see a **Success** message with a direct link to your set.
+
+
+
+## Learn more
+
+Consult the rest of the files in the [docs](.) folder.
diff --git a/docs/images/authentication-01.png b/docs/images/authentication-01.png
new file mode 100644
index 0000000..1a16ab7
Binary files /dev/null and b/docs/images/authentication-01.png differ
diff --git a/docs/images/authentication-02.png b/docs/images/authentication-02.png
new file mode 100644
index 0000000..b4fcb6a
Binary files /dev/null and b/docs/images/authentication-02.png differ
diff --git a/docs/images/authentication-03.png b/docs/images/authentication-03.png
new file mode 100644
index 0000000..21d28f4
Binary files /dev/null and b/docs/images/authentication-03.png differ
diff --git a/docs/images/authentication-05.png b/docs/images/authentication-05.png
new file mode 100644
index 0000000..49b5d85
Binary files /dev/null and b/docs/images/authentication-05.png differ
diff --git a/docs/images/bricktracker-01.png b/docs/images/bricktracker-01.png
new file mode 100644
index 0000000..6e3ce62
Binary files /dev/null and b/docs/images/bricktracker-01.png differ
diff --git a/docs/images/bricktracker-02.png b/docs/images/bricktracker-02.png
new file mode 100644
index 0000000..39019a3
Binary files /dev/null and b/docs/images/bricktracker-02.png differ
diff --git a/docs/images/bricktracker-03.png b/docs/images/bricktracker-03.png
new file mode 100644
index 0000000..5b4e3c4
Binary files /dev/null and b/docs/images/bricktracker-03.png differ
diff --git a/docs/images/bricktracker-04.png b/docs/images/bricktracker-04.png
new file mode 100644
index 0000000..10dbc9d
Binary files /dev/null and b/docs/images/bricktracker-04.png differ
diff --git a/docs/images/bricktracker-05.png b/docs/images/bricktracker-05.png
new file mode 100644
index 0000000..344b644
Binary files /dev/null and b/docs/images/bricktracker-05.png differ
diff --git a/docs/images/bricktracker-06.png b/docs/images/bricktracker-06.png
new file mode 100644
index 0000000..063e222
Binary files /dev/null and b/docs/images/bricktracker-06.png differ
diff --git a/docs/images/bricktracker-07.png b/docs/images/bricktracker-07.png
new file mode 100644
index 0000000..8c06c2c
Binary files /dev/null and b/docs/images/bricktracker-07.png differ
diff --git a/docs/images/bricktracker-08.png b/docs/images/bricktracker-08.png
new file mode 100644
index 0000000..8f71052
Binary files /dev/null and b/docs/images/bricktracker-08.png differ
diff --git a/docs/images/bricktracker-09.png b/docs/images/bricktracker-09.png
new file mode 100644
index 0000000..a8d610e
Binary files /dev/null and b/docs/images/bricktracker-09.png differ
diff --git a/docs/images/bricktracker-10.png b/docs/images/bricktracker-10.png
new file mode 100644
index 0000000..cfb8d7e
Binary files /dev/null and b/docs/images/bricktracker-10.png differ
diff --git a/docs/images/bricktracker-11.png b/docs/images/bricktracker-11.png
new file mode 100644
index 0000000..187fce8
Binary files /dev/null and b/docs/images/bricktracker-11.png differ
diff --git a/docs/images/bricktracker-12.png b/docs/images/bricktracker-12.png
new file mode 100644
index 0000000..492af33
Binary files /dev/null and b/docs/images/bricktracker-12.png differ
diff --git a/docs/images/bricktracker-13.png b/docs/images/bricktracker-13.png
new file mode 100644
index 0000000..d336c1d
Binary files /dev/null and b/docs/images/bricktracker-13.png differ
diff --git a/docs/images/common-errors-01.png b/docs/images/common-errors-01.png
new file mode 100644
index 0000000..d6963f9
Binary files /dev/null and b/docs/images/common-errors-01.png differ
diff --git a/docs/images/common-errors-02.png b/docs/images/common-errors-02.png
new file mode 100644
index 0000000..15cd595
Binary files /dev/null and b/docs/images/common-errors-02.png differ
diff --git a/docs/images/common-errors-03.png b/docs/images/common-errors-03.png
new file mode 100644
index 0000000..5d79773
Binary files /dev/null and b/docs/images/common-errors-03.png differ
diff --git a/docs/images/common-errors-04.png b/docs/images/common-errors-04.png
new file mode 100644
index 0000000..6348ea2
Binary files /dev/null and b/docs/images/common-errors-04.png differ
diff --git a/docs/images/first-steps-01.png b/docs/images/first-steps-01.png
new file mode 100644
index 0000000..927b19c
Binary files /dev/null and b/docs/images/first-steps-01.png differ
diff --git a/docs/images/first-steps-02.png b/docs/images/first-steps-02.png
new file mode 100644
index 0000000..749a480
Binary files /dev/null and b/docs/images/first-steps-02.png differ
diff --git a/docs/images/first-steps-03.png b/docs/images/first-steps-03.png
new file mode 100644
index 0000000..b8f83ca
Binary files /dev/null and b/docs/images/first-steps-03.png differ
diff --git a/docs/images/first-steps-04.png b/docs/images/first-steps-04.png
new file mode 100644
index 0000000..c1942b1
Binary files /dev/null and b/docs/images/first-steps-04.png differ
diff --git a/docs/images/first-steps-05.png b/docs/images/first-steps-05.png
new file mode 100644
index 0000000..3a27961
Binary files /dev/null and b/docs/images/first-steps-05.png differ
diff --git a/docs/images/first-steps-06.png b/docs/images/first-steps-06.png
new file mode 100644
index 0000000..9381efa
Binary files /dev/null and b/docs/images/first-steps-06.png differ
diff --git a/docs/images/first-steps-07.png b/docs/images/first-steps-07.png
new file mode 100644
index 0000000..0af61f8
Binary files /dev/null and b/docs/images/first-steps-07.png differ
diff --git a/docs/images/first-steps-08.png b/docs/images/first-steps-08.png
new file mode 100644
index 0000000..f1ef9f4
Binary files /dev/null and b/docs/images/first-steps-08.png differ
diff --git a/docs/images/first-steps-09.png b/docs/images/first-steps-09.png
new file mode 100644
index 0000000..704189e
Binary files /dev/null and b/docs/images/first-steps-09.png differ
diff --git a/docs/images/set-01.png b/docs/images/set-01.png
new file mode 100644
index 0000000..d37a99b
Binary files /dev/null and b/docs/images/set-01.png differ
diff --git a/docs/images/set-02.png b/docs/images/set-02.png
new file mode 100644
index 0000000..773b4f0
Binary files /dev/null and b/docs/images/set-02.png differ
diff --git a/docs/images/set-03.png b/docs/images/set-03.png
new file mode 100644
index 0000000..15efc3d
Binary files /dev/null and b/docs/images/set-03.png differ
diff --git a/docs/images/set-04.png b/docs/images/set-04.png
new file mode 100644
index 0000000..f97d726
Binary files /dev/null and b/docs/images/set-04.png differ
diff --git a/docs/images/set-05.png b/docs/images/set-05.png
new file mode 100644
index 0000000..246c1e4
Binary files /dev/null and b/docs/images/set-05.png differ
diff --git a/docs/images/set-06.png b/docs/images/set-06.png
new file mode 100644
index 0000000..f3069c1
Binary files /dev/null and b/docs/images/set-06.png differ
diff --git a/docs/images/set-07.png b/docs/images/set-07.png
new file mode 100644
index 0000000..50bbfe5
Binary files /dev/null and b/docs/images/set-07.png differ
diff --git a/docs/images/set-08.png b/docs/images/set-08.png
new file mode 100644
index 0000000..26a2c65
Binary files /dev/null and b/docs/images/set-08.png differ
diff --git a/docs/images/set-09.png b/docs/images/set-09.png
new file mode 100644
index 0000000..385ae50
Binary files /dev/null and b/docs/images/set-09.png differ
diff --git a/docs/set.md b/docs/set.md
new file mode 100644
index 0000000..eba2183
--- /dev/null
+++ b/docs/set.md
@@ -0,0 +1,62 @@
+# Managing your sets
+
+> **Note**
+> The following page is based on version `1.0.0` of BrickTracker.
+
+## Set image
+
+If you click the set image, it will open fullscreen.
+
+
+
+## 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.
+
+
+
+# Instructions
+
+If you have uploaded instructions with a name matching the set, they will be available to consult on the set page.
+
+
+
+## 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.
+
+
+
+You can sort the part list by clicking the header of each column of the table.
+
+
+
+If you click a part image, it will open fullscreen.
+
+
+
+## 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.
+
+
+
+If you click the minifigure image near the **Details** button, it will open fullscreen.
+
+
+
+You can also check the details of the minifigure pressing by clicking on the **Details** button.
+
+
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 0000000..a058233
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,94 @@
+# Setup
+
+> **Note**
+> 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_` environment to your application, depending on how you run the application.
+For instance:
+
+- Docker: `docker run -e BK_=xxxx`
+- Docker compose (directly in `compose.yaml`):
+
+```
+services:
+ bricktracker:
+ environment:
+ - BK_=xxxx
+```
+
+- Docker compose (with an environement file, for instance `.env`)
+
+```
+-- .env
+BK_=xxxx
+
+-- compose.yaml
+services:
+ bricktracker:
+ env_file: ".env"
+```
+
+> **Warning**
+> 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)