Getting started

Install the server

Start the Docker stack and get the pairing password.

You need

Docker, with about 4 GB of memory to spare
git and make
A computer that can stay switched on at home

Steps

Get the code.

git clone https://github.com/sunday-studio/shop shop && cd shop

02
Optional: copy the settings file. Add a logo.dev key if you want real shop logos; without it the app shows initials.
```
cp deploy/.env.example deploy/.env
```
03
Build and start.
```
make setup
```
The first build downloads the OCR models and takes several minutes. When it ends it prints the pairing password once. Copy it.
```
$ make setup
…
pairing password (shown once; enter it in the app with the server URL):
maple-orbit-cedar-tide-42
```
04
Check that everything is healthy.
```
curl localhost:8080/healthz
```
Every check should say ok.

WarningThe server speaks plain HTTP. Do not expose it to the internet. Reach it over your home network or a VPN (see the next page).

Without building

You can pull ready-made images from GitHub Container Registry instead of building. The README has the commands; set SHOP_TAG in deploy/.env to pin a version (default latest). Pairing works the same way: run docker compose -f deploy/docker-compose.yml exec api shop password generate to get the password.

Settings

Set these in deploy/.env.

Setting	Default	Meaning
`SHOP_PORT`	8080	Port for the API and MCP
`SHOP_BACKUP_DIR`	backups/	Where nightly backups go (point it at another disk or a network share)
`BACKUP_AT`	03:30	Daily backup time
`BACKUP_KEEP_DAYS`	30	How long snapshots are kept
`LOGO_DEV_TOKEN`	none	Shop logos
`AUTO_PRODUCTS`	on	Create products when you confirm a receipt

SHOP_PORT · default 8080
Port for the API and MCP
SHOP_BACKUP_DIR · default backups/
Where nightly backups go (point it at another disk or a network share)
BACKUP_AT · default 03:30
Daily backup time
BACKUP_KEEP_DAYS · default 30
How long snapshots are kept
LOGO_DEV_TOKEN · default none
Shop logos
AUTO_PRODUCTS · default on
Create products when you confirm a receipt