Portabase Logo
Portabase Agent

Environment Variables

Complete reference of .env configuration options.

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.


VariableTypeOptionalDefaultDescription
EDGE_KEYstringNoNoneYour agent's unique key from the dashboard.
DATABASES_CONFIG_FILEstringYesconfig.jsonName of the databases configuration file mounted in /config. Set config.toml to use TOML. Only useful if you declare databases on the agent side.
TZstringYesUTCTimezone for the agent (e.g. UTC, Europe/Paris).
POLLINGnumberYes5Frequency (in seconds) to check for new tasks.
LOGstringYesinfoMinimum log level: trace, debug, info, warn or error. LOG_LEVEL is read when LOG is not set. Applies to the console and to the log file.
LOG_TO_FILEbooleanYesfalseSet to true to also write logs to /var/log/app/app.log.YYYY-MM-DD. Files rotate daily and the 7 most recent are kept. Logs always go to the standard output (docker logs). See Logs.
DATA_PATHstringYes/dataInternal path where the agent stores its data.
TMPDIRstringYes/tmpDirectory where the agent builds the temporary backup/restore archive. Point it at a disk with enough free space for your largest volume (see Docker Volume).
PORTABASE_HELPER_IMAGEstringYesNoneImage of the short-lived helper container used by Docker Volume backups and restores. By default the agent reuses its own image. Set it when the agent and the mounted socket belong to different engines (e.g. agent on Docker, socket from Podman). The image must already exist on that engine, contain sh, sleep and tar (tar is used for backups under Podman), and have no ENTRYPOINT (or one that runs the command it is given).
RETRY_ATTEMPTSnumberYes3Total attempts (not retries after the first) for a database dump, each storage upload, and the restore download. 3 means one initial try plus two retries. Must be between 3 and 5.
RETRY_BACKOFF_MSnumberYes1000Base delay between retry attempts. Doubles each attempt, with equal jitter and a 30s ceiling per wait, so the default spends at most ~3s sleeping per seam. Must be between 100 and 30000.
MAX_CONCURRENT_BACKUPSnumberYesNoneMaximum number of backups (manual and automatic) the agent runs at the same time. Extra backups wait in a queue until a slot frees up. Unset or empty means unlimited. Must be at least 1. Lower it to cap CPU, memory and disk usage when many databases are scheduled at the same time.
SSL_CERT_FILEstringYesNonePath to a CA bundle used for the agent's outgoing TLS connections. Needed when the agent must trust an internal certificate authority (see below).

Internal certificate authority: update-ca-certificates has no effect

The agent is written in Rust and uses rustls, which does not read the system CA directory. Dropping your certificate into /usr/local/share/ca-certificates/ and running update-ca-certificates satisfies tools such as curl, but the agent keeps failing with InvalidCertificate(UnknownIssuer).

Mount a CA bundle and point SSL_CERT_FILE at it instead:

docker-compose.yml
volumes:
  - ./ca-bundle.crt:/etc/ssl/certs/portabase-ca-bundle.crt:ro
environment:
  - SSL_CERT_FILE=/etc/ssl/certs/portabase-ca-bundle.crt

SSL_CERT_FILE replaces the default root store, it does not add to it. The bundle must therefore contain the standard Mozilla root certificates concatenated with your internal CA — otherwise the agent stops trusting public hosts, such as your S3 storage.


Logs

The agent always writes its logs to the standard output. Read them with docker logs portabase-agent, or portabase logs <PATH> with the CLI. LOG sets the minimum level for every output.

Since Agent 1.26.1

Log files are no longer written by default. Earlier agents always wrote /var/log/app/app.log.* with every level down to trace, whatever LOG said, and never deleted old files, which could fill the disk. If you read or ship these files, set LOG_TO_FILE=true after upgrading. Files left by earlier agents are not deleted while LOG_TO_FILE is off: remove them by hand, or enable it once and the agent keeps only the 7 most recent.

Save logs to a file

Set LOG_TO_FILE to true, and mount /var/log/app to keep the files on the host:

docker-compose.yml
services:
  app:
    image: portabase/agent:latest
    volumes:
      - ./logs:/var/log/app
    environment:
      LOG: info
      LOG_TO_FILE: "true"
  • One file per day, named app.log.YYYY-MM-DD. The date is in UTC.
  • The 7 most recent files are kept, today's included. Older files are deleted when the agent starts and at each daily rotation.
  • The file gets the same level as the standard output (LOG).

Last updated on

On this page