Docker Installation Guide

1 What you are installing

A single, self-contained stack. No database server to install by hand, no Windows service or registry setup. Each install is standalone with its own database.

Two volumes hold everything that must survive restarts and image updates: ritzy-pg (the PostgreSQL data, mounted at /var/lib/postgresql; the 18 image keeps it in 18/docker under that) and ritzy-data, mounted in the app at /ritzy (company backups, licence files, the ZATCA SDK and certificates).

What is not included in v1

• The two secondary PWAs (Ritzy Track, Ritzy Dues) — native installs only for now.
• TLS/HTTPS — put a reverse proxy (Caddy, nginx, Traefik) in front.
• The License Server, which deploys separately.

2 Prerequisites & sizing

• Linux Docker Engine + Compose v2. Ubuntu LTS or Debian recommended. The installer can add them.
• Windows Windows 10/11 or Windows Server 2025. Preferred: Docker Engine inside a WSL2 Ubuntu — no per-seat licence, no GUI, and it is the same install a Linux server gets. Docker Desktop on the WSL2 backend also works on Windows 10/11. For Windows Server 2025, follow Docker on Windows Server 2025.
• Outbound internet access to pull the base images.

Rough sizing (per install)

[wsl2]
memory=6GB

3 The one-command install

On a blank Ubuntu (including a fresh WSL2 Ubuntu) a single script does everything in sections 4–11 — prerequisites, Docker Engine, secrets, the build, and a health check:

# from the repository root, NOT from docker/
bash install-linux.sh

It is safe to re-run: satisfied steps are skipped and an existing .env is never overwritten, so your database passwords and token secret survive.

The script also handles things that are easy to get wrong by hand: it starts Docker via systemd or the sysvinit wrapper (a fresh WSL has no systemd), uses sudo for the current run so a brand-new Docker install needs no logout, warns before the slow failures (too little RAM, a port already in use), and offers to move the source off /mnt first — building on the Windows drive through the WSL bridge is several times slower.

Prefer to understand each step, or installing on Windows? Continue with §4.

4 Docker by hand — Linux

# Install Docker Engine + Compose plugin
curl -fsSL https://get.docker.com | sh

# Start it and enable on boot
sudo systemctl enable --now docker

# Run docker without sudo (log out and back in afterwards)
sudo usermod -aG docker $USER

# Verify
docker --version
docker compose version

5 Docker by hand — Windows

Recommended: Docker Engine inside WSL2 Ubuntu

1. In PowerShell as Administrator, install WSL2 with Ubuntu (reboot if prompted):

   wsl --install -d Ubuntu

2. Open the Ubuntu shell and follow the Linux steps in §4.
3. Turn on systemd so Docker restarts with WSL — create /etc/wsl.conf containing:

   [boot]
   systemd=true

   then wsl --shutdown from PowerShell and reopen Ubuntu.
4. Verify inside Ubuntu: docker run --rm hello-world

Alternative: Docker Desktop

1. Install Docker Desktop and choose the WSL2 backend.
2. Launch it once so the engine starts.
3. Verify in PowerShell: docker info should succeed.
4. Run powershell -ExecutionPolicy Bypass -File .\install.ps1 from the docker\ folder.

6 Get the application onto the server

A first install builds the image from source, so the project has to be on the server.

cd ~
git clone <your-repo-url> ritzyweb
cd ritzyweb

Add the ZATCA SDK zip — required

ZATCA e-invoicing is part of the standard image, and ZATCA only offers its SDK through a captcha-protected download, so it can't be fetched during the build. Download the Java SDK zip from https://sandbox.zatca.gov.sa/downloadSDK and put it in docker/vendor/:

cp ~/Downloads/zatca-einvoicing-sdk-*.zip ~/ritzyweb/docker/vendor/

The build stops with a clear message if the zip is missing. The zip is never committed to git, and servers that pull a published image (§16) need nothing here. On first start each stack copies the SDK into its data volume, so the company's ZATCA certificates survive upgrades and are included in backups.

7 How the database is set up

Nothing to do by hand. The postgres container starts with the superuser password from PG_PASSWORD; on its first start the app connects with it and creates, in order:

Each step leaves what is already there alone. docker compose logs app shows the lines (created database ritzy, applying schema.sql) the first time.

8 Configure (.env)

cp .env.example .env

No editing of docker-compose.yml is required. While RITZY_IMAGE is a local tag the install scripts layer docker-compose.build.yml on top to build from source; point it at a published image and they pull instead.

9 Build & start

# build from source (first install)
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

# or, with a published image in RITZY_IMAGE
docker compose pull && docker compose up -d

