Update changelog

README.md

@@ -18,7 +18,9 @@ A web application for organizing and tracking LEGO sets, parts, and minifigures.
 
 Use the provided [compose.yaml](compose.yaml) file.
 
-See [setup](docs/setup.md).
+See [Quickstart](docs/quickstart.md) to get up and running right away.
+
+See [Setup](docs/setup.md) for a more setup guide.
 
 ## Usage
 

docs/DOCS.md

@@ -9,6 +9,7 @@ This page helps you navigate the documentation of BrickTracker.
 ## Installation
 
 - [Setup](setup.md)
+- [Variables overview](env.md)
 
 ## Usage
 

docs/env.md

@@ -0,0 +1,108 @@
+# Environment Variables Reference
+
+## Essential Variables
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_REBRICKABLE_API_KEY` | Rebrickable API key | None | Yes |
+
+## Common Configuration
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_DATABASE_PATH` | SQLite database path | `./app.db` | No |
+| `BK_PORT` | Server port | `3333` | No |
+| `BK_HOST` | Server host address | `0.0.0.0` | No |
+| `BK_DEBUG` | Enable debug mode | `false` | No |
+| `BK_USE_REMOTE_IMAGES` | Use remote images | `false` | No |
+| `BK_DEFAULT_TABLE_PER_PAGE` | Items per page | `25` | No |
+| `BK_TIMEZONE` | Timezone | `Etc/UTC` | No |
+
+## UI Customization
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_HIDE_ADMIN` | Hide admin menu entry | `false` | No |
+| `BK_HIDE_ADD_SET` | Hide 'Add' menu entry | `false` | No |
+| `BK_HIDE_ADD_BULK_SET` | Hide bulk add option | `false` | No |
+| `BK_HIDE_ALL_SETS` | Hide sets menu entry | `false` | No |
+| `BK_HIDE_ALL_PARTS` | Hide parts menu entry | `false` | No |
+| `BK_HIDE_ALL_MINIFIGURES` | Hide minifigures menu entry | `false` | No |
+| `BK_HIDE_ALL_INSTRUCTIONS` | Hide instructions menu entry | `false` | No |
+| `BK_HIDE_MISSING_PARTS` | Hide missing parts menu entry | `false` | No |
+| `BK_HIDE_WISHES` | Hide wishlist menu entry | `false` | No |
+| `BK_INDEPENDENT_ACCORDIONS` | Make accordions independent | `false` | No |
+
+## Sort Order Configuration
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_SETS_DEFAULT_ORDER` | Default set sorting | `"rebrickable_sets"."number" DESC` | No |
+| `BK_PARTS_DEFAULT_ORDER` | Default part sorting | `"inventory"."name" ASC` | No |
+| `BK_MINIFIGURES_DEFAULT_ORDER` | Default minifig sorting | `"minifigures"."name" ASC` | No |
+| `BK_WISHES_DEFAULT_ORDER` | Default wishlist sorting | `"bricktracker_wishes"."rowid" DESC` | No |
+
+## External Links Configuration
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_REBRICKABLE_LINKS` | Show Rebrickable links | `false` | No |
+| `BK_BRICKLINK_LINKS` | Show BrickLink links | `false` | No |
+| `BK_BRICKLINK_LINK_PART_PATTERN` | BrickLink part URL pattern | `https://www.bricklink.com/v2/catalog/catalogitem.page?P={number}` | No |
+| `BK_REBRICKABLE_LINK_PART_PATTERN` | Rebrickable part URL pattern | `https://rebrickable.com/parts/{number}/_/{color}` | No |
+| `BK_REBRICKABLE_LINK_MINIFIGURE_PATTERN` | Rebrickable minifig URL pattern | `https://rebrickable.com/minifigs/{number}` | No |
+| `BK_REBRICKABLE_LINK_INSTRUCTIONS_PATTERN` | Rebrickable instructions URL pattern | `https://rebrickable.com/instructions/{path}` | No |
+
+## File Storage Configuration
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_INSTRUCTIONS_FOLDER` | Instructions storage path | `instructions` | No |
+| `BK_MINIFIGURES_FOLDER` | Minifigures storage path | `minifigs` | No |
+| `BK_PARTS_FOLDER` | Parts storage path | `parts` | No |
+| `BK_SETS_FOLDER` | Sets storage path | `sets` | No |
+| `BK_INSTRUCTIONS_ALLOWED_EXTENSIONS` | Allowed instruction file types | `.pdf` | No |
+
+## API and Network Configuration
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_DOMAIN_NAME` | CORS origin restriction | None | No |
+| `BK_REBRICKABLE_PAGE_SIZE` | Items per API call | `100` | No |
+| `BK_SOCKET_NAMESPACE` | Socket.IO namespace | `bricksocket` | No |
+| `BK_SOCKET_PATH` | Socket.IO path | `/bricksocket/` | No |
+| `BK_NO_THREADED_SOCKET` | Disable socket threading | `false` | No |
+| `BK_REBRICKABLE_USER_AGENT` | Custom User-Agent | `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36` | No |
+
+## External Data Sources
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_RETIRED_SETS_FILE_URL` | Retired sets list URL | `https://docs.google.com/spreadsheets/d/1rlYfEXtNKxUOZt2Mfv0H17DvK7bj6Pe0CuYwq6ay8WA/gviz/tq?tqx=out:csv&sheet=Sorted%20by%20Retirement%20Date` | No |
+| `BK_RETIRED_SETS_PATH` | Local retired sets file path | `./retired_sets.csv` | No |
+| `BK_THEMES_FILE_URL` | Themes list URL | `https://cdn.rebrickable.com/media/downloads/themes.csv.gz` | No |
+| `BK_THEMES_PATH` | Local themes file path | `./themes.csv` | No |
+| `BK_REBRICKABLE_IMAGE_NIL` | Missing image placeholder | `https://rebrickable.com/static/img/nil.png` | No |
+| `BK_REBRICKABLE_IMAGE_NIL_MINIFIGURE` | Missing minifig placeholder | `https://rebrickable.com/static/img/nil_mf.jpg` | No |
+
+## Behavior Configuration
+| Variable | Purpose | Default | Required |
+|----------|---------|----------|-----------|
+| `BK_RANDOM` | Shuffle front page lists | `false` | No |
+| `BK_SKIP_SPARE_PARTS` | Ignore spare parts | `false` | No |
+| `BK_DATABASE_TIMESTAMP_FORMAT` | Backup timestamp format | `%Y-%m-%d-%H-%M-%S` | No |
+| `BK_AUTHENTICATION_KEY` | Secret key for auth tokens | None | If using authentication |
+| `BK_AUTHENTICATION_PASSWORD` | Admin area password | None | No |
+
+## Sort Order Examples
+```bash
+# Sort sets by year ascending
+BK_SETS_DEFAULT_ORDER="rebrickable_sets"."year" ASC
+
+# Sort parts by missing count descending
+BK_PARTS_DEFAULT_ORDER="total_missing" DESC, "inventory"."name" ASC
+
+# Sort minifigures by ID
+BK_MINIFIGURES_DEFAULT_ORDER="minifigures"."fig_num" ASC
+
+# Sort wishlist by set number
+BK_WISHES_DEFAULT_ORDER="bricktracker_wishes"."set" ASC
+```
+
+## File Extensions Example
+```bash
+# Allow multiple instruction file types
+BK_INSTRUCTIONS_ALLOWED_EXTENSIONS=.pdf, .docx, .png
+```

