Host requirements
A host with at least 4 CPU cores and 8 GB of memory is recommended. Size storage for the database, attachments, logs, and backups as well as the application. The default setup pulls prebuilt app and database images from GitHub Container Registry. Only source builds require access to build dependencies and base images.
Start with the quick start. The default Compose configuration uses the prebuilt ghcr.io/feronavi/feronavi-app:latest and ghcr.io/feronavi/feronavi-db:16 images, so the product does not need to be compiled on the deployment host. Set FERONAVI_VERSION=0.1.0 in .env to pin the app version, then use docker compose pull to fetch it.
Ports and access
The default application binds to 127.0.0.1:3000. Expose HTTPS through a reverse proxy rather than opening the application port directly to the internet.
Replace the sample domain pm.example.com with your domain and point its DNS to the server.
HTTPS with Caddy
When Caddy runs directly on the same host as Feronavi, use:
pm.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000 {
flush_interval -1
}
request_body {
max_size 30MB
}
}
For eligible public domains, Caddy can issue and renew certificates automatically. flush_interval -1 forwards streaming responses promptly. If the proxy runs in a container or on another host, configure the upstream address and trusted proxy ranges for that network.
Using nginx
Reuse your existing TLS configuration. Preserve the host and forwarded protocol, disable response buffering, and allow a longer read timeout for the event stream.
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off;
proxy_read_timeout 300s;
}
location /api/v1/events {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Connection '';
proxy_buffering off;
proxy_read_timeout 3600s;
}
Configure services
| Setting | Purpose |
|---|---|
DB_PASSWORD |
Database password, required by Compose |
APP_PORT |
Local application port, 3000 by default |
TRUSTED_PROXY_CIDRS |
Address ranges trusted as reverse proxies |
VALKEY_MAXMEMORY |
Cache memory limit, sized for the host |
Compose substitutes values from .env. To add a new application environment variable, also include it in the relevant service’s environment section. Adding it only to .env does not pass it into the container.
Configure SMTP, models, and third-party integrations in the administration interface. Persist database and application volumes. The application and worker use the same version and data directory.
Verify before inviting your team
- Sign in over HTTPS and complete a status transition.
- Check that notifications and assistant streaming arrive promptly.
- Upload and download an attachment to verify proxy size limits.
- Confirm audit records identify the real client IP.
- Create and validate a full backup. See backups and upgrades.