Instalar Encuestum

Encuestum corre self-hosted como una sola imagen all-in-one: nginx (puerto 80) enruta el frontend (Next.js) y /api/ al backend (FastAPI). El frontend habla con el backend same-origin, así que en producción no configurás ninguna URL de API.

Imagen publicada: ghcr.io/diegoparras/encuestum:latest

Requisitos

• Docker (con Compose). Nada más.
• Una base de datos PostgreSQL para producción (el Compose la levanta por vos). Para probar rápido, la imagen suelta usa SQLite.

Instalación rápida

Un comando y tenés tu propio Typeform + Forms + corrector con IA corriendo:

git clone https://github.com/diegoparras/encuestum.git
cd encuestum
cp .env.example .env
# Editá .env y poné un secreto real:
#   ENCUESTUM_SESSION_SECRET=$(openssl rand -hex 32)
docker compose -f docker-compose.prod.yml up -d

Abrí http://localhost:8080 → Crear cuenta → ¡a armar tu primera encuesta!

Esto levanta la app all-in-one + PostgreSQL con datos persistentes en el volumen encuestum_pg.

Deploy con Docker

Compose + Postgres (recomendado)

El archivo docker-compose.prod.yml levanta la app + Postgres de una:

cp .env.example .env      # poné ENCUESTUM_SESSION_SECRET
docker compose -f docker-compose.prod.yml up -d
# → http://localhost:8080  ·  datos en el volumen encuestum_pg

Detrás de un dominio con HTTPS, en .env:

ENCUESTUM_PUBLIC_URL=https://encuestas.tudominio.com
ENCUESTUM_COOKIE_SECURE=true

y serví el puerto 8080 detrás de tu reverse proxy (nginx / Caddy / Traefik).

Imagen suelta (SQLite)

Para una prueba rápida, sin Postgres:

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

Usa SQLite dentro del volumen /app_data. Perfecto para probar; para producción usá Postgres.

Buildear vos mismo

docker build -t encuestum:local .

Deploy en EasyPanel

EasyPanel es la forma más cómoda de correrlo en un VPS. Encuestum es una App (no compose): corre la imagen y se configura por variables de entorno.

1. Base de datos → creá un servicio Postgres en tu proyecto (te da un host interno tipo tuproyecto_encuestum-db).
2. App → Create → App → source Docker Image: ghcr.io/diegoparras/encuestum:latest.
3. Environment de la App:

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

4. Ports / Domains → mapeá el dominio al puerto 80 del contenedor. EasyPanel emite el certificado (Let’s Encrypt) automáticamente.
5. Deploy. Al arrancar corre las migraciones solo y crea todo el esquema. Entrá a tu dominio → Crear cuenta.

Nota

Si usás SQLite en vez de Postgres, montá un volumen en /app_data para no perder los datos entre deploys. Con Postgres externo no hace falta.

Variables de entorno clave

Todo se configura por env con prefijo ENCUESTUM_*. Ver .env.example para la lista completa y comentada. Las principales:

Variable	Default	Para qué
ENCUESTUM_SESSION_SECRET	(efímero)	Firma las sesiones. OBLIGATORIO en prod (openssl rand -hex 32). Si no lo fijás, las sesiones se invalidan en cada reinicio.
DATABASE_URL	(SQLite)	postgresql://user:pass@host:5432/db para Postgres. Sin esto usa SQLite en ENCUESTUM_DATA_DIR.
ENCUESTUM_PUBLIC_URL	(CORS[0])	URL base pública (para los links de los emails). En prod, tu dominio.
ENCUESTUM_COOKIE_SECURE	true	Cookies solo-HTTPS. Poné false solo en http local.
ENCUESTUM_ALLOW_REGISTRATION	true	Auto-registro público. false para cerrar el alta.
ENCUESTUM_SUPERADMIN_EMAIL	—	Email (verificado) que obtiene el panel de super-admin de la plataforma.
ENCUESTUM_LLM_API_KEY	—	Key del proveedor LLM (o configurá la IA desde la pantalla IA de la app).
ENCUESTUM_LLM_BASE_URL	https://openrouter.ai/api/v1	Endpoint OpenAI-compatible.
ENCUESTUM_LLM_MODEL	openai/gpt-4o-mini	Modelo por defecto.
ENCUESTUM_STORAGE	local	s3 para subir a Cloudflare R2 / S3.
ENCUESTUM_SMTP_HOST …	—	Email para invitaciones / links / notificaciones.
ENCUESTUM_BASE_DOMAIN	—	Habilita subdominios por organización (acme.tudominio.com).

Almacenamiento externo (Cloudflare R2 / S3)

Para videos y adjuntos en producción, definí ENCUESTUM_STORAGE=s3 y las variables ENCUESTUM_S3_*. El navegador del respondiente sube el archivo directo al bucket privado con una URL prefirmada (el servidor nunca bufferea el archivo grande) y la app los streamea same-origin. R2 es lo recomendado por su egress gratis.

Seguridad en producción

Diseñado para self-hosted. Antes de exponerlo:

• Fijá ENCUESTUM_SESSION_SECRET (openssl rand -hex 32) y ENCUESTUM_COOKIE_SECURE=true.
• Serví el puerto detrás de un reverse proxy con TLS y poné ENCUESTUM_TRUST_PROXY=true para leer bien la IP real (rate limiting).
• En multi-tenant, dejá ENCUESTUM_ALLOW_PRIVATE_OUTBOUND=false (anti-SSRF en webhooks y en el base URL del LLM).
• Activá el captcha proof-of-work por encuesta en las públicas para frenar el spam de respuestas.

Leer la documentación completa