Configuración avanzada

Databasus funciona con valores por defecto razonables desde el primer momento: una instalación estándar de un solo contenedor no necesita configuración alguna. Todas las variables de esta página son opcionales y no hacen falta en el 99% de los despliegues en producción.

OAuth

Por defecto Databasus usa inicio de sesión con correo y contraseña. Además, puede permitir que la gente inicie sesión con su cuenta de Google o GitHub. El botón de un proveedor aparece en cuanto se define su client ID, pero el inicio de sesión solo se completa cuando están presentes tanto el client ID como el client secret.

Al registrar la aplicación OAuth, establezca su URL de redirección (callback) en https://<your-domain>/auth/callback. Debido a esa redirección, el inicio de sesión OAuth necesita que su instancia se sirva por HTTPS en un dominio público; vea la nota más abajo.

HTTPS es obligatorio para el inicio de sesión y el correo. Tanto el inicio de sesión OAuth como el correo necesitan que su instancia sea accesible por HTTPS en un dominio público: los proveedores OAuth redirigen el navegador de vuelta a https://<your-domain>/auth/callback, y los enlaces dentro de los correos deben abrirse para quien los recibe. Una instancia solo en localhost o en HTTP plano no puede usar estas funciones. La forma más simple de obtener HTTPS es la configuración del reverse proxy Caddy.

Google

Cree un cliente OAuth en la Google Cloud Console (APIs & Services → Credentials → Create credentials → OAuth client ID, tipo de aplicación Web application) y añada https://<your-domain>/auth/callback como URI de redirección autorizada.

Variable	Descripción
`GOOGLE_CLIENT_ID`	Client ID de su cliente OAuth de Google. Al definirlo se muestra el botón "Sign in with Google".
`GOOGLE_CLIENT_SECRET`	Client secret de su cliente OAuth de Google. Requerido junto con el ID para que el inicio de sesión funcione.

GitHub

Cree una aplicación OAuth en GitHub Developer settings (Settings → Developer settings → OAuth Apps → New OAuth App) y establezca la authorization callback URL en https://<your-domain>/auth/callback.

Variable	Descripción
`GITHUB_CLIENT_ID`	Client ID de su aplicación OAuth de GitHub. Al definirlo se muestra el botón "Sign in with GitHub".
`GITHUB_CLIENT_SECRET`	Client secret de su aplicación OAuth de GitHub. Requerido junto con el ID para que el inicio de sesión funcione.

Correo electrónico (SMTP)

Conecte un servidor de correo para que Databasus pueda enviar invitaciones a espacios de trabajo, códigos para restablecer la contraseña y códigos de acceso. El servidor de correo se considera configurado en cuanto se define SMTP_HOST. Sin él, la pantalla de ajustes indica que el servidor de correo no está configurado y la pantalla de inicio de sesión oculta el enlace para restablecer la contraseña.

Este es el servidor de correo de la instancia. Los canales de notificación por correo, que informan sobre las copias de seguridad, tienen su propia configuración SMTP en el formulario de cada canal. Por eso, que un canal de notificación entregue correo no dice nada de este servidor. Para comprobar el servidor de correo de la instancia, abra Databasus settings → Mail server y pulse Send test email. El mensaje llega a su propia dirección y, si la entrega falla, verá la respuesta del servidor de correo.

Si su relé no admite STARTTLS, defina SMTP_SECURITY=none antes de actualizar. En cualquier puerto distinto del 465 el modo predeterminado es starttls, que no continúa sin cifrado, así que ese relé no recibirá nada hasta que defina la variable. Si la instancia exige el código de acceso por correo, nadie podrá entrar con contraseña mientras el correo no se entregue. Para recuperar el acceso, desactive el segundo factor con docker exec -it databasus ./main --disable-2fa (consulte Dejar de pedir un código al iniciar sesión).

