Advanced config
Databasus runs with sensible defaults out of the box — a standard single-container install needs no configuration at all. Every variable on this page is optional. The most of these variables are used for cloud. As Databasus is fully open source, anyone can use these variables as well despite they are not needed in 99% of production setups
OAuth
By default Databasus uses email and password sign-in. You can additionally let people sign in with their Google or GitHub account. A provider's button appears as soon as its client ID is set, but sign-in only completes when both the client ID and the client secret are present.
When you register the OAuth application, set its redirect (callback) URL to https://<your-domain>/auth/callback. Because of that redirect, OAuth sign-in needs your instance served over HTTPS on a public domain — see the note below.
HTTPS is required for sign-in and email. OAuth sign-in and email both need your instance reachable over HTTPS on a public domain — OAuth providers redirect the browser back to https://<your-domain>/auth/callback, and links inside emails must open for whoever receives them. A localhost-only or plain-HTTP instance cannot use these features. The simplest way to get HTTPS is the Caddy reverse proxy setup.
Create an OAuth client in the Google Cloud Console (APIs & Services → Credentials → Create credentials → OAuth client ID, application type Web application) and add https://<your-domain>/auth/callback as an authorized redirect URI.
| Variable | Description |
|---|---|
GOOGLE_CLIENT_ID | Client ID of your Google OAuth client. Setting it shows the "Sign in with Google" button. |
GOOGLE_CLIENT_SECRET | Client secret of your Google OAuth client. Required together with the ID for sign-in to work. |
GitHub
Create an OAuth app under GitHub Developer settings (Settings → Developer settings → OAuth Apps → New OAuth App) and set the authorization callback URL to https://<your-domain>/auth/callback.
| Variable | Description |
|---|---|
GITHUB_CLIENT_ID | Client ID of your GitHub OAuth app. Setting it shows the "Sign in with GitHub" button. |
GITHUB_CLIENT_SECRET | Client secret of your GitHub OAuth app. Required together with the ID for sign-in to work. |
Email (SMTP)
Connect an SMTP server so Databasus can send transactional email such as password-reset links and workspace invitations. Email is treated as configured only when both SMTP_HOST and DATABASUS_URL are set — until then, email features stay hidden in the UI.
| Variable | Description |
|---|---|
SMTP_HOST | SMTP server hostname (e.g. smtp.gmail.com). Enables email together with DATABASUS_URL. |
SMTP_PORT | SMTP server port (e.g. 587). Must be a positive integer when SMTP_HOST is set. |
SMTP_USER | Username for SMTP authentication. |
SMTP_PASSWORD | Password for SMTP authentication. For Gmail, use an App Password — not your account password. |
SMTP_FROM | The "From" address on outgoing email. |
DATABASUS_URL | Public base URL of your instance (e.g. https://backup.example.com). Used to build links inside emails. Required together with SMTP_HOST. |
Sign up captcha (Cloudflare Turnstile)
If your instance is reachable from the public internet, you can put a Cloudflare Turnstile challenge on the sign-up and sign-in forms to keep bots out. Both keys come from the Turnstile dashboard, and the challenge activates only when both are set.
To stop external sign-ups entirely rather than just challenging them, you do not need a captcha at all — open Databasus settings → Allow sign up in the UI and turn it off. That closes the sign-up form completely.
| Variable | Description |
|---|---|
CLOUDFLARE_TURNSTILE_SITE_KEY | Public Turnstile site key, used to render the widget in the browser. |
CLOUDFLARE_TURNSTILE_SECRET_KEY | Secret Turnstile key, used by the backend to validate challenge responses. |
Disable cloud notice
Databasus shows small in-app notices promoting the cloud version. We want to be transparent about why it is there: cloud subscriptions fund the open source development, so the notice is part of the trade-off that keeps Databasus free and maintained. At the same time, we know many DevOps and DBA companies deploy Databasus for their own customers and would rather not highlight that a cloud version exists. Some users simply prefer not to see the label. That is a fair ask, so the notice can be switched off entirely with IS_DISABLE_CLOUD_NOTICE.
| Variable | Default | Description |
|---|---|---|
IS_DISABLE_CLOUD_NOTICE | false | Set to true to hide the in-app notice that promotes the cloud version. |
Telemetry
Databasus sends anonymous, non-identifying usage telemetry by default. It carries no personal data and helps us understand how the project is used. You can read exactly what is collected in the privacy policy, and you can turn it off completely.
| Variable | Default | Description |
|---|---|---|
IS_DISABLE_ANONYMOUS_TELEMETRY | false | Set to true to disable anonymous usage telemetry. |
Log shipping
By default Databasus keeps its application logs inside the container. If you run central log aggregation, you can ship them to an external VictoriaLogs instance instead. Setting VICTORIA_LOGS_URL enables shipping; the username and password are only needed if your endpoint requires basic auth.
| Variable | Default | Description |
|---|---|---|
VICTORIA_LOGS_URL | — | URL of a VictoriaLogs instance to ship application logs to. Leave unset to keep logs in the container. |
VICTORIA_LOGS_USERNAME | — | Username for the VictoriaLogs endpoint, if it requires basic auth. |
VICTORIA_LOGS_PASSWORD | — | Password for the VictoriaLogs endpoint, if it requires basic auth. |
Analytics script
Databasus can inject your own analytics or tracking snippet — Google Analytics, Plausible, Umami and similar into the app. When ANALYTICS_SCRIPT is set, its value is inserted into the page <head> at startup.
Security warning: the value is injected verbatim as raw HTML and JavaScript and runs with full access to the Databasus UI in every visitor's browser. Only ever set it to a snippet you fully control and trust.
| Variable | Description |
|---|---|
ANALYTICS_SCRIPT | Custom <script> markup injected before the closing </head> tag. Leave unset to add no analytics. |
Multi-node mode
By default Databasus runs as a single self-contained container — one image with everything inside. Multi-node mode is an advanced setup that splits backup processing across several machines for much higher throughput. Almost no installation needs it. The sections below explain that default design first, then the variables for running Databasus across multiple nodes.
Why Databasus bundles PostgreSQL and Valkey
Databasus uses PostgreSQL as its internal storage (backup metadata, database configurations, audit logs, etc.) and Valkey for caching. Both are bundled inside the image. Here is why:
For users:
- You only pull one image — no extra configs, no managing other images, no tracking internal service versions, no environment variables to set. Just run
docker run, even if you manage hundreds of databases. - Auto-update covers everything — enable auto-update for the Databasus image and forget about it. There are no separate upgrade guides for internal services and no multiple image versions to keep in sync.
- The backup guide just works — it is written around the internal PostgreSQL. With an external database you would have to figure out its backup separately.
For Databasus maintainers:
- We know exactly what is inside the image — we control migrations, extensions and service configuration. That means we can safely bump internal service versions without breaking compatibility and stay focused on development.
- Users never have to touch their compose files for upgrades — PostgreSQL and Valkey versions are updated inside the image. With external services, many users would skip or delay upgrade steps and run into compatibility issues across versions.
Summing up, it is a reasonable approach for projects which focus on simple UX and do not face hundreds of RPS. GitLab CE, for example, follows the same approach.
What about performance overhead? — there is none worth noting. Databasus is network-intensive (uploading and downloading backup files to remote storage), not database-intensive. The internal PostgreSQL typically uses 100–150 MB of RAM for hundreds of backup jobs across hundreds of databases with millions of backup records. If you increase your server resources it scales accordingly, so there is no realistic chance of reaching a vertical scaling limit.
Both services are only accessible inside the container (PostgreSQL runs on port 5437, Valkey binds to 127.0.0.1 only) and are never exposed externally.
Configuring nodes
Set IS_MANY_NODES_MODE to true, then mark each node's role with the variables below. While IS_MANY_NODES_MODE is left unset, a single node acts as both the primary and a processing node. Multi-node mode also requires every node to share one external PostgreSQL and Valkey — see External services configuration below.
| Variable | Default | Description |
|---|---|---|
IS_MANY_NODES_MODE | false | Set to true to enable multi-node operation. The role variables below take effect only when this is on. |
IS_PRIMARY_NODE | — | Set to true on the primary node, which runs scheduling. |
IS_PROCESSING_NODE | — | Set to true on nodes that run backup processing. |
NODE_NETWORK_THROUGHPUT_MBPS | 125 | Node network throughput in MB/s, used when scheduling work across nodes. |
External services configuration
Databasus can run against an external PostgreSQL and Valkey instead of the bundled ones. This is what multi-node mode needs, since every node must share the same database and cache.
This is not a tested or supported configuration. We do not run migration tests against external services, so your instance may break on the next upgrade with no migration path provided. If you understand the risks — the variables are below.
The only reason we use external services ourselves is the Databasus cloud — it runs on a cluster of distributed servers that together handle up to 100 Gbit/s of throughput, so all nodes need to share the same database.
Why do we use a multi-node cluster for the cloud, but not recommend it to you even if you have hundreds of DBs? Our cloud is a public service used by thousands of users (because Databasus is the most popular PostgreSQL backup tool on GitHub now). Because it is public, we also face DDoS attacks and need far higher throughput than any typical company would. We also cannot predict or control how many databases our users connect or how many restores they run through it — some of them many terabytes in size. It's not just production use, it's permanent defence 🛡️. Your own instance is the opposite — you always know and control your own databases, so you never face that unpredictability.
Usual production use of Databasus runs from a couple of databases to hundreds of databases (in DBA outsourcing companies). For that, a regular single-server installation with the internal PostgreSQL and Valkey is the right choice — it is what we use for backing up our own databases in Databasus Labs too.
If you genuinely face the same situation as we do, the variables are below — we do not lock this ability, even though it is hard to maintain — but pin your Databasus version first.
External PostgreSQL
| Variable | Description |
|---|---|
DANGEROUS_EXTERNAL_DATABASE_DSN | Full PostgreSQL connection string. Example: postgresql://user:password@host:5432/databasus |
External Valkey
| Variable | Description |
|---|---|
DANGEROUS_VALKEY_HOST | Hostname of your Valkey instance. |
DANGEROUS_VALKEY_PORT | Port. Default 6379. |
DANGEROUS_VALKEY_USERNAME | Username. Leave empty if not set. |
DANGEROUS_VALKEY_PASSWORD | Password. |
DANGEROUS_VALKEY_IS_SSL | true or false. |
What if I need fully distributed, stateless HA? If your goal is a fully distributed, stateless HA setup where multiple application nodes share the same PostgreSQL and Valkey instances — neither Databasus, WAL-G nor pgBackRest are the right tools for that. Those are backup tools, not cluster orchestrators. For distributed PostgreSQL HA, look at purpose-built Kubernetes operators:
- CloudNativePG (CNPG) + Barman Cloud — the CNCF-backed operator with built-in WAL archiving and backup to object storage via Barman Cloud.
- PGO (Crunchy Postgres Operator) + object storage — another mature operator with pgBackRest integration and S3-compatible storage support.