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

5. Make names, certificates and permissions agree

A connection succeeds only when three facts agree: the client resolves the name to the intended server, the server presents a certificate for that name, and the client trusts its issuer. An IP address that responds to ping proves none of the last two facts. Keep this sequence in mind when troubleshooting every service.

Step 1: distinguish native and Azure names

Native clients use names such as quinzee.cloud, <account>.blob.storage.quinzee.cloud, <namespace>.servicebus.quinzee.cloud and <app>.appservice.quinzee.cloud. Azure-name emulation adds supported Microsoft hostnames on a separate listener. It is for isolated clients that explicitly use Quinzee's DNS and development trust; it does not contact Azure. Do not redirect a workstation's general DNS to the emulator.

The standard network gives the cloud address <prefix>.10 and CoreDNS <prefix>.53. Joining the Docker network alone does not select its DNS. Pass --dns <prefix>.53 to a separate client container and mount only public trust material. Native database names point to the engine container's own address, not to the cloud HTTPS gateway.

Step 2: inspect and change DNS

Open Emulator → DNS → Records. Check generated records for the loaded services. Use Add record for a deliberate custom record, and use the DNS server tab to inspect the generated server configuration and Azure emulation state. Changes publish the zone/Corefile read by the separate CoreDNS process. If records look right in QHQ but clients cannot resolve them, check CoreDNS's process, network, DNS selection and cache before changing the record again.

A custom record accepts a lowercase DNS name, optional IPv4 address (defaulting to the advertised emulator address), and optional descriptive detail. Generated service names are reserved and cannot be overwritten. Deleting a custom record removes only that override. The generated zone has a fixed five-second TTL and a serial that increases on updates. AAAA and wildcard records are unsupported; changing a record does not change a certificate.

DNS controls

The DNS module supports its documented local record workflow; it is not the Azure DNS zone ARM provider. Do not put a Microsoft.Network/dnsZones resource in a template and expect this module to configure CoreDNS.

Step 3: issue and distribute certificates

make certs creates the development root and service certificates under .local/certificates. Existing material is reused. To deliberately replace it, use make certs FORCE=1 only after planning how every affected client will trust the replacement roots. Keep CA signing keys on the operator host; containers receive service leaf keys or public roots according to their role.

Native cloud defaults look for server.crt, server.key and ca.crt in /etc/quinzee/tls. The standard Compose mounts supply those paths. Azure-name certificates use a separate name-constrained root and mount. Functions and App Service helpers also have separate name-constrained runtime CAs for upstream verification. An app presenting a valid certificate for another domain must still be rejected.

After renewal, restart the affected listeners and distribute the new public CA bundle to clients. Verify HTTPS without disabling certificate checks. Native engine clients may need the engine CA and its revocation responder reachable; copying the cloud's HTTPS root alone is insufficient for their certificates.

Step 4: separate the identities involved

The OS service user owns files and processes. The bootstrap application identity administers Quinzee. A directory user signs in as a person. A service principal is an application's tenant identity. A managed identity is a service principal whose token credential is supplied by a hosted environment. A SQL administrator is an engine-local database login. None of these names makes the others the same account, and password reset at one boundary does not reset all of them.

Bootstrap credentials grant broad local control. New principals/users need supported ARM or Service Bus role assignments. Other data planes retain their explicit compatibility boundaries. A role named Owner is not a directory administrator, and an app role called Orders.Read is not an Azure resource role. Never infer an authorization guarantee solely from an Azure-shaped property.

Step 5: protect the installation at rest

Private state, credentials, signing material and runtime mailboxes use restricted permissions. The emulator does not provide blanket encryption at rest for all application data. Use OS ownership, encrypted storage where required, private backups and a restricted management network. Do not expose the bootstrap credential file through a web server or mount it into ordinary application containers. Keep the Docker socket with the explicitly operated helpers.