Set it up
Menu

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.

ContainerWhat it doesUpdates
AppBrick Bin itself, from the published image.Watchtower, every five minutes
Postgres 17The app’s own database. It isn’t shared with anything else.Never automatic
Tailscale sidecarServes HTTPS at https://brick-bin.<your-tailnet>.ts.net.By you
WatchtowerPulls 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.

WhatHoldsPlan for
CatalogPart images and catalog files from Rebrickable.About 6 GB of images, plus up to 220 MB while a file is unpacked
DatabaseSets, copies, people, wishlists, the activity trail and the catalog tables.A few hundred MB
Instruction PDFsWhatever you upload or save.Tens of GB over time
CoversSet 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 needs rsync and read access to the Docker volume, which usually means root.
Terminal
# from the repository folder, on the Docker host, as root
COMPOSE="docker compose -f deploy/docker-compose.yml" scripts/backup.sh /srv/backups/brick-bin

Keep 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

  1. Set up the stack as in Setup, with the same .env, but don't open it yet.
  2. Start only the database and load the dump into it, then start the rest and put the covers and the instruction PDFs back:
    Terminal
    # 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.

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