Running DBRepairs with Docker and TrueNAS

DBRepairs Server turns the desktop repair-management workflow into a shared browser application. Docker separates the web interface, API, PostgreSQL database and backup worker so several computers can use one central dataset.

Why a server edition exists

The desktop edition is intentionally simple: one application and one local SQLite database. That is ideal for a single workstation. The moment a counter computer and an office computer both need the same live repairs, copying database files back and forth becomes error-prone and sharing SQLite over the network is not a good concurrency model.

The server edition solves that by moving shared state to PostgreSQL and exposing business operations through an HTTP API. Browsers load the same React interface but data access is routed through the server instead of a local Tauri SQLite plugin.

The four-service layout

A normal DBRepairs Docker deployment has four services. The web container serves the compiled frontend and proxies API requests. The api container validates requests and performs transactional operations. The db container runs PostgreSQL. The backup container periodically creates database dumps and removes backups older than the configured retention period.

Only the web port needs to be published to the local network. PostgreSQL and the API can remain on the private Docker network. This reduces unnecessary exposure and makes the browser endpoint the single entry point for users.

Persistent storage is separate from containers

Containers are replaceable. Business data must not depend on a container’s writable layer. PostgreSQL therefore stores its files in a persistent Docker volume or a TrueNAS dataset, while database dumps are written to a separate backup location.

On TrueNAS SCALE, the project uses dedicated datasets for PostgreSQL data and backups. Keeping those datasets separate makes permissions clearer and allows backup copies to be handled differently from the live database.

TrueNAS deployment model

The project provides a compose.truenas.yaml file designed for installation through the TrueNAS custom YAML application workflow. The published web and API images are pulled from GitHub Container Registry, while PostgreSQL uses the official Alpine image.

The web interface is exposed on a configurable host port. The current TrueNAS configuration maps the external DBRepairs port to the unprivileged nginx port inside the container. That distinction matters during updates: when the internal web image changed from port 80 to 8080, the compose mapping also had to be updated.

Health checks make updates safer

Each critical service should expose a health signal. PostgreSQL can be checked with pg_isready. The API has a health endpoint. The web container can request its own local health path. Docker uses these checks to report whether a service is merely running or actually ready to serve requests.

Dependencies can then wait for healthy upstream services. For example, the web service should not be considered useful until the API is healthy, and the API should not start normal work before PostgreSQL accepts connections.

Backups before updates

Before changing container images or compose configuration, create a current backup. DBRepairs Server supports manual PostgreSQL backups from the interface as well as scheduled dumps from the backup service. Keep at least one copy outside the Docker host so a storage failure on the TrueNAS system does not destroy both the database and its backups.

For migration between desktop and server editions, use the portable .dbrepairs format instead of treating a PostgreSQL dump as a SQLite file. The portable archive represents application data rather than one database engine’s internal format.

Safe update sequence

• Create and verify a fresh backup.
• Review release notes and compose changes, especially ports and environment variables.
• Pull the new images or redeploy the TrueNAS custom app.
• Check that database, API and web services report healthy.
• Open the application from another machine and test a read operation.
• Test one controlled write, PDF generation and a new backup.
• Keep the previous image tag or configuration available until validation is complete.

LAN first, remote access carefully

The first DBRepairs Server architecture is primarily intended for a trusted local network. Publishing an internal business application directly to the Internet without authentication is not appropriate. If remote access is required, place it behind a VPN or an authenticated reverse proxy and review the threat model before opening firewall ports.

Docker and TrueNAS are useful here because they make the deployment repeatable, not because containers remove operational responsibility. A reliable setup still depends on persistent storage, correct permissions, health checks, controlled updates and backups that have actually been tested.