From ff1f02b7e33771e2b94f97e8f84fa3c9f89f726c Mon Sep 17 00:00:00 2001 From: FrederikBaerentsen Date: Tue, 28 Jan 2025 14:55:28 +0100 Subject: [PATCH] Updated readme and various docs. Added quickstartguide and env overview. --- README.md | 4 +- docs/DOCS.md | 1 + docs/env.md | 108 ++++++++++++++++++++++++++++++++++++++++++++ docs/first-steps.md | 2 +- docs/quickstart.md | 90 ++++++++++++++++++++++++++++++++++++ docs/setup.md | 22 ++++++++- 6 files changed, 224 insertions(+), 3 deletions(-) create mode 100644 docs/env.md create mode 100644 docs/quickstart.md diff --git a/README.md b/README.md index 291d8b5..58e4529 100644 --- a/README.md +++ b/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 diff --git a/docs/DOCS.md b/docs/DOCS.md index 450ca29..28deffe 100644 --- a/docs/DOCS.md +++ b/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 diff --git a/docs/env.md b/docs/env.md new file mode 100644 index 0000000..1f215cb --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/docs/first-steps.md b/docs/first-steps.md index 162854b..30c9f2e 100644 --- a/docs/first-steps.md +++ b/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 diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..e38019e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md index 502502f..8ad7da6 100644 --- a/docs/setup.md +++ b/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)