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.

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.

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.

See Memory MCP for the full surface.

Memory search mode

The Memory MCP search engine supports three operating modes, controlled by:

# Values: legacy | shadow | hybrid_v2  (default: shadow)
MEMORY_SEARCH_MODE=shadow

Recommended rollout:

1. Run in shadow mode (the default) for a period that covers your typical query variety.
2. Query search_comparisons to review divergence between the two rankers:

   SELECT query, overlap_count, legacy_top_ids, v2_top_ids, created_at
   FROM search_comparisons
   ORDER BY overlap_count ASC   -- lowest overlap = biggest change
   LIMIT 20;

3. If divergence looks good (higher-quality results), flip to hybrid_v2:

   MEMORY_SEARCH_MODE=hybrid_v2
   sudo systemctl restart quazzar.service

The search_comparisons table is truncated automatically when it exceeds 10 000 rows (oldest first) to prevent unbounded growth.

Predictive Insights alerts

The Predictive Insights subsystem scores four predictors (resource anomaly, capacity forecast, backup health, app health) on an hourly cycle. Detection and on-demand serving (MCP tool, REST endpoint, dashboard card) are on by default.

Proactive push notifications — Molly alerting you without being asked, when a predictor scores high risk — are off by default and must be opted in:

# Enable proactive Molly alerts for high-risk predictions (default: false)
QUAZZAR_INSIGHTS_ALERTS=true

When enabled, the alert system respects a per-predictor dedup window: a high-risk disk-capacity alert fires at most once per hour. If the risk level is unchanged in the next scoring cycle, no duplicate notification is sent.

To limit alerts to specific predictors, you may set:

# Comma-separated list of predictors to alert on (default: all four)
QUAZZAR_INSIGHTS_ALERT_PREDICTORS=capacity_forecast,backup_health

See Predictive Insights for a full description of the predictors and their honest-refusal behaviour.

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.

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.

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.