Skip to content

Environment Variables Overview

Bumper's behavior can be tailored by setting environment variables before startup. Below is a list of all variables that the Python application reads, grouped by category. Variables not listed here are hardcoded or not configurable via environment.


⏰ Timezone

Variable Default Description
TZ UTC Timezone for scheduling and log timestamps. Set to any IANA zone, e.g., Europe/Berlin.
SYNC_TIMEZONE false Sync the server clock and timezone offset to robots when they connect over MQTT.

⚙️ Feature Flags

Variable Default Description
CA_CERT_API_ONLY_BUMPER_CERT false If true, only the self-signed Bumper CA is served. If false, the bundle also carries the original system CA.
USER_USERNAME_DEFAULT bumper Username the local account is presented with.
USER_NICKNAME_DEFAULT USER_USERNAME_DEFAULT Display name of the local account. Shown as the member name in the app.
USER_MAIL_DEFAULT ${USER_USERNAME_DEFAULT}@home.local Mail address the local account is presented with.
PHOTO_MAX_PER_DEVICE 20 How many uploaded files are kept per robot, pictures and cleaned maps alike. The oldest are dropped on every new upload.
CLEAN_LOG_MAX_PER_DEVICE 100 How many clean log entries are kept per robot. The oldest are dropped on every new one.
WEBVIEW_TRUSTED_HOST_SUFFIXES ecovacs.com,ecovacs.cn,ecouser.net,... Hosts the app may open in a webview. The app ships the Ecovacs domains as a fallback, add the host this instance is reached under.

📁 Paths & Files

Variable Default Description
BUMPER_DATA $PWD/data Directory for persistent data, uploads and caches.
DB_FILE ${BUMPER_DATA}/bumper.db TinyDB database file. The file holds JSON, not SQL.
BUMPER_ACCOUNT_KEY ${BUMPER_DATA}/account.key RSA key used to decrypt account fields the app encrypts. Mode 0600.
BUMPER_CERTS $PWD/certs Directory for TLS certificate files.
BUMPER_VOICES ${BUMPER_DATA}/voices Directory for the voice files the robot downloads.
BUMPER_CODEPUSH ${BUMPER_DATA}/codepush Directory for the CodePush packages the app downloads.
BUMPER_CA_CERT ${BUMPER_CERTS}/ca.crt Path to the CA certificate. BUMPER_CA is accepted as a deprecated alias.
BUMPER_CA_KEY ${BUMPER_CERTS}/ca.key Path to the CA private key.
BUMPER_CA_PEM ${BUMPER_CERTS}/ca.pem Path to the combined server key, server certificate and CA certificate.
BUMPER_CERT ${BUMPER_CERTS}/bumper.crt Path to the server certificate.
BUMPER_KEY ${BUMPER_CERTS}/bumper.key Path to the server private key.

🔐 Certificates

Variable Default Description
BUMPER_CA_VALID_DAYS 6669 CA certificate validity in days (about 18 years). Long duration for home-hosted self-signed stability.
BUMPER_VALID_DAYS 666 Server certificate validity in days (about 22 months). Practical rotation cycle for home management.
CERT_KEY_TYPE ec Key algorithm. Accepts only ec (P-256 elliptic curve) or rsa.
CERT_RSA_KEY_SIZE 2048 RSA key size in bits. Must be 2048 to 4096. Ignored for EC keys.

🔒 Authentication

Variable Default Description
TOKEN_VALIDITY_SECONDS 2592000 Portal-token session lifetime in seconds (30 days).
ACCESS_TOKEN_VALIDITY_SECONDS 1800 OAuth access JWT lifetime in seconds (30 minutes).
REFRESH_TOKEN_VALIDITY_SECONDS 2592000 OAuth refresh JWT lifetime in seconds (30 days).
TOKEN_JWT_ALG Follows key type Algorithm used to sign app tokens. Defaults to ES256 for EC keys and RS256 for RSA keys.

Bumper does not verify Ecovacs request signatures. See Authentication for the full flow.


🌐 Networking

Variable Default Description
BUMPER_LISTEN Auto-detected via system DNS IP address or hostname to bind all server listeners (Web, MQTT, XMPP).
BUMPER_ANNOUNCE_IP ${BUMPER_LISTEN} IP advertised to robots. If 0.0.0.0, set explicitly.
WEB_SERVER_HTTPS_PORT 443 Port for the HTTPS web UI and API.
WEB_SERVER_LISTEN_PORT 8007 Port for the plain HTTP web UI and API.
MQTT_LISTEN_PORT 1883 Plain MQTT listener.
MQTT_LISTEN_PORT_TLS 8883 TLS MQTT listener.
XMPP_LISTEN_PORT_TLS 5223 TLS XMPP listener.
HELPER_BOT_TIMEOUT 10 Seconds the helper bot waits for a robot to answer. The app gives up on a request after 15 seconds, so a longer wait is never seen by it.
CODEPUSH_LOCAL_PACKAGE false Serve the CodePush package from this server instead of the cloud. The app then downloads it from the host of the CodePush service, which has to be one that the DNS override points at Bumper.

🚦 Logging & Debugging

Variable Default Description
DEBUG_BUMPER_LEVEL INFO Log level (NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL).
DEBUG_BUMPER_VERBOSE 1 Verbose output per log line (integer 0, 1, 2).
DEBUG_LOGGING_API_REQUEST false Log incoming API requests.
DEBUG_LOGGING_API_REQUEST_MISSING false Log requests that no route matches.
DEBUG_LOGGING_XMPP_REQUEST false Log XMPP requests before internal changes.
DEBUG_LOGGING_XMPP_REQUEST_REFACTOR false Log XMPP requests after internal changes.
DEBUG_LOGGING_XMPP_RESPONSE false Log XMPP server responses.
DEBUG_LOGGING_SA_RESULT false Log service-autonomy outputs from API requests by /sa.

🔗 Proxy & Forwarding

Variable Default Description
BUMPER_PROXY_MQTT false Forward MQTT traffic to the Ecovacs cloud.
BUMPER_PROXY_WEB false Forward web traffic to the Ecovacs cloud.
PROXY_PUBLISH_TIMEOUT 10 Seconds a proxied MQTT publish may wait before it is reported as timed out.

🚢 Docker Compose & Swarm Variables

These additional environment variables are used in the compose files to control service deployment and container behavior.

Variable Default Description
NODE_ROLE manager Docker Swarm role constraint for service placement (manager or worker).
NETWORK_MODE bridge Docker network driver (bridge or overlay).
RESOURCES_LIMITS_CPUS 0.25 CPU limit per container.
RESOURCES_LIMITS_MEMORY 250m Memory limit per container.
RESOURCES_RESERVATIONS_CPUS 0.001 CPU reservation per container.
RESOURCES_RESERVATIONS_MEMORY 32m Memory reservation per container.
VERSION_BUMPER latest Bumper image tag to deploy. The image reports its build version under the same name.
VERSION_NGNIX 1.29-alpine3.22-slim NGINX image tag for the reverse proxy.
TZ Europe/Berlin Timezone inside containers (binds to host timezone).
BUMPER_ANNOUNCE_IP required IP address advertised to robots. Falls back to auto-detection if unset.
BUMPER_LISTEN 0.0.0.0 Bind interface inside the container for Bumper listeners.
DEBUG_BUMPER_LEVEL INFO Logging level inside containers.
DEBUG_BUMPER_VERBOSE 1 Verbose detail per log line inside containers.