Environment Variables¶

All configuration parameters for the Kamerplanter backend are controlled via environment variables. Variables are loaded by pydantic-settings — case sensitivity is not relevant.

cp .env.example .env

Database Connection¶

*ARANGO_ROOT_PASSWORD is passed directly to the ArangoDB container and is required to start the database.

Cache and Task Queue¶

Format: redis://[user]:[password]@[host]:[port]/[db]

Examples:

redis://localhost:6379/0                    # Local without auth
redis://:mypassword@redis:6379/0            # With password
rediss://user:pass@redis-host:6380/1        # TLS (rediss://)

Security and Authentication¶

openssl rand -hex 32

Privacy & GDPR (REQ-025 / NFR-011)¶

These variables control the legally mandated deletion/anonymization of personal data (see Privacy (GDPR)) and are independent of the operating mode — they apply in both Light and Full mode.

Operating Mode¶

Light Mode (KAMERPLANTER_MODE=light)¶

In Light Mode, token authentication is disabled. The API is usable without login. This mode is intended for local single-user installations that are not exposed to the internet.

CORS Configuration¶

Format: Always as a JSON array in string format:

CORS_ORIGINS='["https://app.example.com","https://app2.example.com"]'

Email¶

In development mode (EMAIL_ADAPTER=console), emails are not sent but printed to the backend log.

External Data Enrichment (REQ-011)¶

GBIF is used without an API key (public API). Perenual and Tréflé require free registration.

Knowledge Service — Re-Ranking (optional)¶

These variables configure the optional cross-encoder re-ranker of the Knowledge Service. When RERANKER_URL is empty, the Knowledge Service operates in hybrid-search-only mode (graceful degradation). See ADR-007.

AI Assistant ¶

These variables belong to the Kamerplanter backend and control the three-stage toggle mechanism as well as the connection to the Knowledge Service (see AI Assistant — User Guide). Provider selection (Ollama/Anthropic/OpenAI-compatible) is a separate configuration on the Knowledge Service itself — see AI Provider Setup.

MCP Server ¶

These variables control the MCP server — the tool interface through which external LLM clients (Claude Desktop, Claude Code, custom agents) can access Kamerplanter via a service-account API key.

mDNS / Zeroconf Discovery¶

When enabled, the backend announces a _kamerplanter._tcp.local. service on the local network. Home Assistant detects this service automatically and offers to set up the Kamerplanter integration.

mDNS and Kubernetes¶

mDNS relies on Multicast UDP (port 5353) within the local Layer 2 network. In standard Kubernetes clusters, mDNS does not work because:

1. Overlay network blocks multicast — Standard CNIs (Calico, Cilium, Flannel) only route L3 traffic. Multicast packets from a pod never reach the physical LAN — Home Assistant cannot see the announcements.
2. Pod IP is not LAN-reachable — Even if multicast worked, the announced pod IP (e.g. 10.42.x.x) would not be reachable from outside the cluster.

The Helm chart sets MDNS_ENABLED to false by default. The manual config flow in Home Assistant (URL input) works in every deployment scenario as a fallback.

Home Assistant Integration (REQ-005)¶

When both HA_URL/HA_ACCESS_TOKEN are set, the backend also enables the Home Assistant channel of the notification system (persistent notifications, mobile push, TTS).

Time-Series Data (TimescaleDB, REQ-005)¶

These variables enable the optional TimescaleDB connection for high-frequency sensor time-series with automatic downsampling (see Sensors). Without TIMESCALEDB_ENABLED=true, manual and automatic readings are still stored in ArangoDB — the app remains fully functional, just without automatic multi-stage downsampling.

Environment Control & Actuators (REQ-018)¶

This variable controls the periodic evaluation of schedules and rules, the hourly override-expiry sweep, and the 5-minute online/offline sync with Home Assistant for Environment Control & Actuators.

InvenTree Integration (REQ-016)¶

These variables enable the optional integration with InvenTree. Without INVENTREE_ENABLED=true, every InvenTree endpoint returns a "feature disabled" error (HTTP 409) without blocking the app.

You then set up the connection (including the API token) and links via the REST API — see Equipment & Inventory (InvenTree) — For Technical Users / Self-Hosters for details.

Weather Forecast & Frost Early-Warning ¶

These variables control the weather forecast fetching and the proactive frost early-warning built on top of it. Without WEATHER_ENABLED=true, both features stay fully disabled — sites without a configured weather source are likewise unaffected.

For comparison — the existing reactive frost threshold (current measured temperature, unchanged by this feature):

Climate Normals (NASA POWER) ¶

These variables control the monthly background fetch of long-term climate normals (the "Climate at the Site" section) via the keyless NASA POWER reanalysis interface. Both WEATHER_ENABLED and NASA_POWER_CLIMATE_ENABLED must be active for the fetch to run.

Hardiness Zones (USDA) ¶

