⚙️ Configuration reference

Everything configurable lives in two places: config/site.env (your instance's values — hosts, URLs, keys, paths; gitignored) and config/*.yaml (the product's own declarations — jobs, events, schema; versioned). Validate your instance any time with nocloud config check.

config/site.env — your instance

Created by nocloud setup (or by hand from config/site.env.example). Read by every Python script via scripts/site_config.py and sourced by the shell scripts. The schema (config/schema.yaml) validates each key and marks which ones are secret, so nocloud config list masks them.

Key	What it is
SERVER_HOST / SERVER_USER	the server's LAN IP and SSH user
SERVER_SSH	optional SSH target override (default SERVER_USER@SERVER_HOST)
NOCLOUD_NGINX_CONFIG / NOCLOUD_NGINX_CONTAINER	override the nginx config path/container name auto-discovered during deploy — leave blank unless your instance uses different names
ACME_MODE / DNS_PROVIDER / CERT_EXTRA_DOMAINS	how HTTPS certificates are issued — see Network
WG_ENABLED / WG_PORT / WG_SUBNET / WG_ENDPOINT / WG_LAN	the WireGuard remote-access tunnel — see Network
IMMICH_URL / IMMICH_KEY	Immich API base (default http://SERVER_HOST:2283) and API key
IMMICH_PUBLIC_URL	optional public Immich URL used for click-through links
WEBMAIL_URL / WEBMAIL_PUBLIC_URL	webmail base (default http://SERVER_HOST:8888) and its public URL
DOMAIN / EMAIL	your domain and main email address
MAIL_DOMAIN / MAIL_FROM / MAIL_SIGNATURE	the product's outgoing mail (validation links, notices)
SITE_URL	public portal URL, used in links
MAC_API_URL	legacy name for the workstation editor/sending API as seen from the LAN (default port 8055)
MAC_DAEMON_URL / MAC_DAEMON_TOKEN	legacy names for the workstation runtime daemon as seen from the LAN (default port 8765) and its shared token — required for the "↻ Refresh" buttons
OLLAMA_URL / COACH_MODEL	Ollama chat endpoint for Rule Coach's NL→DSL step, as seen from the LAN (default http://localhost:11434/api/chat, qwen2.5:7b) — fully local, no cloud API
NOCLOUD_TRUST_PROXY_AUTH	trust the Remote-User header — only behind Authelia or equivalent forward-auth
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS_FILE	your local SMTP relay (Proton Bridge by default: 127.0.0.1:1025)
LOCAL_USER / MAC_HOME / NOCLOUD_HOME	the workstation user and paths (MAC_* names are retained for compatibility)
ARCHIVE_ROOT / IMMICH_BACKUP_DIR / MAIL_LOCAL_DIR	where the ordered archive, the Immich backup and the local mail live
BACKUP_DEST	the external disk backup_local.sh snapshots to and nocloud restore reads from; while unset, nocloud doctor's backup snapshot check fails with "no backup destination configured"
SERVER_HOME / SERVER_PORTAL	the server's home and the portal's web root

Warning

nocloud setup writes the network and path keys it can detect (including MAC_DAEMON_URL; it leaves MAC_DAEMON_TOKEN empty, only needed when the daemon listens beyond loopback). SERVER_SSH, IMMICH_PUBLIC_URL and NOCLOUD_TRUST_PROXY_AUTH are optional keys you add by hand (or with nocloud config set) when you need them. The certificate and WireGuard keys (ACME_MODE through WG_LAN) are asked by the install wizard and stay editable afterwards from Settings → Network — see Network — rather than hand-edited.

Rule Coach's local model needs a one-time pull

OLLAMA_URL/COACH_MODEL only point at where Ollama should be — nothing installs Ollama or downloads the model for you. On the machine OLLAMA_URL resolves to (the workstation, by default), one time:

brew install ollama && ollama serve &   # or: your platform's Ollama install
ollama pull qwen2.5:7b

nocloud doctor includes a low-severity "ollama model pulled (Rule Coach)" check so a missing or unpulled model shows up there instead of only failing the first time you actually try to coach a rule.

config/*.yaml — the product's declarations

These files ship with the product and are versioned; you rarely edit them, but they're where the platform's behavior is declared rather than hardcoded.

File	What it declares
schema.yaml	every valid site.env key: type, required, secret, group — what nocloud config check validates against
jobs.yaml	the job registry: every scheduled task with its schedule, host, timeout and output
events.yaml	the audit event vocabulary (kinds, severities)
triggers.yaml	event → job automations (on: <kind> plus optional field filters)
runtime.yaml	runtime knobs: state directory, daemon port, required services
upgrade.yaml	the upgrade lifecycle's phases, in order
backup_manifest.yaml	the backup contract: which items must exist in a backup for it to count
integrations.yaml	the third-party adapters (Immich, Home Assistant, docker, systemd…) and whether each is required
datasets.yaml	the dataset definitions (table, columns, conflict key) connectors write through

Default ports

Port	Service	Where
8765	nocloud daemon (runtime API)	workstation, loopback by default
8055	MAC_API_URL (editor/sending API)	workstation
1025	SMTP relay (Proton Bridge)	workstation, loopback
2283	Immich	home server
8888	Webmail	home server
8123	Home Assistant	home server
9092 / 9093 / 9095	permissions API / settings API / ingest service	home server, loopback behind nginx
80 / 443	nginx portal	home server
51820/udp	WireGuard VPN	home server, public when remote access is enabled
22	SSH (key-only)	home server, LAN/VPN

The security panel flags anything else listening publicly — see Security & privacy.