docker compose logs -f api worker # logs
docker compose exec api npm -w @soloops/api run db:studio # Prisma Studio
docker compose down # stop
npm run ports # who is listening on what right now?
npm run ports:kill soloops # free this project's portsnpm run ports lists every listening service with its process and origin —
the container name where there is one, otherwise the working directory.
Freeing knows the difference: a port held by Docker is released by stopping the
container rather than by killing the daemon.
Edit prisma/schema.prisma, then npm run db:migrate — that writes a
migration under prisma/migrations/, applies it, and regenerates the client.
Commit the migration with the schema change; the two belong together and a
schema without its migration is a schema nobody else can apply.
On every start a one-shot migrate service runs prisma migrate deploy and
api and worker wait for it to finish. So a container restart applies
whatever is pending, and a migration that fails stops the boot instead of
becoming the first line of a log nobody reads.
prisma db push is gone. It was convenient and it could silently drop a
column; migrate deploy only ever runs what is written down and reviewed.
The first migration, 0_init, is the whole schema as it stood when migrations
were introduced. On an existing database its tables are already there, so it
must be marked as applied once instead of being run:
docker compose run --rm migrate npx prisma migrate resolve --applied 0_init \
--schema packages/core/prisma/schema.prismaWithout this, migrate deploy tries to create tables that exist and stops.
Afterwards docker compose up works as usual. Take a backup first — the
backup window of the macOS app does it in one click, see
macOS app.
Two kinds, in two places.
The .env holds what a container needs before it can answer anything:
DATABASE_URL, REDIS_URL, the ports, NODE_ENV, TZ, APP_URL,
DATA_DIR, SYNC_ADVERTISE_HOSTS, the n8n topology, OWNER_* (read once as
a seed), SERVICE_TOKEN — and JWT_SECRET, which can never move:
secretbox.ts derives the
encryption key from it, so a JWT_SECRET in the database would encrypt its
own decryption key.
Everything that belongs to the person rather than to the deployment is in
Einstellungen: the twelve sender fields, the five invoicing defaults, the
keys for the optional services, the video provider, and the six poll
intervals. The registry is
packages/core/src/settings.ts; each key
carries a Zod schema, whether it is a secret, and the .env variable it falls
back to.
Reading order is database → .env → default. So an existing installation
keeps working untouched, and the moment a value is set in the interface the
database is the answer — editing the file has no effect from then on. Every
field in the interface says which of the two it currently is.
Secrets are sealed at rest and never sent back; the interface shows "set" and
the first four characters. Clearing a field hands it back to the .env.
A changed poll interval takes effect within a minute: the worker compares what it has planned against what is in force and rewrites only what moved.
Everything sealed with it becomes unreadable: IMAP passwords, Google refresh
tokens, CalDAV passwords, the n8n key, and now the service keys. Each site
degrades differently — some fall back to the .env, some ask for the value
again, imap.ts throws. There is no re-key path. Rotating it means entering
those secrets again, and that is worth knowing before rather than after.
Every environment variable is documented in
.env.example; packages/core/src/env.ts is
the authoritative source with types and defaults. If something required is
missing, the API refuses to start and says what.
Two things have to come along: the database and ./data (invoice PDFs, signed
contracts and the files filed at a customer). The
.env belongs in your password manager, not in the backup archive.
# Back up
docker compose exec -T postgres pg_dump -U soloops -Fc soloops > soloops-$(date +%F).dump
tar czf soloops-data-$(date +%F).tar.gz data/
# Restore
docker compose exec -T postgres pg_restore -U soloops -d soloops --clean --if-exists < soloops-2026-01-01.dumpCalendar sync is not a backup: it propagates changes, deletions included.
And allowRemoteDelete is off per account by default so a misclick here does
not take the events on all your devices with it.
| Symptom | Cause and fix |
|---|---|
| API won't start, log names a variable | A required field in .env is missing or too short (JWT_SECRET needs 16+ chars) |
Login fails although .env is correct |
The seed never ran: docker compose exec api npm -w @soloops/api run seed |
| Events missing from the week view | Account just connected? The first sync only fetches the window — check worker |
| CalDAV reports an authentication error | Apple needs an app-specific password, not the Apple ID password |
| Web loads, API answers 502 | The API is still waiting for migrate; docker compose logs -f migrate api |
| Day band stays empty | Activity recording is off, or macOS has not been granted Accessibility |
In this order. Only the first step is mandatory; the rest is what changed around it.
-
Take a backup. The backup window of the macOS app does it in one click, see macOS app.
-
Adopt the migrations — once.
0_initis the whole schema as it stood when migrations were introduced, and on an existing database its tables are already there:docker compose run --rm migrate npx prisma migrate resolve --applied 0_init \ --schema packages/core/prisma/schema.prisma
Without this,
migrate deploytries to create tables that exist and stops. -
docker compose up -d. A one-shotmigrateservice now runs beforeapiandworker; anything pending is applied there.prisma db pushis gone —npm run db:migratein development,npm run db:deployotherwise. -
The Prisma schema moved to
packages/core/prisma/schema.prisma. Any script or alias of your own that names the old path needs adjusting. -
n8n is pinned to 2.42.4. It ran on
latestbefore. To keep that, setN8N_IMAGE_TAG=latestin the.env. -
Time booked through the automation connector now carries an hourly rate and a client, and completing a task through it closes the lead's follow-up. Entries booked before this are not corrected retroactively — if a workflow has been booking time, those rows have no rate and will be invoiced at nothing until they are fixed by hand.
-
The
.envstill works. Nothing has to be moved. But as soon as a value is set under Einstellungen, the database wins and the file stops having an effect for that one value. -
Re-import both contract workflows in n8n — Automatisierungen → Vorlagen, "Vertrag versenden" and "Vertrag signiert". Contracts are a table now, not notes with a
[VERTRAG]title, and the copy running in n8n still writes notes: the send would file the contract twice and the signed PDF would never reach it. The import needs the updated soloops node, which comes with the image.Existing
[VERTRAG]notes are left alone — nothing reads them any more, so anything still in flight is filed by hand under the customer, where the PDF can be uploaded with it.