Saltar al contenido principal

Referencia de configuración

Memship se configura con variables de entorno, normalmente definidas en un fichero .env junto a docker-compose.yml. Copia .env.example a .env y ajústalo. Esta página documenta todos los ajustes que lee el backend.

En inglés: Configuration reference. En català: Referència de configuració.

Mínimo para producción: cambia SECRET_KEY y DB_PASSWORD, pon en IMAGE_TAG una versión publicada y configura el correo.

Disposición del despliegue

VariablePor defectoDescripción
MEMSHIP_DATA_ROOT./dataRuta absoluta que contiene todas las rutas persistentes: base de datos, archivos subidos, estado del planificador, certificados TLS y copias de seguridad. Haz copia de seguridad de ella. Ver la Instalación.
SITE_ADDRESS(vacío)La dirección que sirve Caddy. Un nombre de máquina sin más (memship.example.com) hace que Caddy obtenga automáticamente un certificado de Let’s Encrypt; vacío sirve HTTP sin cifrar en el puerto 80.
HOST_UID1001Uid con el que se ejecutan los contenedores del backend. Ponle tu id -u para que los archivos subidos montados con bind mount sean tuyos y se puedan leer sin sudo.
HOST_GID1001Gid, igualmente: tu id -g.

scripts/install.sh define las cuatro por ti.

Seguridad

VariablePor defectoDescripción
SECRET_KEY(se genera en storage/session.key)Firma las cookies de sesión y los códigos QR del carné de socio, y de ella se deriva la clave que cifra las credenciales guardadas de las pasarelas de pago. Si la dejas en blanco, se genera una clave propia de la instalación en el primer arranque; defínela explícitamente si quieres que sobreviva a la pérdida del directorio de datos. Genérala con openssl rand -hex 32. Los valores de ejemplo que vienen en los ficheros de ejemplo se reconocen y se ignoran: cualquier cosa firmada con una clave publicada se puede falsificar.
SESSION_KEY_FILE<STORAGE_LOCAL_PATH>/session.keyDónde se guarda la clave de firma generada automáticamente cuando SECRET_KEY está en blanco. Tiene que estar en almacenamiento persistente; si no, cada reinicio cierra la sesión de todos los usuarios y las credenciales de pago guardadas dejan de poder descifrarse.
COOKIE_SECURE(se deduce de FRONTEND_URL)Fuerza a activado o desactivado el atributo Secure de la cookie de sesión. Por defecto se lee el esquema de FRONTEND_URL, que es lo correcto salvo que el TLS lo termine un proxy anterior que hable HTTP sin cifrar con Caddy: ahí, pon true.
MEMSHIP_SECRET_KEY(se genera en storage/secret.key)Cifra las credenciales de SSO y de las pasarelas de pago guardadas en la base de datos. Defínela explícitamente: una clave generada automáticamente vive solo en el directorio de datos, así que una máquina reconstruida no puede descifrar sin ella una copia de seguridad restaurada. Cambiarla deja ilegibles las credenciales guardadas.
SECRETS_KEY_FILE<STORAGE_LOCAL_PATH>/secret.keyDónde se guarda la clave generada automáticamente cuando MEMSHIP_SECRET_KEY no está definida. Tiene que estar en almacenamiento persistente; si no, las credenciales guardadas se vuelven ilegibles tras un reinicio.
ACCESS_TOKEN_EXPIRE_MINUTES30Duración del token de acceso, en minutos.

Base de datos

VariablePor defectoDescripción
DB_PASSWORDmemshipCámbiala. Contraseña de PostgreSQL que usa Compose.
DATABASE_URLpostgresql://memship:memship@localhost:5433/memship_dbCadena de conexión completa. En Compose apunta al servicio db.

Aplicación

VariablePor defectoDescripción
APP_ENVdevelopmentPonla a production en los despliegues. Afecta al comportamiento de depuración y a si se exponen los documentos de la API.
APP_VERSION(de la imagen / etiqueta de git)Se incorpora a la imagen al construirla; déjala sin definir cuando uses imágenes publicadas.
DEFAULT_LOCALEesIdioma por defecto de la interfaz: es, ca o en.
CORS_ORIGINShttp://localhost:3000Lista separada por comas de los orígenes de navegador permitidos. Pon la URL o URL de tu sitio.
FRONTEND_URLhttp://localhost:3000URL pública del frontend; se usa en los enlaces de los correos.
TRUSTED_PROXY_HOPS1Cuántos proxies hay delante de la API. Cada uno añade a X-Forwarded-For el par del que aceptó la conexión, así que la dirección de quien llama está a ese número de entradas desde la derecha. 1 es el Caddy incluido. El frontend no cuenta como salto: sus rutas de proxy pasan la cabecera sin cambios, así que la API ve la misma cadena tanto si la petición llegó a través de ellas como si fue directa a /api/v1. Súbelo si pones cualquier otra cosa delante (una CDN, un balanceador de carga, tu propio proxy inverso); si no, el límite de intentos de inicio de sesión por IP asigna a todos los que llaman la IP de ese proxy y limita todo tu sitio a la vez. Ponlo a 0 solo si la API está publicada sin nada delante, lo que hace que la cabecera la ponga quien llama y que el límite por IP se pueda eludir.
BACKEND_PUBLIC_URLhttp://localhost:8003URL del backend accesible públicamente para las notificaciones de las pasarelas de pago (p. ej. Ds_Merchant_MerchantURL de Redsys). En producción tiene que ser el nombre de máquina externo al que la pasarela pueda hacer POST.

