Install Encuestum

Encuestum ships as one all-in-one Docker image: nginx routes the frontend (Next.js) and /api/ to the backend (FastAPI). The frontend talks to the backend same-origin, so in production you configure no API URL at all. The only hard requirement is Docker (with Compose).

Published image: ghcr.io/diegoparras/encuestum:latest

Quick start

git clone https://github.com/diegoparras/encuestum.git
cd encuestum
cp .env.example .env
# Edit .env and set a real secret:
#   ENCUESTUM_SESSION_SECRET=$(openssl rand -hex 32)
docker compose -f docker-compose.prod.yml up -d

Open http://localhost:8080 → Create account → build your first survey. This brings up the all-in-one app + PostgreSQL with persistent data (volume encuestum_pg).

Set the session secret in production

ENCUESTUM_SESSION_SECRET signs the sessions and is mandatory in production. If you leave it unset, sessions are invalidated on every restart. Generate one with openssl rand -hex 32.

Docker options

Compose + Postgres (recommended)

The docker-compose.prod.yml file brings up the app plus Postgres in one shot:

cp .env.example .env      # set ENCUESTUM_SESSION_SECRET
docker compose -f docker-compose.prod.yml up -d
# → http://localhost:8080  ·  data in the encuestum_pg volume

Behind an HTTPS domain, add to .env:

ENCUESTUM_PUBLIC_URL=https://surveys.yourdomain.com
ENCUESTUM_COOKIE_SECURE=true

and serve port 8080 behind your reverse proxy (nginx / Caddy / Traefik).

Single image (SQLite, to try)

docker run --rm -p 8080:80 -v encuestum_data:/app_data \
  -e ENCUESTUM_SESSION_SECRET=$(openssl rand -hex 32) \
  -e ENCUESTUM_COOKIE_SECURE=false \
  ghcr.io/diegoparras/encuestum:latest

Uses SQLite inside the /app_data volume. Great for a quick test; for production use Postgres (the Compose option).

Build it yourself

docker build -t encuestum:local .

Deploy on EasyPanel

EasyPanel is the most convenient way to run it on a VPS. Encuestum is an App (not a compose stack): run the image and configure it with environment variables.

1. Database → in your EasyPanel project, create a Postgres service (it gives you an internal host such as yourproject_encuestum-db).
2. App → Create → App → source Docker Image: ghcr.io/diegoparras/encuestum:latest.
3. Environment of the App:

   DATABASE_URL=postgresql://USER:PASS@INTERNAL_HOST:5432/DBNAME
   ENCUESTUM_SESSION_SECRET=<openssl rand -hex 32>
   ENCUESTUM_PUBLIC_URL=https://surveys.yourdomain.com
   ENCUESTUM_COOKIE_SECURE=true

4. Ports / Domains → map your domain to the container’s port 80. EasyPanel issues the Let’s Encrypt certificate automatically.
5. Deploy. On boot it runs the migrations itself and creates the whole schema. Visit your domain → Create account.

Tip

Changing a variable means a Redeploy. If you use SQLite instead of Postgres, mount a volume at /app_data so data survives deploys — with external Postgres this is not needed.

Key environment variables

Everything is configured with ENCUESTUM_* env vars; see .env.example for the full, commented list. The essentials:

Variable	Default	Purpose
ENCUESTUM_SESSION_SECRET	(ephemeral)	Signs sessions. Mandatory in prod (openssl rand -hex 32).
DATABASE_URL	(SQLite)	postgresql://user:pass@host:5432/db for Postgres. Falls back to SQLite otherwise.
ENCUESTUM_PUBLIC_URL	(CORS[0])	Public base URL, used for the links in emails.
ENCUESTUM_COOKIE_SECURE	true	HTTPS-only cookies. Set false only on local http.
ENCUESTUM_ALLOW_REGISTRATION	true	Public self-registration. false closes sign-up.
ENCUESTUM_SUPERADMIN_EMAIL	—	Verified email that gets the platform super-admin panel.
ENCUESTUM_LLM_API_KEY	—	LLM provider key (or configure AI from the app’s AI screen).
ENCUESTUM_LLM_BASE_URL	https://openrouter.ai/api/v1	OpenAI-compatible endpoint.
ENCUESTUM_LLM_MODEL	openai/gpt-4o-mini	Default model.
ENCUESTUM_STORAGE	local	s3 to upload to Cloudflare R2 / S3.
ENCUESTUM_SMTP_HOST …	—	Email for invitations / magic links / notifications.
ENCUESTUM_BASE_DOMAIN	—	Enables per-organization subdomains (acme.yourdomain.com).
AUTH_MODE	local	Set federado to delegate login to Lockatus (Suite SSO).

Email is optional

Without SMTP, Encuestum does not break: emails are written to the log (copy the link from there) and you can always download the CSV of access codes and hand them out yourself.

Read the full documentation