Skip to Content
DocsAdmin GuideConfiguration

Configuration

Quazzar Cloud OS is configured through an environment file at /etc/quazzar/quazzar.env.

Configuration File

Edit the configuration with:

sudo nano /etc/quazzar/quazzar.env

After making changes, restart the service:

sudo systemctl restart quazzar.service

JWT signing secret

The JWT signing secret is used for session cookies. The secret is persisted to disk at /var/lib/quazzar/jwt-secret (mode 0600) so sessions survive apt upgrade and manual restarts. The file is generated automatically on first boot if absent.

Override with an explicit value:

QUAZZAR_JWT_SECRET=<64-byte hex string>

When the env var is set, the file is ignored. This is useful in containerised deployments where you want the secret managed by your orchestrator.

Changing the secret invalidates every existing session — users are logged out and must sign in again. Back up /var/lib/quazzar/jwt-secret before any host migration.

Reverse Proxy

Cloud OS includes a built-in Caddy reverse proxy that provides automatic HTTPS and subdomain-based routing for installed apps. When configured with a base domain like cloud.example.com, an app named “nextcloud” becomes accessible at nextcloud.cloud.example.com.

DNS requirements for automatic HTTPS:

  1. A record for your base domain pointing to the server IP
  2. Wildcard A record (*.cloud.example.com) pointing to the same IP
  3. Ports 80 and 443 open

If you use an external reverse proxy (nginx, Traefik, Cloudflare Tunnel), disable the built-in proxy and route traffic to the Cloud OS port directly.

Caddy admin unix socket

The managed Caddy process now binds its admin endpoint to a unix socket at /var/run/quazzar-caddy-admin.sock instead of 127.0.0.1:2019. This avoids a port collision with the distro caddy.service that ships with some Debian / Ubuntu variants.

On every start, Quazzar best-effort stops the distro caddy.service to reclaim ports 80 and 443. If Quazzar is offline (or crashed) when you SSH in, you can restart it safely with:

sudo systemctl restart quazzar.service

When the managed Caddy’s admin socket is missing at reload time, the service falls back to a full Stop + Start instead of returning exit status 1. If you see reload failures on older installs, upgrade to 0.6.34 or later.

Troubleshooting: if both quazzar.service and caddy.service are enabled, caddy.service grabs port 80 first at boot. Quazzar then fails its Caddy start. Disable the distro service:

sudo systemctl disable --now caddy.service
sudo systemctl mask caddy.service

Semantic search (Ollama)

The Memory MCP server uses a local Ollama instance to compute embeddings for hybrid search. Configure with:

# Ollama host URL (default: http://127.0.0.1:11434)
OLLAMA_HOST=http://127.0.0.1:11434
 
# Embedding model (default: nomic-embed-text, 768 dims)
MCP_EMBED_MODEL=nomic-embed-text

Pull the default model once before first use:

ollama pull nomic-embed-text

If Ollama is unreachable at boot the service logs semantic search disabled (no embedding backend) and falls back to lexical-only ranking. Every Memory MCP tool keeps working; only the cosine term of the hybrid score is dropped.

Keep OLLAMA_HOST on loopback (127.0.0.1 or localhost) to prevent embedding queries leaving your node. Pointing it at a remote host sends your note content to that host on every memory_create / memory_update.

See Memory MCP for the full surface.

Control Panel agent (CC) TLS

For nodes connected to a Quazzar Cloud Control Panel, the CC agent can provision a domain certificate for the node automatically. Configure with:

# Absolute paths to the cert + key (PEM). Provisioned under /var/lib/quazzar/certs/
CC_AGENT_TLS_CERT=/var/lib/quazzar/certs/node.crt
CC_AGENT_TLS_KEY=/var/lib/quazzar/certs/node.key
 
# Comma-separated list of external domains the node terminates TLS for
CC_AGENT_EXTERNAL_DOMAINS=cloud.example.com,api.example.com

When CC_AGENT_EXTERNAL_DOMAINS is set, the CC agent requests certificates for every domain from the Control Panel and writes them to the configured paths. The managed Caddy reverse proxy then serves HTTPS from those certs without needing Let’s Encrypt on the node itself — useful for air-gapped nodes or domains that cannot satisfy HTTP-01 challenges.

The certs directory must be writable by the quazzar system user. On read-only filesystems (container rootfs, etc.) the agent logs the failure and continues without provisioning. Fixed in 0.6.34: the service no longer crashes on a read-only certs directory.

Service Management

Cloud OS runs as a systemd service. Common management commands:

# Check status
sudo systemctl status quazzar.service
 
# Start / stop / restart
sudo systemctl start quazzar.service
sudo systemctl stop quazzar.service
sudo systemctl restart quazzar.service
 
# View logs
sudo journalctl -u quazzar.service -f

Database Read Replica

For high-traffic deployments, the Control Panel supports routing read-only queries to a PostgreSQL read replica.

Configuration

Set the CC_DATABASE_READ_URL environment variable to your read replica connection string:

CC_DATABASE_READ_URL="postgres://user:pass@replica-host:5432/quazzar_cc?sslmode=require"

When configured:

  • Read operations (listing instances, viewing dashboards, fetching analytics) use the read replica
  • Write operations (creating resources, updating settings, issuing commands) use the primary database

If CC_DATABASE_READ_URL is not set, all queries go to the primary database configured via CC_DATABASE_URL.

Ensure your read replica is kept in sync with the primary database. The Control Panel does not manage replication — configure streaming replication or logical replication at the PostgreSQL level.

Tips

  • Keep backups of /etc/quazzar/quazzar.env before making changes.
  • Use journalctl to troubleshoot startup issues after configuration changes.
  • Restart the service after editing the environment file for changes to take effect.
DeploymentSecurity Hardening