Variable	Descripción
`SMTP_HOST`	Nombre de host del servidor de correo (por ejemplo, `smtp.gmail.com`). Al definirla se activa el correo de la instancia.
`SMTP_PORT`	Puerto del servidor de correo (por ejemplo, `587`). Debe ser un entero positivo cuando `SMTP_HOST` está definido.
`SMTP_SECURITY`	Seguridad de la conexión: `tls`, `starttls` o `none`, descritos más abajo. Por defecto es `tls` en el puerto 465 y `starttls` en cualquier otro. Con otro valor, la instancia no arranca.
`SMTP_USER`	Nombre de usuario para la autenticación SMTP.
`SMTP_PASSWORD`	Contraseña para la autenticación SMTP. Para Gmail, use una App Password, no la contraseña de su cuenta.
`SMTP_FROM`	Dirección del remitente, sola (`noreply@example.com`) o con un nombre (`Acme Backups <noreply@example.com>`). Sin nombre, los destinatarios ven `Databasus`. Si no está definida, se usa `SMTP_USER` cuando es una dirección de correo y, si no, `noreply@` seguido de `SMTP_HOST`, de modo que un usuario como `apikey` nunca pasa a ser el remitente. Si el valor no se puede leer como dirección, la instancia no arranca.
`SMTP_HELO_NAME`	El nombre con el que la instancia saluda al servidor de correo. Por defecto es el host de `DATABASUS_URL` y, si no existe, el nombre del equipo. Debe ser un nombre de host o un literal de dirección como `[192.0.2.1]` o `[IPv6:2001:db8::1]`; de lo contrario, la instancia no arranca.
`SMTP_INSECURE_SKIP_VERIFY`	Póngalo en `true` para omitir la verificación del certificado TLS en los modos `tls` y `starttls`. Por defecto es `false`. Úselo solo con servidores con certificado autofirmado en una red de confianza: desactiva la protección contra ataques de intermediario (man-in-the-middle).
`DATABASUS_URL`	URL base pública de su instancia (por ejemplo, `https://backup.example.com`). Opcional: añade un enlace a los correos de invitación y aporta el nombre de saludo predeterminado. El correo funciona sin ella.

SMTP_SECURITY elige uno de tres modos. Los canales de notificación por correo ofrecen la misma elección en Advanced settings.

Modo	Comportamiento
`tls`	La conexión va cifrada desde el primer byte. Lo habitual en el puerto 465.
`starttls`	La conexión empieza sin cifrar y se cifra antes de enviar la contraseña o cualquier mensaje. Si el servidor no lo admite, la entrega falla en lugar de continuar sin cifrado. Lo habitual en el puerto 587.
`none`	La conexión nunca se cifra. Úselo para un relé que no admite STARTTLS, como un Postfix local en el puerto 25.

none envía la contraseña SMTP y todos los mensajes sin cifrar, y cualquiera que esté entre Databasus y el relé puede leerlos. Úselo solo con un relé en el mismo host o en una red privada de confianza.

Si su instancia es accesible desde internet, puede poner un desafío de Cloudflare Turnstile en los formularios de registro e inicio de sesión para dejar fuera a los bots. Ambas claves salen del panel de Turnstile, y el desafío se activa solo cuando las dos están definidas.

Para bloquear por completo los registros externos, en lugar de solo ponerles un desafío, no necesita captcha alguno: abra Databasus settings → Allow sign up en la interfaz y desactívelo. Eso cierra el formulario de registro por completo.

Variable	Descripción
`CLOUDFLARE_TURNSTILE_SITE_KEY`	Clave pública de sitio de Turnstile, usada para renderizar el widget en el navegador.
`CLOUDFLARE_TURNSTILE_SECRET_KEY`	Clave secreta de Turnstile, usada por el backend para validar las respuestas al desafío.

Permisos del almacenamiento Docker

Databasus suele tomar los ID numéricos del usuario y del grupo del directorio pgdata existente, después del mount de copias de seguridad o de la raíz de datos y, como último recurso, usa 999. Configure PUID o PGID solo si esa selección automática no sirve para su bind mount, recurso CIFS o exportación NFS. Deben ser enteros decimales de 1 a 4294967294.

Variable	Valor automático	Cuenta
`PUID`	Propietario del mount o `999`	Usuario `databasus`
`PGID`	Grupo del mount o `999`	Grupo principal `databasus`

Databasus y PostgreSQL usan la misma cuenta del sistema operativo sin privilegios root, llamada databasus.

El entrypoint comienza como root dentro del contenedor para elegir los ID e intentar ejecutar chown y chmod. Después comprueba todo el ciclo de archivos como databasus. Un mount puede funcionar aunque rechace cambios de propietario o modo. No se admite un valor arbitrario de Docker user:.

ERROR: Databasus cannot write to local storage paths /databasus-data/temp and /databasus-data/backups as UID 999 and GID 999.
Required operation: save a file through local storage.
Set PUID and PGID or fix the mounted directory permissions: https://databasus.com/advanced-config/#docker-storage-permissions
Details: permission denied

Las cuatro variables anteriores para servicios separados se eliminaron de forma deliberada. Quítelas de la configuración al actualizar. Si los ID elegidos automáticamente no pueden acceder a un mount, el inicio se detiene e indica la operación fallida y el enlace a esta documentación.

Telemetría

Databasus envía por defecto telemetría de uso anónima y no identificable. No contiene datos personales y nos ayuda a entender cómo se usa el proyecto. Puede leer exactamente qué se recopila en la política de privacidad, y puede desactivarla por completo.

Variable	Por defecto	Descripción
`IS_DISABLE_ANONYMOUS_TELEMETRY`	`false`	Póngalo en `true` para desactivar la telemetría de uso anónima.

