Hosting
Brick Bin is built for one household on one small server. This page covers what's running, what it stores, and what to copy somewhere safe.
On this page
What runs
The recommended home is a Proxmox VM or LXC with Docker, reached over Tailscale. The compose file in deploy starts four containers, and shares nothing with any other stack on the host.
| Container | What it does | Updates |
|---|---|---|
| App | Brick Bin itself, from the published image. | Watchtower, every five minutes |
| Postgres 17 | The app’s own database. It isn’t shared with anything else. | Never automatic |
| Tailscale sidecar | Serves HTTPS at https://brick-bin.<your-tailnet>.ts.net. | By you |
| Watchtower | Pulls a new app image when one is published. | By you |
The stack also publishes port 3000 on the host, so a home dashboard can check /healthz. Signing in needs HTTPS, so use the tailnet address for everything else.
Storage
Everything the app stores outside the database lives under DATA_DIR, which is /data on the app-data volume. The database has a volume of its own.
| What | Holds | Plan for |
|---|---|---|
| Catalog | Part images and catalog files from Rebrickable. | About 6 GB of images, plus up to 220 MB while a file is unpacked |
| Database | Sets, copies, people, wishlists, the activity trail and the catalog tables. | A few hundred MB |
| Instruction PDFs | Whatever you upload or save. | Tens of GB over time |
| Covers | Set and wish pictures. | Small |
A single PDF can be up to 200 MB by default. Change that with INSTRUCTIONS_MAX_MB.
Backups
The repository's scripts/backup.sh writes a backup in three parts. Run it nightly from cron on the Docker host. It keeps the newest 14 of each.
- A database dump,
db-<stamp>.sql.gz. The catalog tables are left empty, because an import rebuilds them. - Covers,
covers-<stamp>.tar.gz. - Instruction PDFs, as a snapshot in
instructions/<stamp>/. Files that haven't changed are hard links, so only new ones take space. This part needsrsyncand read access to the Docker volume, which usually means root.
# from the repository folder, on the Docker host, as root
COMPOSE="docker compose -f deploy/docker-compose.yml" scripts/backup.sh /srv/backups/brick-binKeep a copy of your .env with the backups.
Catalog images are not backed up
They're about 6 GB of files you can download again, so the backup leaves them out. After a restore, expect to run a catalog import.
Restoring
- Set up the stack as in Setup, with the same
.env, but don't open it yet. - Start only the database and load the dump into it, then start the rest and put the covers and the instruction PDFs back:
# in the deploy folder of the new install docker compose up -d db gunzip -c db-<stamp>.sql.gz | docker compose exec -T db psql -U bricks -d bricks docker compose up -d docker compose exec -T app tar -C /data -xzf - < covers-<stamp>.tar.gz # the PDFs go straight into the volume, as root cp -a instructions/<stamp>/. "$(docker volume inspect -f '{{ .Mountpoint }}' brick-bin_app-data)/instructions/"The order matters. The dump carries its own tables, and loads cleanly only into an empty database. When the app starts afterward, it adds any database changes newer than the backup.
- Sign in and run a catalog import. Your sets and copies are already there. The import brings back catalog lookup and the part pictures. The import history isn't restored, so the 48-hour wait starts fresh: if you imported on the old machine in the last two days, wait out the rest of that window.
Running without Tailscale
docker-compose.prod.yml, in the root of the repository, runs the app and its Postgres only, and publishes the app on port 3000. Change the port with APP_PORT. It builds the image from source, so Watchtower has nothing to update: pull the repository and run the build again to upgrade. If you put your own reverse proxy in front and serve HTTPS, set COOKIE_SECURE to true.
What it downloads, and when
Brick Bin makes no background downloads, and nothing in the app loads from a CDN. It reaches out in four cases, each started by a person:
- An admin runs a catalog import. Downloads come only from the origins in
REBRICKABLE_ALLOWED_ORIGINS, over HTTPS, one file at a time. - Someone saves a set picked from the catalog, and its cover is fetched once from
CATALOG_IMAGE_ORIGIN. - Someone scans a barcode, and the code is looked up with a public barcode service.
- Someone asks to save an instruction PDF from a web address. Only public HTTPS addresses are allowed; addresses on your own network or tailnet are refused.
The rest of the stack has its own habits: Watchtower checks for a new app image every five minutes, and the Tailscale sidecar stays connected to Tailscale.
Catalog data comes from Rebrickable.
Next in the docsConfiguration →Every environment variable, with its default.