docker compose ps            # both services should reach "healthy"
docker compose logs -f app   # watch startup; Ctrl-C to stop watching

The first build compiles the API and three front-ends — 5–10 minutes is normal. Later starts are immediate.

The app service waits for postgres to report healthy (pg_isready), then makes the database ready (§7) before it starts serving.

10 First-run setup wizard

1. Open http://<server>:8080/ in a browser (localhost on the same machine).
2. Because there is no database yet, the login screen shows Set up Ritzy. Click it.
3. Enter the support password — the date-based DBA setup code.
4. Complete the wizard: Company details → Financial Year → Administrator → Summary. It adds the first company to the database — financial year, numbering and reference data.
5. Sign in with the administrator account you just created.

11 Verify

curl http://localhost:8080/api/version
# {"version":"<build marker>"}

curl http://localhost:8080/api/setup/status
# before setup: {"needsSetup":true,...}
# after setup:  {"needsSetup":false,...}

Persistence — the data must survive a restart:

docker compose down && docker compose up -d

The company and your login should still be there; data lives in the ritzy-pg and ritzy-data volumes, not in the containers.

12 Ports & firewall

13 Update, backup & rollback

Update

docker compose pull && docker compose up -d
# building locally instead:
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Rollback

Set RITZY_IMAGE in .env back to the previous version tag, then docker compose up -d.

Stop and start

docker compose down          # stop; data persists in the volume
docker compose up -d         # start again

Backups — backup-stacks.sh

One script backs up every stack on the host: a pg_dump -Fc of the stack's database (ritzy.pgdump, every company), read from one snapshot so it is consistent while people work. It also saves the app's volume (files.tar.gz: company backups, ZATCA certificates, licence files) and the stack's .env.

cd ~/ritzyweb/docker
./backup-stacks.sh --rclone storagebox:ritzy     # or --rsync user@host:path, or --rsync /mnt/d/Backups

# daily at 02:30 (crontab -e)
30 2 * * * $HOME/ritzyweb/docker/backup-stacks.sh --rclone storagebox:ritzy >> $HOME/ritzy-backups/backup.log 2>&1

Each run writes <dest>/<stack>/<date>/. It exits with an error if any stack or the off-site copy failed, and never leaves a partial file that could pass for a good backup.

Restore

One company: DBA Console → Backup / Restore. A .pgbk holds one company's rows and restores into the same company (a pre-restore copy is written first) or as a new one.

The whole stack from a nightly backup — stop the app, restore, start it:

cd ~/ritzy-acme
docker compose stop app
docker compose exec -T postgres pg_restore -U postgres --clean --if-exists -d ritzy < ~/ritzy-backups/acme/<date>/ritzy.pgdump
docker compose start app

14 Several stacks on one host

First decide: another company, or another stack?

These are different things, and the wrong choice is expensive to undo.

The quick way — new-stack.sh

One command per additional customer. It creates the folder, generates that stack's own secrets, sets the project name and port, and refuses the mistakes that are painful later — a port already in use, a project name already running, or an image that does not exist yet:

cd ~/ritzyweb/docker

# build the shared image once
docker compose -f docker-compose.yml -f docker-compose.build.yml build

# then one command per stack
./new-stack.sh acme   8090
./new-stack.sh globex 8091 --start

Each lands in ~/ritzy-<name> with its own .env. Start it with docker compose up -d from that folder (or pass --start), then run the first-company wizard on its port. The rest of this section explains what the script sets up, and how to do it by hand.

By hand: what makes two stacks separate

Compose names everything — containers, networks and the data volume — after its project, which defaults to the folder name. Give each stack its own folder and the two never touch:

cp -r ~/ritzyweb/docker ~/ritzy-acme
cp -r ~/ritzyweb/docker ~/ritzy-globex

Then in each .env, three keys must differ:

Setting COMPOSE_PROJECT_NAME explicitly is worth the line: it survives a folder rename, and it is what appears in every container and volume name.

cd ~/ritzy-acme   && docker compose up -d
cd ~/ritzy-globex && docker compose up -d

docker volume ls | grep ritzy-data
# acme_ritzy-data      <- separate volumes (and acme_ritzy-pg / globex_ritzy-pg)
# globex_ritzy-data

Only APP_PORT is published, so that is the one number that has to be unique. PostgreSQL is not published at all — each stack's database is reachable only by its own app container, which is exactly the isolation you want.

Build the image once, run it in every stack

Do not rebuild per stack. Build once, tag it, and point every .env at that tag:

