DeltaChat / Installation
Install DeltaChat
Deploy DeltaChat using Docker Compose on Ubuntu or a similar Linux host. This path is designed for self-hosted installation with a runtime environment file, clear operational control, and a practical setup flow.
Quick start
The shortest real path from repo to running stack.
cp .env.example .env.runtime nano .env.runtime chmod 600 .env.runtime docker compose --env-file .env.runtime up -d docker compose ps docker compose logs -f
Install video coming soon
A YouTube walkthrough will be added to this page to make the self-hosted install path easier to follow end-to-end.
Prerequisites
- A server running Ubuntu 24 or a similar Linux distribution
- SSH access with a user that can run sudo
- Docker Engine and Docker Compose plugin installed
- A domain name recommended for production deployments
- A copy of docker-compose.yml and .env.example from the DeltaChat repository
Production recommendation
For public deployments, use a real domain, HTTPS, strong secrets, and pinned image versions where practical.
Step-by-step install path
This follows the deployment model used in the actual DeltaChat repository: deployment files, a runtime environment file, Docker Compose, and explicit operator checks after startup.
Install Docker and Compose
Start with a fresh Ubuntu 24 server and install Docker Engine plus the Docker Compose plugin.
sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo systemctl enable docker sudo systemctl start docker
Create the deployment directory
Set up the DeltaChat deployment folder under /opt and prepare the instances directory for persistent service data.
sudo mkdir -p /opt/deltachat sudo chown -R $USER:$USER /opt/deltachat cd /opt/deltachat sudo mkdir -p /opt/deltachat/instances sudo chown -R 1000:1000 /opt/deltachat/instances
Copy the deployment files
Copy docker-compose.yml and .env.example from the repository into your deployment directory.
cp docker-compose.yml /opt/deltachat/ cp .env.example /opt/deltachat/ cd /opt/deltachat
Create and edit .env.runtime
Use the example environment file as your runtime file, then review image version, passwords, JWT settings, and public URLs.
cp .env.example .env.runtime nano .env.runtime
Generate a strong JWT signing key
Replace JWT_SIGNING_KEY with a long, random value. At least 32 characters is recommended.
openssl rand -base64 48
Secure the environment file
Restrict permissions so the runtime file is not broadly readable on the host.
chmod 600 .env.runtime
Start DeltaChat
Bring the stack up using the runtime environment file explicitly.
docker compose --env-file .env.runtime up -d
Check status and logs
Confirm services are running and inspect logs if anything looks unhealthy.
docker compose ps docker compose logs -f
Review these values before startup
- Image registry and version
- Database password
- JWT signing key
- PUBLIC_BASE_URL and PUBLIC_API_BASE_URL
- Any Nginx Proxy Manager or reverse proxy settings
First access
Typical local/default URLs during initial setup:
Web UI
http://localhost:3000
API
http://localhost:7000
Nginx Proxy Manager
http://localhost:81
Using Nginx Proxy Manager?
After first access, sign in to Nginx Proxy Manager, change the default credentials immediately, then create proxy hosts for your public domains and enable SSL.
Important production notes
DeltaChat can be brought up locally first, but public deployment should be treated as real production work.
Do not leave public URLs pointed at localhost in production
Do not keep default passwords in production
Use HTTPS and a real domain for public access
Do not expose PostgreSQL publicly unless you have a deliberate reason and proper controls
Review firewall rules for ports such as 80, 81, 443, 3000, and 7000 depending on your deployment model
What next?
Once the stack is up, continue with the docs, review configuration, and keep the troubleshooting and upgrading paths close by.
Need the wider deployment picture?
After installation, continue into the DeltaChat docs for the broader operational model, troubleshooting paths, and supporting guidance.