DeltaChat / Advanced Install
Advanced install guide
Detailed deployment guidance for operators who want the full install model, configuration expectations, staged startup behavior, and manual fallback paths.
Operator-oriented deployment guide
This page is written for serious self-hosters and infrastructure-capable operators. It assumes Linux, Docker Compose, domains, DNS, reverse proxies, certificates, and troubleshooting are already familiar.
Confirm prerequisites
DeltaChat is currently documented for real operators. Before starting, make sure the host, DNS, reverse proxy, and certificate prerequisites are already in place.
Understand the staged startup model
Infrastructure first
The infrastructure layer includes PostgreSQL and Nginx Proxy Manager. These services must already be running before the application layer is started.
Application second
The DeltaChat API and web frontend come up after infrastructure. This is intentional because the API bootstraps ingress through NPM.
Hard requirement
Nginx Proxy Manager must already be running, the NPM credentials must be valid, and the wildcard certificate must already exist before the application layer is started.
What the installer will ask for
The installer creates your working environment file and prompts for the key public hostnames, Nginx Proxy Manager credentials, certificate name, and database secrets used by the deployment.
Public app hostname
The public hostname users open in their browser, for examplechat.your-domain.com
Public API hostname
The public hostname browsers use to reach the API, for exampleapi.your-domain.com
Ingress certificate name
This must match the wildcard certificate already present in Nginx Proxy Manager, for example*.your-domain.com
NPM identity and secret
Use real operator credentials accepted by your NPM instance. These are later used by the DeltaChat API to authenticate against the NPM API.
NEXTAUTH_URL=https://chat.your-domain.com
NEXT_PUBLIC_API_URL=https://api.your-domain.com
NPM_BASEURL=http://npm:81
NPM_IDENTITY=admin@your-domain.com
NPM_SECRET=change-me
INGRESS_CERTIFICATE_NAME=*.your-domain.comManual Docker Compose fallback
The intended path is installer plus helper scripts, but experienced operators can fall back to Docker Compose directly if needed.
Start infrastructure first
This brings up the default infrastructure services.
docker compose up -dStart the app layer second
Only after NPM and the wildcard certificate are already in place.
docker compose --profile app up -d api webView full stack status
docker compose --profile app psStop everything
docker compose --profile app down --remove-orphansVerify startup and first access
Once infrastructure, DNS, certificates, and the application layer are in place, verify service state, review logs, and confirm the expected entrypoints are reachable.
./stack.sh status
./stack.sh logs app
./stack.sh logs api
./stack.sh logs webTypical URLs
https://chat.your-domain.com
https://api.your-domain.com
http://your-server:81What to check when something is wrong
If startup does not look right, begin by checking current state, then inspect infrastructure and application logs before changing anything.
./stack.sh status
./stack.sh logs infra
./stack.sh logs appCommon things to confirm
- Nginx Proxy Manager is reachable
- The wildcard certificate already exists in NPM
- The configured ingress certificate name matches the real certificate
- The public hostnames resolve to the correct server
- The NPM credentials are valid
- The public app and API URLs are correct