Basics

Guia de instalacion

Como desplegar QuoteNode en tu propia infraestructura usando Docker Compose.

Instalacion

QuoteNode funciona como un conjunto de contenedores Docker. No necesitas instalar Java, Node.js ni PostgreSQL en tu maquina: Docker se encarga de todo.

Requisitos previos

Docker Engine 24.0 o posterior (instalar Docker)
Docker Compose v2, incluido en Docker Desktop y Docker Engine modernos
Una maquina con al menos 2 GB de RAM y 10 GB de espacio libre

Para verificar la instalacion:

docker --version        # Debe mostrar 24.0+
docker compose version  # Debe mostrar v2.x

Inicio rapido (5 minutos)

Esto pone QuoteNode en marcha en tu maquina local para evaluacion. No es para produccion; para eso, sigue la seccion inferior.

Paso 1 - Crear un directorio de proyecto

mkdir quotenode && cd quotenode

Paso 2 - Crear el archivo de configuracion

Crea un archivo llamado .env con la configuracion minima requerida:

# Database
DB_URL=jdbc:postgresql://postgres:5432/quotenode
DB_USERNAME=quotenode
DB_PASSWORD=change-me-to-something-random-32-chars
DB_NAME=quotenode

# ============================================================
# SECURITY SECRETS - LEE ESTO ANTES DE CONTINUAR
# Estos valores son UNICOS para tu instalacion.
# Si pierdes este archivo, NO podras regenerar los mismos secretos.
# GUARDA ESTE ARCHIVO y conserva una copia segura.
# ============================================================
DB_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
TIMING_TOKEN_SECRET=change-me-timing-secret-min-32-chars
PUBLIC_LINK_PASSWORD_SESSION_SECRET=change-me-session-secret-min-32

# Domain (for CORS and Caddy)
CORS_ALLOWED_ORIGINS=http://localhost
DOMAIN=localhost

# Logging
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=prod

Guarda tu archivo .env inmediatamente. Los secretos de arriba son unicos para esta instalacion. Si lo pierdes, no podras regenerar los mismos valores. Sin el DB_ENCRYPTION_KEY original, los datos cifrados como codigos MFA, contrasena SMTP y claves API pasan a ser ilegibles para siempre. Copia este archivo a una ubicacion segura. En produccion, considera incluso imprimir los secretos y guardarlos en una caja fuerte fisica.

Paso 3 - Crear el archivo Docker Compose

Crea un archivo llamado docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME}"]
      interval: 10s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  gotenberg:
    image: gotenberg/gotenberg:8
    environment:
      LOG_LEVEL: info
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  backend:
    image: ghcr.io/lesisty7/quotenode/quotenode-api:latest
    depends_on:
      postgres: { condition: service_healthy }
      gotenberg: { condition: service_healthy }
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: web
      PDF_ENABLED: "true"
      PDF_GOTENBERG_URL: http://gotenberg:3000
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 45s
    restart: unless-stopped

  frontend:
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend:latest
    depends_on:
      backend: { condition: service_healthy }
    ports:
      - "80:80"
      - "443:443"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:80/"]
      interval: 15s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  postgres_data:
  backend_uploads:
  backend_pdfs:

Paso 4 - Iniciar QuoteNode

docker compose up -d

Docker descargara las imagenes y arrancara todos los servicios. Puedes seguir el arranque con:

docker compose logs -f backend

Espera hasta ver una linea como Started QuoteNodeApplication; eso indica que el backend ya esta listo.

Paso 5 - Abrir QuoteNode

Abre http://localhost en tu navegador.

Credenciales por defecto:

Campo	Valor
Email	`[email protected]`
Password	`Admin123!`

Cambia la contrasena por defecto inmediatamente despues de iniciar sesion, en Settings > My Profile > Change Password.

Que se esta ejecutando

Despues de docker compose up, tendras 4 contenedores:

Contenedor	Funcion	RAM
`postgres`	Almacena todos tus datos	~256 MB
`backend`	API Java y logica de negocio	~512 MB - 1.5 GB
`gotenberg`	Convierte HTML a PDF	~200 MB
`frontend`	Sirve la UI web y el proxy inverso	~20 MB

Total aproximado: 1.5 - 2.5 GB de RAM.

Comandos habituales

# Comprobar si todos los servicios siguen en marcha
docker compose ps

# Ver logs de todos los servicios
docker compose logs -f

# Ver logs solo del backend
docker compose logs -f backend

# Detener QuoteNode
docker compose down

# Actualizar a la ultima version
docker compose pull && docker compose up -d

Mantener seguros tus secretos

Tu archivo .env contiene secretos criptograficos unicos para tu instalacion. Entender que protege cada uno te ayuda a planificar la estrategia de backup:

Secreto	Que protege	Si se pierde
`DB_PASSWORD`	Acceso a la base de datos	Recuperable; se puede resetear con herramientas de administracion de PostgreSQL
`DB_ENCRYPTION_KEY`	Codigos MFA, contrasena SMTP, clave API de FX y, cuando `ENCRYPT_PII=true`, todos los campos PII	Ilegible para siempre; esos campos no pueden descifrarse sin la clave original
`TIMING_TOKEN_SECRET`	Tokens anti timing attack	Se puede regenerar; se invalidan los tokens existentes y los usuarios vuelven a autenticarse
`PUBLIC_LINK_PASSWORD_SESSION_SECRET`	Sesiones de enlaces publicos	Se puede regenerar; las sesiones activas expiran pero los enlaces siguen funcionando