docs/first-steps.md

@@ -1,7 +1,7 @@
 # First steps
 
 > **Note**
-> The following page is based on version `1.0.0` of BrickTracker.
+> The following page is based on version `1.1.1` of BrickTracker.
 
 ## Database initialization
 

docs/quickstart.md

@@ -0,0 +1,90 @@
+# Quickstart
+
+> **Note**
+> The following page is based on version `1.1.1` of BrickTracker.
+
+## Prerequisites
+- Docker and Docker Compose installed
+- A Rebrickable API key from https://rebrickable.com/users/profile/
+- curl or wget (for downloading configuration files)
+
+## Note on Environment Configuration
+BrickTracker can be configured using either:
+- A `.env` file (recommended and shown in this guide)
+- Environment variables in compose.yaml
+
+This guide uses the `.env` file approach for better maintainability. The environment variables in the compose.yaml file are kept minimal and only reference the essential paths.
+
+## Directory Setup
+
+1. Create the project directory and structure:
+```bash
+mkdir -p bricktracker/{data,static/{instructions,minifigures,parts,sets}}
+cd bricktracker
+```
+
+2. Download the sample configuration files:
+```bash
+# Get the environment file template
+curl -o env.sample https://raw.githubusercontent.com/FrederikBaerentsen/BrickTracker/main/env.sample
+
+# Or with wget:
+# wget -O env.sample https://raw.githubusercontent.com/FrederikBaerentsen/BrickTracker/main/env.sample
+```
+
+## Docker Compose Configuration
+
+Create `compose.yaml` with this content:
+```yaml
+services:
+  bricktracker:
+    container_name: BrickTracker
+    restart: unless-stopped
+    image: gitea.baerentsen.space/frederikbaerentsen/bricktracker:1.1.1
+    ports:
+      - "3333:3333"
+    volumes:
+      - ./data:/data
+      - ./static/instructions:/app/static/instructions
+      - ./static/minifigures:/app/static/minifigures
+      - ./static/parts:/app/static/parts
+      - ./static/sets:/app/static/sets
+    env_file: ".env"
+```
+
+## Starting BrickTracker
+
+1. Start the application:
+```bash
+docker compose up -d
+```
+
+2. Access BrickTracker at `http://localhost:3333`
+
+Please refer to [Environment Variables Reference](docs/env.md) for a list of available variables.
+
+3. Read more in [First steps](docs/first-steps.md)
+
+## Troubleshooting
+
+1. If the application won't start:
+   - Check if port 3333 is available
+   - Check logs with `docker compose logs -f`
+   - Ensure `.env` file is properly formatted
+
+2. If images aren't appearing:
+   - Verify write permissions on static directories
+   - Ensure network connectivity to Rebrickable
+
+3. If you can't add sets:
+   - Verify your Rebrickable API key
+   - Check the application logs for API errors
+
+4. Environment configuration issues:
+   - Make sure `.env` file exists and is readable
+   - Check for any syntax errors in `.env` file
+   - Verify no conflicting environment variables are set in the shell
+
+For more troubleshooting, take a look at [Common Errors](docs/common-errors.md)
+
+Please refer to [Setup](docs/setup.md) for more information.