Puertos

Se definen en .env para la plataforma de Compose (los valores por defecto están en .env.example):

VariablePor defectoDescripción
HTTP_PORT80Puerto HTTP de Caddy.
HTTPS_PORT443Puerto HTTPS de Caddy.
API_PORT8003Puerto directo de la API del backend.
DB_PORT5433Puerto de PostgreSQL en la máquina.

Correo

El correo está desactivado salvo que haya definida una clave de API de Resend o un servidor SMTP. Mira Envío de correo para un recorrido completo.

Resend (preferido, envío gestionado):

VariablePor defectoDescripción
RESEND_API_KEY(vacío)Activa el envío con Resend.
RESEND_FROM_EMAIL(vacío)Dirección de remitente verificada.

SMTP (alternativa autoalojada):

VariablePor defectoDescripción
SMTP_HOST(vacío)Activa el envío por SMTP si se define.
SMTP_PORT587Puerto SMTP.
SMTP_USER(vacío)Usuario SMTP.
SMTP_PASSWORD(vacío)Contraseña SMTP.
SMTP_FROMnoreply@memship.localDirección del remitente.
SMTP_SECURITYstarttlsstarttls, ssl (puerto 465) u off.
SMTP_TLStrueObsoleta: true significa starttls y false significa off. Manda SMTP_SECURITY.

Si están configurados los dos, tiene prioridad Resend.

Todas las variables de arriba se pueden definir también desde Configuración → Integraciones → Correo, incluido el servidor SMTP. Una vez guardada esa pantalla, sus valores mandan y el proveedor activo es el que ella seleccione: ver Envío de correo.

Tareas en segundo plano (Celery / Redis)

VariablePor defectoDescripción
CELERY_BROKER_URLredis://localhost:6379/0Broker de Redis para el correo asíncrono, la facturación recurrente y los recordatorios, y donde se cuentan los límites de intentos de inicio de sesión y de restablecimiento de contraseña, para que todos los procesos de la API los compartan. Redis va incluido en la plataforma de Compose.
CELERY_CONCURRENCY2Procesos del worker. Cada uno ocupa unos 50 MiB en reposo. El valor por defecto del propio Celery es uno por CPU, que hace crecer la memoria del worker con la máquina y no con la carga de trabajo; las tareas programadas son ligeras, así que dos bastan. Súbelo solo si el correo en cola se acumula.

El worker y el planificador (Celery beat) se ejecutan como parte de la plataforma y se encargan de los correos asíncronos, la generación programada de cuotas y los recordatorios de pago.

Copias de seguridad fuera del servidor

Las lee scripts/push-backup.sh, nunca la aplicación. Mira Copias de seguridad y restauración para preparar cada destino.

VariablePor defectoDescripción
BACKUP_TARGET(vacío)Adónde van las instantáneas: ssh://user@host[:port]/absolute/path o s3://bucket[/prefix]. Es obligatoria para ejecutar el script.
BACKUP_RETENTION_DAYS30Las instantáneas más antiguas que esto se borran del destino tras un envío correcto.
BACKUP_SSH_KEY(por defecto de ssh)Fichero de identidad para un destino ssh://.
BACKUP_S3_ACCESS_KEY_ID(vacío)Clave de acceso para un destino s3://.
BACKUP_S3_SECRET_ACCESS_KEY(vacío)Su secreto. Se pasa al contenedor por el entorno, nunca en una línea de órdenes.
BACKUP_S3_REGIONus-east-1Región del bucket.
BACKUP_S3_ENDPOINT(AWS)Endpoint de un almacenamiento que no sea AWS, p. ej. https://s3.eu-central-003.backblazeb2.com.
BACKUP_AWS_CLI_IMAGEamazon/aws-cli:2.27.0La imagen que ejecuta un envío a s3://.

Almacenamiento de archivos

VariablePor defectoDescripción
STORAGE_LOCAL_PATHstorageRuta dentro del contenedor para los archivos subidos (logotipos, imágenes de actividades, PDF). Se monta con bind mount desde $MEMSHIP_DATA_ROOT/storage, que contiene además secret.key: inclúyela en las copias de seguridad.
MAX_UPLOAD_SIZE_MB10Tamaño máximo de un archivo subido, en megabytes.

Servidor

VariablePor defectoDescripción
HOST0.0.0.0Dirección de escucha del backend.
PORT8000Puerto del backend dentro del contenedor.

Migraciones

VariablePor defectoDescripción
RUN_MIGRATIONS(puesta a 1 en Compose)Con 1, el backend ejecuta las migraciones de la base de datos al arrancar. Ver Actualización.

Documentación generada desde memship v3.3.1-25-g38618db (rama main) el . Sigue el desarrollo, no la última versión publicada, así que puede describir cambios aún sin publicar.