Services
Services
A lazyit instance is a small set of containers on one host. This page explains what each one does, so you know which logs to read and what is safe to restart. The reverse proxy is the only service that publishes ports to the host; everything else lives on an internal Docker network.
The containers
| Service | Role | Notes |
|---|---|---|
| caddy | Reverse proxy + automatic HTTPS | The only public-facing service. Routes / to the web app and /api/* to the API. |
| web | The Next.js web app | Serves the user interface; runs sign-in server-side. |
| api | The NestJS API | All business logic. Also runs the background workers. |
| db | PostgreSQL — the application database | The system of record. Holds all your data. |
| migrate | One-shot migration + seed job | Runs once per deploy, then exits. Applies schema migrations before the API starts. |
| valkey | Background-job broker | Backs the async workers (e.g. document import, the workflow engine). |
| meilisearch | Search engine | Powers cross-entity search. Rebuildable from the database. |
No identity provider runs in the stack. With local accounts lazyit handles sign-in itself; with your own OIDC provider, sign-in goes to a service you run elsewhere (see Identity provider). An optional backup sidecar can also run alongside — see Backups & restore.
How the pieces fit together
- The browser only ever talks to Caddy over HTTPS. Caddy forwards page requests to web and
API requests to api on the internal network. Because the web app calls the API at the relative
path
/api, one image works on any domain. - api reads and writes the db (PostgreSQL), pushes background jobs to valkey, and keeps meilisearch in sync as data changes.
- migrate runs first on every deploy: it applies database migrations and a small idempotent seed, then exits. The API waits for it to finish successfully before starting.
- Sign-in is handled by web and api — against lazyit’s own accounts, or by validating the tokens your OIDC provider issues.
One database
The stack runs one PostgreSQL database, the application database (db). It holds your data and, with local accounts, the sign-in credentials too. See Backups & restore.
What is and isn’t a backup target
- db holds real state — back it up.
- meilisearch is rebuildable: its index is reconstructed from the database with a re-index command, so its data does not need backing up.
- valkey holds only in-flight background-job state (PostgreSQL is the system of record), so it is not a backup target either. Its data survives restarts so queued jobs aren’t lost.
- caddy re-obtains its certificates automatically, so its state needs no backup.
Resource limits and logs
Every long-running container has a modest memory and CPU ceiling and a log-rotation policy, so one
runaway service can’t exhaust the host and logs can’t fill the disk over months. Tune the limits to
your box if a service is constrained — watch docker stats. The full sizing guidance lives in the
self-hosted deployment runbook.