quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Administrator’s guide

4. Configure the cloud and its launch environment

Configuration has three layers. The native executable reads an optional JSON file and command-line arguments. Compose/Make launchers substitute their own variables and mounts. Individual resources are configured through their service APIs. Changing a shell variable does not update a running resource, and adding an Azure resource property does not change the server's listening port.

Step 1: choose one source of startup configuration

--config FILE reads a JSON object of at most 64 KiB. All members are optional. Command-line options override the file. Unknown names and invalid types fail startup instead of being ignored. The native executable does not directly read Compose environment variables. Relative paths are relative to its working directory; use absolute paths in a persistent service definition.

Save a private configuration such as:

{
  "address": "127.0.0.1",
  "port": 11443,
  "tlsCertificate": "/srv/quinzee/tls/server.crt",
  "tlsKey": "/srv/quinzee/tls/server.key",
  "caCertificate": "/srv/quinzee/tls/ca.crt",
  "dataDirectory": "/srv/quinzee/data",
  "advertiseAddress": "127.0.0.1",
  "logLevel": "info",
  "azureEmulation": false
}

Create the directories for the service's non-root OS user, install matching certificates, and run bin/debug/quinzee.cloud --config /srv/quinzee/cloud.json. Use bin/release/quinzee.cloud after make PRESET=release for a release build. There is no plaintext HTTP mode for the cloud executable.

Complete cloud startup settings

JSON member CLI option Default and meaning
address --address Numeric IP 127.0.0.1; listener binding
port --port HTTPS 11443; explicit ports 1–65535
serviceBusPort --service-bus-port Omitted disables AMQP; explicit 1–65535 enables TLS AMQP
tlsCertificate --tls-cert /etc/quinzee/tls/server.crt; PEM chain
tlsKey --tls-key /etc/quinzee/tls/server.key; matching private key
caCertificate --ca-cert /etc/quinzee/tls/ca.crt; development root metadata and outbound trust where used
dataDirectory --data-dir /var/lib/quinzee; durable instance state
modules --modules All catalogue modules by default; JSON array or comma-separated CLI IDs
advertiseAddress --advertise-address IPv4 127.0.0.1; generated service DNS targets, not listener binding
storageDomain --storage-domain storage.quinzee.cloud; Blob/Queue/Table suffix
vaultDomain --vault-domain vault.quinzee.cloud
appConfigurationDomain --app-configuration-domain appconfig.quinzee.cloud
azureEmulation --azure-emulation false / off; CLI accepts on or off
emulationPort --emulation-port 443; separate Azure-name HTTPS listener
emulationTlsCertificate --emulation-tls-cert /etc/quinzee/azure-emulation/server.crt
emulationTlsKey --emulation-tls-key /etc/quinzee/azure-emulation/server.key
directoryPostgresConfig --directory-postgres-config Absent: legacy private JSON directory; present: private libpq settings file
ldapSocket --ldap-socket Absent: no LDAP backend socket; requires PostgreSQL when present
otlpEndpoint --otlp-endpoint Empty: external telemetry export disabled; HTTPS origin
otlpCaCertificate --otlp-ca Optional CA for telemetry export
logLevel --log-level info; debug, info, warning or error

--config and --help are CLI-only. Explicit TLS certificate/key overrides must be supplied as a pair. Service domains must be lowercase DNS names with at least two labels and must also be present in certificates and client DNS. TLS files are loaded at startup: replacing a file alone does not reload it. The Azure emulation listener is provisioned at startup; its DNS/route switch can then be changed in QHQ. Enabling a switch cannot create a missing TLS listener.

Compose and Make values

These values configure the standard launchers, not arbitrary Azure resources:

Name Default / effect
PRESET debug; native build/test preset, also release/asan/tsan
DOCKER_PRESET / TRIGLAV_DOCKER_PRESET release; image build preset passed by launcher/Compose
JOBS Host CPU count; keep parallel builds enabled
TRIGLAV_HOST_BIND 127.0.0.1; published host address
QUINZEE_HTTPS_PORT 11443 on host; container remains 11443
QUINZEE_AMQP_PORT 5671 on host; container remains 5671
QUINZEE_DNS_PORT 10053 on host; container DNS is 53 TCP/UDP
QUINZEE_NET_PREFIX 172.29.53; /24 network, cloud .10 and DNS .53
QUINZEE_DATA_DIR .local/quinzee; mounted instance data
QUINZEE_TLS_DIR .local/certificates/quinzee.cloud; service TLS mount
QUINZEE_EMULATION_TLS_DIR .local/certificates/azure-emulation; Azure-name TLS mount
QUINZEE_UID, QUINZEE_GID Compose defaults 65534; development launcher supplies the operator IDs
ENGINE_DATA_DIR Absolute .local/quinzee; cloud state observed by helpers
ENGINE_NETWORK triglav-http_quinzee; existing Docker network
FUNCTIONS_STATE_DIR Absolute .local/functions-helper; private hosting-helper state
FUNCTIONS_REGISTRY images.json in that helper state directory
QHQ_WIDTH, QHQ_HEIGHT Viewer dimensions; launcher defaults 1440 × 900
QHQ_RASTA_PORT Viewer UDP port; launcher default 5100
QHQ_PRESET QHQ launcher's selected binary preset
QUINZEE_CERT_DIR Development launcher's certificate root, normally .local/certificates
QUINZEE_OTLP_ENDPOINT, QUINZEE_OTLP_CA Optional engine-helper telemetry destination and trust

Use docker compose config to inspect resolved mounts, addresses and commands before startup. It can show interpolated private values in other projects; keep its output local. The default Compose file supplies startup arguments explicitly; to add a JSON config, mount it and override the service command in a separate Compose override file. Passing a host path that is not mounted into the container cannot work. Prefer a new private instance directory for a new environment.

Change one setting and verify the result

  1. Record the old value, origin, paths and active resources.
  2. Stop incoming writes and follow the relevant workload shutdown procedure.
  3. Edit the JSON or launcher configuration, preserving private permissions.
  4. Restart, check /health, QHQ Connection and the affected service endpoint.
  5. If startup fails, restore the prior configuration; do not modify state files to make incompatible settings appear acceptable.

Fixed resource limits, SQL engine versions and supported API properties appear in later chapters. They are not hidden environment variables you can tune.