docs/setup.md

@@ -1,7 +1,7 @@
 # Setup
 
 > **Note**
-> The following page is based on version `1.0.0` of BrickTracker.
+> The following page is based on version `1.1.1` of BrickTracker.
 
 ## Prerequisites
 
@@ -53,6 +53,8 @@ services:
 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.
 
+[Environment Variables Reference](docs/env.md) contains a table of the available variables.
+
 ## Database file
 
 To accomodate for the original version of BrickTracker, the default database path is `./app.db`.
@@ -89,6 +91,24 @@ In the original version of BrickTracker they were either shipped with the contai
 
 You can use the `BK_RETIRED_SET_PATH` and `BK_THEMES_PATH` to relocate them into a volume.
 
+## Directory Structure
+
+Updated directory structure showing data volume organization:
+```
+bricktracker/
+├── data/                  # Persistent data
+│   ├── app.db             # Database file
+│   ├── retired_sets.csv   # Retired sets data
+│   └── themes.csv         # Themes data
+├── static/                # Static files
+│   ├── instructions/      # PDF and other instruction files
+│   ├── minifigures/       # Minifigure images
+│   ├── parts/             # Part images
+│   └── sets/              # Set images
+├── .env                   # Environment configuration
+└── compose.yaml     # Docker compose configuration
+```
+
 ## Authentication
 
 See [authentication](authentication.md)