Environment Variables

Portabase provides flexibility through environment variables. These let you customize application behavior, database connection, authentication and storage.

If you use Docker Compose, set these variables in your .env file at the root of the project.

Project

General instance configuration.

Variable	Type	Optional	Default	Description
`PROJECT_URL`	`string`	No	`http://localhost:8887`	Public URL of your dashboard (e.g. `https://backups.my-domain.com`). Important for generated links.
`PROJECT_SECRET`	`string`	No	`None`	Critical. Secret used to encrypt sensitive data. Generate with `openssl rand -hex 32`.
`PROJECT_NAME`	`string`	Yes	`Portabase`	Display name in the UI (site title).
`RETENTION_CRON`	`string`	Yes	`0 7 * * *`	Schedule for automatic deletion of backups according to the retention policies.
`STALE_BACKUP_THRESHOLD_HOURS`	`number`	Yes	`6`	Threshold, in hours, after which a backup without a recent successful run is flagged as stale.
`BACKUP_FOLDER_NAME`	`string`	Yes	`backups`	Folder name for storing backup files in storage channels.
`LOG_LEVEL`	`string`	Yes	`info`	Controls minimum log level. Options: `debug`, `info`, `warn`, `error`
`SKIP_ONBOARDING`	`boolean`	Yes	`false`	Skips the initial onboarding flow on first launch. Set to `true` when the instance is provisioned automatically.
`AUTH_DEFAULT_USER_NAME`	`string`	Yes	`None`	The default user name
`AUTH_DEFAULT_USER`	`string`	Yes	`None`	The default user email
`AUTH_DEFAULT_PASSWORD`	`string`	Yes	`None`	Password must contain at least 8 characters, 1 number, 1 lowercase letter, 1 uppercase letter and 1 special character
`TELEMETRY`	`boolean`	Yes	`True`	Enables anonymous usage metrics collection.
`TUSD_BEHIND_PROXY`	`boolean`	Yes	`false`	Not always required. Set to `true` when the dashboard runs behind a reverse proxy, so the tusd upload server trusts `X-Forwarded-*` headers and generates correct upload URLs. May resolve upload issues depending on your proxy configuration.

In case you want to seed the default user using .env variables, use AUTH_DEFAULT_USER_NAME, AUTH_DEFAULT_USER, and AUTH_DEFAULT_PASSWORD. These 3 variables must be filled.

API & MCP

Controls programmatic access to your dashboard.

Variable	Type	Optional	Default	Description
`API_ENABLED`	`boolean`	Yes	`false`	Enables all REST API routes under `/api/v1`. Required for both OpenAPI and MCP.
`OPENAPI_ENABLED`	`boolean`	Yes	`false`	Enables the OpenAPI specification and Swagger UI at `/api/v1/openapi` and `/api/v1/docs`. Requires `API_ENABLED=true`.
`MCP_ENABLED`	`boolean`	Yes	`false`	Enables the MCP server at `/api/v1/mcp` for AI assistant integrations. Requires `API_ENABLED=true`.

Cleanup

Scheduled maintenance jobs that permanently delete old data. Both jobs are disabled by default and each requires its own retention value to start.

Job logs cleanup

Permanently deletes old job_logs belonging to soft-deleted backups.

Variable	Type	Optional	Default	Description
`CLEANING_JOB_LOGS_ENABLED`	`boolean`	Yes	`false`	Enables the job logs cleanup cron. Set to `true` to start it.
`CLEANING_JOB_LOGS_CRON`	`string`	Yes	`0 0 * * *`	Cron schedule for the cleanup (default: every day at midnight).
`CLEANING_JOB_LOGS_RETENTION_DAYS`	`number`	No*	`None`	Days to keep logs before purge. Positive integer. Required when `CLEANING_JOB_LOGS_ENABLED=true`. The cron will not start without it.
`CLEANING_JOB_LOGS_BATCH_SIZE`	`number`	Yes	`1000`	Rows deleted per batch.

Deleted backups cleanup

Hard-deletes old soft-deleted backups; children cascade. Retention is measured from deleted_at.

Variable	Type	Optional	Default	Description
`CLEANING_BACKUPS_ENABLED`	`boolean`	Yes	`false`	Enables the deleted backups cleanup cron. Set to `true` to start it.
`CLEANING_BACKUPS_CRON`	`string`	Yes	`0 0 * * *`	Cron schedule for the cleanup (default: every day at midnight).
`CLEANING_BACKUPS_RETENTION_DAYS`	`number`	No*	`None`	Days to keep soft-deleted backups before hard-delete. Positive integer. Required when `CLEANING_BACKUPS_ENABLED=true`. The cron will not start without it.
`CLEANING_BACKUPS_BATCH_SIZE`	`number`	Yes	`100`	Rows deleted per batch.

These jobs permanently delete data. Retention days have no default: the corresponding cron will not start unless you set a positive integer when the job is enabled.

Database

Configuration for the internal Portabase PostgreSQL connection.

Variable	Type	Optional	Default	Description
`DATABASE_URL`	`string`	Yes	`None`	Database URL (e.g., `postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=public`). If not specified, the internal database will be used.

Email (SMTP)

Configuration for transactional email delivery (alerts, invitations).

If no configuration is provided, email-related features will be limited (no password reset, no email verification).

Variable	Type	Default	Description
`SMTP_HOST`	`string`	`None`	SMTP server address (e.g. `smtp.resend.com`).
`SMTP_PORT`	`string`	`None`	SMTP server port (e.g. `587`).
`SMTP_USER`	`string`	`None`	SMTP username.
`SMTP_PASSWORD`	`string`	`None`	SMTP password.
`SMTP_FROM`	`string`	`None`	From email address (e.g. `no-reply@your-domain.com`).
`SMTP_SECURE`	`string`	`false`