FrederikBaerentsen/BrickTracker
4
6
Fork 6
Code Issues 13 Pull Requests 2 Actions Packages Projects 1 Releases 3 Wiki Activity

Updated readme and various docs. Added quickstartguide and env overview.

Browse Source
This commit is contained in:
FrederikBaerentsen 2025-01-28 14:55:28 +01:00
parent 53309a9502
commit ff1f02b7e3
6 changed files with 224 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -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

1
docs/DOCS.md
View File

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

108
docs/env.md Normal file
View File

@ -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
```

2
docs/first-steps.md
View File

@ -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

90
docs/quickstart.md Normal file
View File

@ -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.

22
docs/setup.md
View File

@ -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)