This variable controls the quarterly background refresh of a site's hardiness zone, automatically derived from its climate normals (see Climate Zones & Hardiness). The derivation builds on the climate normals — the associated task therefore only runs when both WEATHER_ENABLED and NASA_POWER_CLIMATE_ENABLED are also active.

Irrigation Demand (ET₀) ¶

These variables control the daily background task that derives the FAO-56 reference evapotranspiration (ET₀) from an outdoor or greenhouse site's weather data and, from it, the net irrigation demand per planting run. The task additionally requires WEATHER_ENABLED=true — without fetched weather data there is nothing to compute. The resulting behaviour for end users is described in Watering Log: Suggested Watering Volume and Care Reminders: Why a Reminder Might Not Appear.

Rate Limiting¶

Format: [count]/[unit] — units: second, minute, hour, day

Uploads¶

Nested Configuration (GBIF)¶

GBIF settings can be passed using the double-underscore delimiter for nesting:

Photo Identification (REQ-029)¶

These variables configure optional plant recognition by photo. If none of the API keys are set, the feature is completely disabled — all camera buttons are hidden and no consent dialog is shown.

apiVersion: v1
kind: Secret
metadata:
  name: kamerplanter-identification
type: Opaque
stringData:
  PLANTNET_API_KEY: "your-api-key"

Feature Toggle Logic¶

PLANTNET_API_KEY set?
  ├── Yes  → Pl@ntNet active (species identification, ≤ 500 IDs/day)
  └── No   → Feature completely disabled
             (camera buttons hidden, no consent dialog)

Pest Detection (REQ-044)¶

These variables configure the optional image-based pest detection feature. The feature is disabled by default — without PEST_DETECTION_ENABLED=true, the "Check for Pests" button is hidden and the app is fully functional.

CV Disease Diagnosis (REQ-038)¶

These variables configure the optional, self-hosted photo diagnosis for diseases and nutrient deficiencies (distinct from Pest Detection above). The feature is disabled by default; without CV_DIAGNOSIS_ENABLED=true the /status API endpoint stays at available: false and the app keeps working without restriction.

The classifier runs in the existing inference service and reuses its already-configured connection (INFERENCE_SERVICE_URL, INTERNAL_SERVICE_TOKEN) — no additional connection variables are needed.

Browser Push / PWA (VAPID)¶

These variables enable the browser push notification channel (channel_key: "pwa"). When all three variables are empty, the channel is disabled — the application remains fully functional and users see "Not configured" in their notification settings.

*All three VAPID_* variables must be set for the browser push channel to become active. If any variable is missing, the channel remains disabled. PWA_PUSH_ENDPOINT_ALLOWED_HOSTS is independently optional.

Generating a Key Pair¶

npx web-push generate-vapid-keys

Output:

Public Key:
BNm...

Private Key:
8Kv...

Alternatively with pywebpush (Python) — the b64urlencode step is required because v.public_key/v.private_key are key objects and only serialization yields the Base64url strings:

pip install pywebpush
python3 - <<'PY'
from py_vapid import Vapid
from py_vapid.utils import b64urlencode
from cryptography.hazmat.primitives import serialization

v = Vapid()
v.generate_keys()
pub_raw = v.public_key.public_bytes(
    serialization.Encoding.X962,
    serialization.PublicFormat.UncompressedPoint,
)
priv_raw = v.private_key.private_numbers().private_value.to_bytes(32, "big")
pub, priv = b64urlencode(pub_raw), b64urlencode(priv_raw)
assert pub_raw[0] == 0x04 and len(pub_raw) == 65 and len(pub) == 87, "invalid public key"
assert len(priv_raw) == 32 and len(priv) == 43, "invalid private key"
print("VAPID_PUBLIC_KEY =", pub)
print("VAPID_PRIVATE_KEY=", priv)
PY

apiVersion: v1
kind: Secret
metadata:
  name: kamerplanter-vapid
type: Opaque
stringData:
  VAPID_PUBLIC_KEY: "BNm..."
  VAPID_PRIVATE_KEY: "8Kv..."
  VAPID_CONTACT_EMAIL: "mailto:admin@example.com"

Season & Overwintering Automation¶

These variables control the thresholds of the automatic season/overwintering detection (see Season Automation). They only affect the live and climatological tiers of the detection cascade — the calendar fallback is independent of them.

Error Tracking (optional)¶

Reports runtime failures to a Sentry-protocol-compatible tracker (reference: GlitchTip). With SENTRY_DSN empty nothing happens — the SDK is never initialised and the frontend does not even download its SDK bundle. Full detail: Error tracking.

All four apply to the backend, Celery worker and beat, the inference and knowledge services, and the frontend. In the frontend they are injected at runtime via runtime-config.js rather than baked into the build — one image serves every stage.

Complete .env Example¶