El secreto critico es DB_ENCRYPTION_KEY. Los demas pueden regenerarse con molestias menores. Pero DB_ENCRYPTION_KEY cifra datos en reposo, y perderlo significa perder esos campos para siempre. Si ENCRYPT_PII=true, esto incluye tambien nombres, correos, telefonos y datos fiscales de clientes, contactos, proveedores y usuarios.

Para produccion recomendamos:

Guardar una copia de .env en un gestor de contrasenas
Para maxima seguridad, imprimir los secretos y guardarlos en una caja fuerte
No subir nunca .env al control de versiones

Recuperacion si se pierde `.env`

Si pierdes .env pero tienes una copia no cifrada de la base de datos (modo de backup por defecto), puedes recuperar tus datos:

Crea un .env nuevo con secretos nuevos
Restaura la base de datos desde tu backup con pg_dump / pg_restore
Todos los datos de negocio, como clientes, ofertas, productos y usuarios, seguiran siendo accesibles
Solo se pierden algunos campos: codigos MFA, contrasena SMTP y clave API de FX. Si ENCRYPT_PII=true estaba activado, tambien se pierde toda la informacion PII

Si tus backups estan cifrados con GPG mediante BACKUP_GPG_RECIPIENT, necesitas la clave privada GPG para descifrarlos primero.

Despliegue en produccion

Para usar QuoteNode en produccion necesitas:

Generar secretos reales. Nunca uses los valores de ejemplo:

# Genera una clave hex de 64 caracteres para el cifrado de base de datos
openssl rand -hex 32

# Genera secretos aleatorios para tokens
openssl rand -base64 32

Configurar un dominio con HTTPS. Ajusta DOMAIN y CORS_ALLOWED_ORIGINS a tu dominio real. El contenedor frontend con Caddy obtiene certificados de Let’s Encrypt automaticamente.
Configurar el correo con una de estas rutas:

Preferida: configurar SMTP mas tarde en Settings > Email SMTP dentro de QuoteNode. En el codigo actual, los ajustes SMTP del tenant se guardan en la base de datos y la contrasena se cifra antes de persistirse.
Fallback: si necesitas SMTP listo antes del primer login, define esto en .env:

SMTP_HOST=smtp.yourprovider.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-smtp-password
SMTP_AUTH=true
SMTP_STARTTLS=true

Si eliges la configuracion desde el panel administrativo, asegurate de respaldar bien DB_ENCRYPTION_KEY, porque la contrasena SMTP se cifra con esa misma clave.

Respaldar tu .env antes de cualquier otra cosa. Consulta la seccion Mantener seguros tus secretos.
Activar backups de la base de datos. Consulta Backup & Recovery.
Revisar todos los ajustes usando Environment Variables Reference para la lista completa de variables.

Para opciones de despliegue avanzadas, como Coolify PaaS, workers de backup o GeoIP, consulta Deployment Options.

Actualizar QuoteNode

Para actualizar a la ultima version:

docker compose pull && docker compose up -d

Las actualizaciones nunca modifican tu archivo .env. Docker descarga nuevas imagenes, pero tu configuracion y tus datos siguen intactos. No borres ni recrees .env durante las actualizaciones.

Las migraciones del esquema de base de datos se ejecutan automaticamente al arrancar el backend. No hace falta un paso manual de migracion.

Resolucion de problemas

El backend no arranca

Revisa los logs con docker compose logs backend. Problemas comunes:

La base de datos no esta lista. El backend espera a que PostgreSQL este sano y reintenta automaticamente.
Secretos invalidos. DB_ENCRYPTION_KEY debe tener exactamente 64 caracteres hexadecimales. DB_PASSWORD debe coincidir entre el backend y PostgreSQL.
Conflicto de puertos. Si los puertos 80 o 443 ya estan en uso, cambia el mapeo ports en docker-compose.yml.

No se puede conectar a QuoteNode

Verifica que todos los contenedores esten en ejecucion con docker compose ps
Comprueba que el contenedor frontend este marcado como healthy
Para pruebas locales, entra por http://localhost, no por https://

Olvide la contrasena del admin

Usa una via de recuperacion no destructiva:

Si SMTP esta configurado, empieza por el flujo de la pantalla de login: Forgot your password?
Si otro administrador todavia puede entrar, abre Users en el panel administrativo y restablece la contrasena desde alli. Los administradores pueden definir una nueva contrasena y forzar el cambio en el siguiente inicio de sesion.
Si ningun administrador puede iniciar sesion y el reset por correo no esta disponible, tratalo como un incidente de recuperacion operativa. Recupera el acceso desde una copia valida o usa el procedimiento interno de mantenimiento de ese entorno.

docker compose down -v no es un procedimiento de reset de contrasena. Ese comando recrea toda la instancia y borra todos los datos persistidos, incluidos usuarios, ofertas, clientes, ajustes y copias almacenadas localmente. Usalo solo en entornos de prueba locales y desechables cuando quieras reiniciar toda la instancia de forma intencionada.

Ver tambien: Restablecer una contrasena y Backup y recuperacion.

Siguientes pasos

Configuration Guide - branding, plantillas de correo y ajustes de seguridad
Environment Variables Reference - catalogo completo de .env y variables Docker Compose
Deployment Options - Coolify, topologia de produccion y backup workers
Backup & Recovery - backups automatizados con cifrado