Application
Core application settings including database, timezone, proxy configuration, and logging.
Application Settings
| Variable | Description | Default |
|---|---|---|
APP_KEY | Application encryption key (required) | - |
APP_URL | Full URL where the app is accessible | http://localhost:2226 |
APP_DEBUG | Enable debug mode (set to false in production) | false |
APP_DISPLAY_TIMEZONE | Timezone for UI, backup filenames, and crons | UTC |
API_RATE_LIMIT | Max API requests per minute, per token | 300 |
API Rate Limit
Requests to the standard /api/v1/* endpoints (not the agent daemon endpoints, see below) are capped at API_RATE_LIMIT per minute. The budget is keyed by API token where one is present, falling back to the authenticated user and then the client IP for the rare request that carries neither. Exceeding it returns 429 Too Many Requests.
This only covers the API. The web UI is unaffected: Livewire requests, including auto-refreshing pages, go through the web routes and are never counted against this limit.
API_RATE_LIMIT=600
Set it to 0 to turn throttling off, for instance when a reverse proxy or API gateway in front of Databasement already enforces its own limits.
Agent daemon endpoints (/api/v1/agent/*) are excluded from API_RATE_LIMIT entirely: agents poll on a fixed interval and have their own protection against repeated authentication failures.
Generating the Application Key
The APP_KEY is required for encryption. Generate one with:
docker run --rm davidcrty/databasement:1 php artisan key:generate --show
Copy the output (e.g., base64:xxxx...) and set it as APP_KEY.
Rotating the Application Key
APP_KEY encrypts every stored credential (database server and SSH passwords, SSH keys, volume and notification secrets, SSO tokens, two-factor secrets). Replacing it outright makes all of them unreadable, so rotate it in this order:
-
Generate a new key (see above).
-
Move the current key to
APP_PREVIOUS_KEYSand set the new one asAPP_KEY:APP_KEY=base64:new-keyAPP_PREVIOUS_KEYS=base64:old-key -
If
BACKUP_ENCRYPTION_KEYis not set, set it to the old key. Encrypted backups useAPP_KEYby default, andAPP_PREVIOUS_KEYSdoes not apply to them, so without this step existing encrypted backups can no longer be restored. See Encrypted Backups. -
Restart the application and the queue worker. Users are logged out once.
-
Re-encrypt the stored values with the new key:
php artisan key:reencryptIt prints a count per column and is safe to run again. A value that neither key can decrypt is left unchanged and reported; enter that credential again in the UI.
-
Confirm nothing needs the old key any more, then remove
APP_PREVIOUS_KEYSand restart:php artisan key:reencrypt --check--checkchanges nothing and exits non-zero while a value still needs a previous key.
Copies of Databasement's own database taken before the rotation can still be decrypted with the old key. If the old key leaked, also change the credentials themselves (database passwords, storage and notification secrets) at their source and update them in Databasement, and in step 3 set BACKUP_ENCRYPTION_KEY to a newly generated key instead, so new backups do not use the leaked one. Keep the old key somewhere safe: restoring a backup encrypted before the rotation needs it set back as BACKUP_ENCRYPTION_KEY for that restore.
Timezone Configuration
Set APP_DISPLAY_TIMEZONE to display dates, backup filenames, and schedule times in your local timezone. A cron like 0 2 * * * will then fire at 02:00 in that zone.
APP_DISPLAY_TIMEZONE=Europe/London
See the list of supported timezones.
Data is always stored in UTC internally. If you previously set TZ, it is migrated automatically — no action needed.
Database Configuration
Databasement needs a database to store its own data (users, servers, backup configurations).
SQLite (Simplest)
DB_CONNECTION=sqlite
DB_DATABASE=/data/database.sqlite
When using SQLite, make sure to mount a volume for /data to persist data.
MySQL / MariaDB
Create a database and user for Databasement on your MySQL server:
MySQL:
CREATE DATABASE databasement CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'databasement'@'%' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON databasement.* TO 'databasement'@'%';
FLUSH PRIVILEGES;
DB_CONNECTION=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_DATABASE=databasement
DB_USERNAME=databasement
DB_PASSWORD=your-secure-password
PostgreSQL
Create a database and user for Databasement on your PostgreSQL server:
PostgreSQL:
CREATE DATABASE databasement;
CREATE USER databasement WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE databasement TO databasement;
DB_CONNECTION=pgsql
DB_HOST=your-postgres-host
DB_PORT=5432
DB_DATABASE=databasement
DB_USERNAME=databasement
DB_PASSWORD=your-secure-password
Reverse Proxy / Trusted Proxies
When running behind a reverse proxy (nginx, Traefik, Kubernetes Ingress), configure trusted proxies so Laravel can correctly determine the client IP and protocol. See the Troubleshooting section if you have issues with proxy configuration.
| Variable | Description | Default |
|---|---|---|
TRUSTED_PROXIES | IP addresses or CIDR ranges of trusted proxies | 127.0.0.0/8,10.0.0.0/8,100.64.0.0/10,169.254.0.0/16,172.16.0.0/12,192.168.0.0/16 |
Alternative values:
*- Trust all proxies (simplest option for containerized environments)- Comma-separated IPs/CIDRs:
10.0.0.1,192.168.1.0/24- Trust specific proxies only - Empty - Trust no proxies
Checks the Troubleshooting section for help with proxy configuration.
Analytics
Databasement sends no analytics. To track visits with your own tool, set ANALYTICS_SNIPPET to the HTML its
setup page gives you: it is added as-is to the <head> of every page, and nothing is added when it is unset.
| Variable | Description | Default |
|---|---|---|
ANALYTICS_SNIPPET | HTML added to the <head> of every page | - |
# Umami
ANALYTICS_SNIPPET='<script defer src="https://umami.example.com/script.js" data-website-id="your-website-id"></script>'
# Plausible
ANALYTICS_SNIPPET='<script defer data-domain="databasement.example.com" src="https://plausible.io/js/script.js"></script>'
The snippet is trusted HTML and runs on every page, including for logged-in users. Only paste code from a provider you trust.
Private CA / Self-Signed Certificates
Connections to OAuth providers, and from a remote agent to the Databasement server,
verify TLS certificates against the system CAs. When your identity provider or server uses a certificate signed by a
private CA, point TLS_CA_BUNDLE to that CA in PEM format, mounted into the container (on the agents too).
| Variable | Description | Default |
|---|---|---|
TLS_CA_BUNDLE | PEM file of the CAs to trust instead of the system's | system CAs |
TLS_VERIFY | Set to false to skip certificate verification | true |
TLS_CA_BUNDLE=/certs/ca.pem
The bundle replaces the system CAs for these connections rather than adding to them, so it must hold every CA they need: append your CA to the system bundle if you also sign in with Google, GitHub or gitlab.com.
TLS_VERIFY=false accepts any certificate, including one presented by an attacker on the network path. Prefer
TLS_CA_BUNDLE, and keep TLS_VERIFY=false for testing.
Logging
| Variable | Description | Default |
|---|---|---|
LOG_CHANNEL | Logging channel | stdio |
LOG_LEVEL | Minimum log level | debug |
LOG_STDERR_FORMATTER | Monolog formatter for stdio and stderr | plain text (JSON in the Helm chart) |
stdio sends warnings and errors to stderr and the rest to stdout, so journald, Cockpit and Kubernetes show errors as
errors. stderr sends everything to stderr. single and daily write to storage/logs/ instead of the container output.
For one JSON object per entry (stack traces included), set the following. The Helm chart does this by default
(logging.formatter; set it to "" for plain text).
LOG_STDERR_FORMATTER=Monolog\Formatter\JsonFormatter
Complete Example
Here's a complete .env file for a production deployment with MySQL:
# Application
APP_DEBUG=false
APP_URL=https://backup.yourdomain.com
APP_KEY=base64:your-generated-key-here
# APP_DISPLAY_TIMEZONE=UTC # timezone for UI, backup filenames, and schedules
# Database (for Databasement itself)
DB_CONNECTION=mysql
DB_HOST=mysql.yourdomain.com
DB_PORT=3306
DB_DATABASE=databasement
DB_USERNAME=databasement
DB_PASSWORD=secure-password-here
# Logging
LOG_CHANNEL=stdio
LOG_LEVEL=warning
Troubleshooting
Enable Debug Mode
Enable debug mode to access detailed diagnostics:
APP_DEBUG=true
Then visit https://your-domain.com/health/debug to view:
- Current IP address and whether it's from a trusted proxy
- Request headers (including
X-Forwarded-For,X-Forwarded-Proto) - Application configuration
Debugging Trusted Proxies
If your application shows HTTP instead of HTTPS, or shows the wrong client IP:
-
Enable debug mode (see above)
-
Visit
/health/debugand check:is_trusted_proxy: Should betruesecure: Should betruefor HTTPSheaders: Checkx-forwarded-forandx-forwarded-proto
-
Common issues:
is_trusted_proxy: false→ The proxy IP is not in yourTRUSTED_PROXIESlistsecure: falsewith HTTPS → Trusted proxy not configured, sox-forwarded-protoheader is ignored
-
Quick fix: Set
TRUSTED_PROXIES=*to trust all proxies
More troubleshooting
If you encounter issues, see the Docker Compose Troubleshooting section for common problems and solutions.
See also Docker Networking if you're having issues connecting to your database server.
Run Artisan Commands
php artisan migrate:status # Check database migrations
php artisan config:show database # View database configuration
Reset a User Password
If you lose access to an account and email delivery is not configured (so the Forgot password? link cannot send a reset email), reset the password directly from the container. Run this from the directory that holds your docker-compose.yml:
docker compose exec app php artisan user:reset-password you@example.com
The command prompts for the new password (hidden input) and validates it against the app's password rules. Omit the email to be prompted for it as well.
Get Help
- Check the logs:
docker compose logs app - Report issues on GitHub