Set it up
Menu

Setup

From an empty machine to the first-visit screen. The recommended route uses Tailscale. There's a shorter one if you only want a look around.

On this page

Before you start

Brick Bin is a self-hosted app. You run it on your own server and reach it over your own network. You'll need:

  • A machine that runs Docker with Compose. We recommend a Proxmox VM or LXC.
  • A Tailscale account and an auth key, if you're following the recommended route.
  • Git, to fetch the compose files from the repository.
  • Disk space: about 6 GB for the catalog, a few hundred MB for the database, and tens of GB for instruction PDFs over time. Storage in detail.

Quick try-out, without Tailscale

To see Brick Bin before committing to anything, build it from the repository with its production compose file, docker-compose.prod.yml, and open port 3000.

Terminal
# fetch the source
git clone https://github.com/chimericdream/brick-bin.git
cd brick-bin

# choose a database password, for this try-out only
echo "POSTGRES_PASSWORD=choose-something-long" > .env

# build the app and start it with its own Postgres
docker compose -f docker-compose.prod.yml up -d --build

# then open
http://<your-server>:3000

Fine for a look, not for keeps

This serves plain HTTP on your network, and the image is built on your machine, so nothing keeps it up to date. If you put HTTPS in front of it, set COOKIE_SECURE to true.

Recommended install, with Tailscale

The repository's deploy folder is the full stack, four containers: the app, its own Postgres 17, a Tailscale sidecar that serves HTTPS, and Watchtower to keep the app image current. What each one does.

  1. Create a Proxmox VM or LXC and install Docker on it.
  2. Fetch the repository and go into its deploy folder, which holds docker-compose.yml and serve.json:
    Terminal
    git clone https://github.com/chimericdream/brick-bin.git
    cd brick-bin/deploy
  3. In the Tailscale admin console, make sure MagicDNS and HTTPS certificates are on for your tailnet, and create an auth key.
  4. Copy .env.example to .env in the deploy folder, and fill in the two values at the top:
    .env
    POSTGRES_PASSWORD=choose-something-long
    TS_AUTHKEY=tskey-auth-…
  5. Start it: docker compose up -d
  6. Open https://brick-bin.<your-tailnet>.ts.net from any device on your tailnet.

The compose file turns on secure cookies and builds the database address itself, so most installs only set those two. The rest of .env.example is commented out at the defaults. Every setting is listed in Configuration.

First visit

The first time anyone opens Brick Bin, it asks you to create the household and the admin account. There's no default password to change, because there's no default account.

SET-01First visit: create the householddesktop · 16:10 · light
SET-01 · First visit: create the household
Screen
First visit: "Set up your bin".
State
Brand-new install. The form is filled in with a sample household name but not yet submitted.
Viewport and theme
Desktop, 1440 wide, light.
Focus
The whole form. Center it and crop the empty margins.

The step-by-step version is the first-run tutorial.

Import the catalog

Brick Bin works without the catalog, but LEGO set lookup and part pictures need it. The first import downloads about 6 GB of part images plus a data archive from Rebrickable, and only runs when an admin starts it.

Tutorial: import the LEGO catalog

Staying up to date

Watchtower checks for a new app image every five minutes and swaps it in. Database migrations run when the app starts.

Postgres is never updated automatically, and neither are the Tailscale and Watchtower containers. When you choose to, take a backup, then run docker compose pull and docker compose up -d in the deploy folder.

Next in the docsHosting →What runs, how much disk it wants, and how to back it up.