SurfSense DocsDocker Compose Development
Building SurfSense from source using docker-compose.dev.yml
If you're contributing to SurfSense and want to build from source, use docker-compose.dev.yml instead:
cd SurfSense/docker
docker compose -f docker-compose.dev.yml up --buildThis file builds the backend and frontend from your local source code (instead
of pulling prebuilt images) and includes pgAdmin for database inspection at
http://localhost:5050. It intentionally keeps raw
frontend, backend, and zero-cache ports published for debugging. Use the
production docker-compose.yml for the default Caddy single-origin setup.
Dev-Only Environment Variables
The following .env variables are only used by the dev compose file (they have no effect on the production docker-compose.yml):
| Variable | Description | Default |
|---|---|---|
PGADMIN_PORT | pgAdmin web UI port | 5050 |
PGADMIN_DEFAULT_EMAIL | pgAdmin login email | admin@surfsense.com |
PGADMIN_DEFAULT_PASSWORD | pgAdmin login password | surfsense |
REDIS_PORT | Exposed Redis port (internal-only in prod) | 6379 |
AUTH_TYPE | Runtime auth mode | LOCAL |
ETL_SERVICE | Runtime document parsing service | DOCLING |
DEPLOYMENT_MODE | Runtime deployment mode | self-hosted |
ZERO_CACHE_PORT | Exposed zero-cache port for debugging | 4848 |
In the production compose file, the frontend reads AUTH_TYPE, ETL_SERVICE,
and DEPLOYMENT_MODE at request time. Browser API and Zero traffic are
same-origin relative through bundled Caddy.
Production Docker exposes only the bundled Caddy proxy by default; dev compose
keeps direct service ports so contributors can inspect and restart individual
services without going through the proxy.