# once, from the repository root
cd ~/ritzyweb/docker
docker compose -f docker-compose.yml -f docker-compose.build.yml build
docker tag ritzy-web-app:local ritzy-web-app:1.0.0

# then in every .env
RITZY_IMAGE=ritzy-web-app:1.0.0

Containers share the image's disk layers, so a second stack costs almost no extra disk — only its data. It also means an upgrade is deliberate per stack: build a new tag, change that stack's RITZY_IMAGE, docker compose up -d. The others stay where they are until you move them.

Sizing — this is what actually limits you

Every stack has memory and CPU ceilings (PG_MEM_LIMIT, PG_CPUS, APP_MEM_LIMIT, APP_CPUS in its .env), so one customer's heavy report cannot starve the others. new-stack.sh --size writes a matching set:

./new-stack.sh tiny 8093 --size small --start

PostgreSQL's ceiling must cover its shared buffers plus PG_WORK_MEM per running sort and some headroom — keep shared buffers near a quarter of PG_MEM_LIMIT. Too low and the server is killed mid-query. A CPU value above the host's core count stops the container from starting. To resize a stack, edit its .env and run docker compose up -d.

Each stack runs its own PostgreSQL, so memory multiplies. Reckon on roughly 2–2.5 GB per stack beyond the host's own ~1 GB. Unlike the old per-database Firebird cache, a stack's shared buffers serve all its companies at once, so adding a company does not add a cache — but adding a stack does. Use --size small when packing several stacks onto one machine, or the host starts swapping and every stack feels slow at once.

Serving them by name instead of by port

Ports are fine internally, but customers want a hostname. Put a reverse proxy in front — each stack keeps its own port on 127.0.0.1 and the proxy maps names to them:

acme.example.com    →  127.0.0.1:8080
globex.example.com  →  127.0.0.1:8090

Caddy, nginx or Traefik all do this in a few lines, and that is also where TLS belongs — the bundle itself serves plain HTTP.

Backups with several stacks

backup-stacks.sh (§13) already covers every ~/ritzy-* stack, each in its own folder named after the stack, so a restore cannot go to the wrong customer.

15 Moving a Windows customer in

For web-only customers on a Windows installation, whose companies are still in Firebird .FDB files. They are converted to PostgreSQL on the Windows side by the importer (npm run pg:convert), then restored into the stack. Customers who also use the Ritzy 7 desktop app stay on Windows — it needs the Firebird databases.

1. On the customer's Windows database server, as Administrator. It needs Firebird's gbak / isql (already there), Node.js 20+, a RitzyWeb source checkout (the importer is a development script) and a PostgreSQL 18 to convert into — a local one is simplest. For the final move, stop the Ritzy One service first:

   powershell -ExecutionPolicy Bypass -File docker\migrate\export-windows.ps1 -PgUrl postgres://postgres:<pw>@localhost:5432/postgres
                                                        # -InstallDir if not C:\RitzyOne

   It converts every company in CompLib.xml (and its documents database) into a scratch database, which it drops afterwards, and writes one zip: a pg_dump of the result, the conversion report, a SHA-256 checksum, the settings that must follow the customer (AI key, web-push keys, licensing — never a database password), the licence files and the ZATCA certificates.
2. Copy the zip to the Docker host over a trusted channel (scp/sftp). It holds every company's data and private keys.
3. On the Docker host:

   cd ~/ritzyweb/docker
   ./new-stack.sh acme 8090 --start                     # if the stack is new
   ./migrate/import-to-stack.sh ritzy-migration-<date>.zip ~/ritzy-acme

   It checks the checksum, restores the dump into the stack's database, clears the Windows ZATCA SDK folder setting, installs the certificates, licence and settings, and restarts the app — which applies any newer upgrades. It refuses to replace a stack that already has companies unless you add --force (the old database is kept as ritzy_pre_import_<date>); companies are not merged.

Afterwards: users sign in again (the stack has its own sign-in secret); read the conversion report left in the stack folder (pg-validation-<date>.md); check that every company opens, that ZATCA shows the certificate as installed, and that the licence is valid; run backup-stacks.sh; stop the old Windows service; delete the zip.

16 Many servers — build once, pull everywhere

Rather than building on every server, build the image once and publish it to a registry:

# on a build machine, once, logged in to the registry
docker login ghcr.io
OWNER=your-github-org VERSION=1.0.0 ./docker/build-and-push.sh

Each server then needs only the docker/ folder and a .env with RITZY_IMAGE=ghcr.io/<owner>/ritzy-web-app:1.0.0, and runs docker compose up -d — no source checkout, no build, and a much smaller machine will do.

17 Troubleshooting