Registros

Databasus escribe sus registros en stdout y los duplica como JSON en databasus.log en el volumen de datos. Defina OPEN_TELEMETRY_URL y también los exportará por OpenTelemetry a un backend como VictoriaLogs, Graylog, SigNoz, Grafana Loki, Datadog o Honeycomb, o a un OpenTelemetry Collector, que es a su vez un receptor OTLP.

El transporte sigue el esquema. http:// y https:// envían OTLP/HTTP y usan la URL literal, ruta incluida; grpc:// y grpcs:// envían OTLP/gRPC y usan solo el host y el puerto.
La autenticación va en OPEN_TELEMETRY_HEADERS o en la URL como user:password@host.
Los secretos (contraseñas, tokens, credenciales) dentro de las URL se ocultan antes de que un registro salga del proceso.
Las entradas de auditoría se envían con los registros de la aplicación etiquetadas como log_type=audit e ignoran LOG_LEVEL, así que subir el nivel nunca elimina el rastro de auditoría.

Variable	Por defecto	Descripción
`OPEN_TELEMETRY_URL`	—	URL completa del endpoint OTLP, ruta incluida. Déjela sin definir para mantener los registros en el contenedor. Una query string, un host ausente o un esquema desconocido detiene el contenedor en el arranque, en lugar de quedarse sin exportar en silencio.
`OPEN_TELEMETRY_HEADERS`	—	Pares `key=value` separados por comas que se envían con cada exportación, normalmente una clave de API. Los valores usan codificación porcentual, como en el formato estándar de `OTEL_EXPORTER_OTLP_HEADERS`.
`LOG_LEVEL`	`info`	Uno de `debug`, `info`, `warn` o `error`. Un valor no reconocido vuelve a `info`.
`LOG_FILE_IS_ENABLED`	`true`	Escribe `databasus.log` junto al resto de los datos, con rotación a los 5 MB y conservando 3 archivos antiguos. Póngalo en `false` si su plataforma ya recolecta stdout.

Valores para los backends habituales, cada uno con la cabecera que lo autentica. Reemplace hosts, regiones y claves por los suyos:

Backend	`OPEN_TELEMETRY_URL`	`OPEN_TELEMETRY_HEADERS`
VictoriaLogs	`http://victoria-logs:9428/insert/opentelemetry/v1/logs`	`Authorization=Basic%20dXNlcjpwYXNzd29yZA==` — las credenciales que espera su `vmauth` o reverse proxy, ya que VictoriaLogs no tiene autenticación propia en la ruta de ingesta.
OpenTelemetry Collector	`grpc://otel-collector:4317`	`Authorization=Bearer%20your-token` — corresponde a una extensión `bearertokenauth` o `basicauth` en el receptor. Un Collector accesible solo dentro de su red normalmente no necesita ninguna.
Graylog 6.2+	`grpc://graylog:4317`	`Authorization=Bearer%20your-token` — el token definido en la entrada OpenTelemetry (gRPC). La entrada también acepta mTLS en su lugar.
SigNoz Cloud	`grpcs://ingest.eu.signoz.cloud:443`	`signoz-ingestion-key=your-ingestion-key`
Grafana Cloud	`https://otlp-gateway-prod-eu-west-0.grafana.net/otlp/v1/logs`	`Authorization=Basic%20<base64>` — base64 de `instance-id:api-token`
Honeycomb	`https://api.honeycomb.io/v1/logs`	`x-honeycomb-team=your-api-key`
Datadog Agent	`grpc://datadog-agent:4317`	Ninguna: el Agent guarda la clave de API y reenvía los registros en su nombre.

Los valores de las cabeceras usan codificación porcentual, así que el espacio después de Basic o Bearer se escribe como %20 y una coma dentro de un valor como %2C. La autenticación básica también puede ir directamente en la URL como https://user:password@host/path: Databasus la convierte en la misma cabecera y la mantiene fuera de los registros. Por http:// y grpc:// las claves y contraseñas viajan en claro, así que use https:// o grpcs:// fuera de una red de confianza.

Script de analítica

Databasus puede inyectar en la aplicación su propio fragmento de analítica o seguimiento: Google Analytics, Plausible, Umami y similares. Cuando ANALYTICS_SCRIPT está definida, su valor se inserta en el <head> de la página al arrancar.

Advertencia de seguridad: el valor se inyecta tal cual como HTML y JavaScript sin procesar, y se ejecuta con acceso completo a la interfaz de Databasus en el navegador de cada visitante. Establézcalo únicamente con un fragmento que controle y en el que confíe plenamente.

Variable	Descripción
`ANALYTICS_SCRIPT`	Marcado `<script>` personalizado que se inyecta antes de la etiqueta de cierre `</head>`. Déjela sin definir para no añadir analítica.