# Database
ARANGO_ROOT_PASSWORD=secure-root-password
ARANGODB_HOST=arangodb
ARANGODB_PORT=8529
ARANGODB_DATABASE=kamerplanter
ARANGODB_USERNAME=root
ARANGODB_PASSWORD=secure-root-password

# Cache / Queue
REDIS_URL=redis://valkey:6379/0

# Security (all three are mandatory secrets, startup gate in production)
JWT_SECRET_KEY=generate-with-openssl-rand-hex-32
FERNET_KEY=generate-with-Fernet.generate_key
ERASURE_TOMBSTONE_SALT=generate-with-openssl-rand-hex-32
REQUIRE_EMAIL_VERIFICATION=false

# CORS
CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]

# Operating mode
KAMERPLANTER_MODE=full
DEBUG=false

# Email (development)
EMAIL_ADAPTER=console

# mDNS Discovery (LAN only, opt-in)
# MDNS_ENABLED=false
# INSTANCE_ID=

# Optional external APIs
PERENUAL_API_KEY=
HA_URL=
HA_ACCESS_TOKEN=

# Knowledge Service — Re-Ranking (empty = disabled)
RERANKER_URL=
RERANKER_INITIAL_K=20
RERANKER_TOP_K=5

# AI Assistant (disabled instance-wide unless explicitly enabled)
AI_FEATURES_ENABLED=false
KNOWLEDGE_SERVICE_ENABLED=false
KNOWLEDGE_SERVICE_URL=http://knowledge-service:8000

# Photo identification (empty = feature disabled)
# PLANTNET_API_KEY=
# IDENTIFICATION_RATE_LIMIT_PER_USER_DAY=50

# Browser Push / PWA (empty = channel disabled)
# VAPID_PUBLIC_KEY=
# VAPID_PRIVATE_KEY=
# VAPID_CONTACT_EMAIL=mailto:admin@example.com

Object Storage (NFR-013)¶

These variables configure the storage adapter for binary data (photos, imports, exports). The active backend is determined by STORAGE_BACKEND. By default, local-fs is active — no additional configuration required.

For background information, see Configure Storage (Object Storage) and Helm Charts — Storage Configuration.

General Storage Settings¶

Default MIME whitelist per category:

Backend: Local Filesystem (local-fs)¶

*Required for local-fs token downloads to work. **Required in multi-replica operation.

kubectl create secret generic kamerplanter-storage-signing \
  --from-literal=STORAGE_LOCALFS_SIGNING_SECRET="$(openssl rand -hex 32)" \
  --namespace kamerplanter

Backend: S3-compatible (s3)¶

Example Configurations¶

STORAGE_BACKEND=s3
STORAGE_S3_ENDPOINT_URL=https://s3.eu-central-1.amazonaws.com
STORAGE_S3_REGION=eu-central-1
STORAGE_S3_BUCKET=my-kamerplanter-bucket
STORAGE_S3_ACCESS_KEY_ID=<from secret>
STORAGE_S3_SECRET_ACCESS_KEY=<from secret>
STORAGE_S3_USE_PATH_STYLE=false
STORAGE_S3_FORCE_TLS=true

STORAGE_BACKEND=s3
STORAGE_S3_ENDPOINT_URL=http://minio.kamerplanter.svc:9000
STORAGE_S3_REGION=us-east-1
STORAGE_S3_BUCKET=kamerplanter
STORAGE_S3_ACCESS_KEY_ID=<from secret>
STORAGE_S3_SECRET_ACCESS_KEY=<from secret>
STORAGE_S3_USE_PATH_STYLE=true
STORAGE_S3_FORCE_TLS=false
STORAGE_S3_ALLOW_PRIVATE_ENDPOINT=true

STORAGE_BACKEND=s3
STORAGE_S3_ENDPOINT_URL=https://fsn1.your-objectstorage.com
STORAGE_S3_REGION=eu-central
STORAGE_S3_BUCKET=my-kamerplanter-bucket
STORAGE_S3_ACCESS_KEY_ID=<from secret>
STORAGE_S3_SECRET_ACCESS_KEY=<from secret>
STORAGE_S3_USE_PATH_STYLE=false
STORAGE_S3_FORCE_TLS=true

Frequently Asked Questions¶

docker compose exec backend python -c "from app.config.settings import settings; print(settings.model_dump())"

See Also¶

• Configuration Matrix — Feature → services → switches → mandatory secrets → resources in a single table
• Deployment Profiles — Recommended component bundles for typical use cases
• Local Setup
• Operations Troubleshooting
• Kubernetes Deployment
• Weather Sources per Location — User Guide
• Notifications: Frost Early-Warning — User Guide
• API Reference: CV Disease Diagnosis
• MCP Server
• Privacy & GDPR — AI Disease Diagnosis
• Watering Log: Suggested Watering Volume — User Guide
• Equipment & Inventory (InvenTree) — User Guide
• Environment Control & Actuators — User Guide
• API Reference: Environment Control & Actuators