Deployment

Canonical production URL: https://asi-database-node-api.arybit.co.ke

First staging installation

Install Python 3.12+, Bash, Git, Azure CLI, SSH/SCP and the required HTTPS tools. Authenticate to the intended Azure tenant/subscription. Pin the VM SSH host key through a trusted channel. Provide a restricted administrator CIDR, VM/image settings and TLS contact in private configuration. Point each selected domain and alias at the VM before certificate issuance.

bash init-deploy-database-api.sh
bash run.sh --13 --staging --plan
bash run.sh --13 --staging --preflight

Review deployment.targets.json and protected runtime settings before cloud changes. The default environment is production; always specify --staging for staging work.

Production hostname

Set production:13 domain to asi-database-node-api.arybit.co.ke and review its www alias. VM version 13 does not require a versioned public hostname. Changing an example does not modify a running VM or DNS. Existing private target files must be reviewed separately. The target domain drives allowed hosts, CORS, Nginx server names and certificate paths. Keep ui/config.json apiBase empty to follow the served HTTPS origin.

Deploy and verify

bash run.sh --13 --plan
bash run.sh --13 --preflight
bash run.sh --13 --core
bash run.sh --13 --verify
bash run.sh --13 --logs --stream

Automatic deploy/core may authenticate to Azure, publish source to main and wait for exact-commit CI. Use --no-auto for manual preparation. These are operator commands, not steps performed by documentation generation. Deployment does not apply product SQL migrations.

Phase responsibilities

The coordinator selects the execution graph; phase scripts delegate to remote.py. Review bash run.sh --help for supported combinations. Candidate readiness and public HTTPS verification precede acceptance. Generated HTML ships with ui/ and is served at /admin/doc/ through the existing Nginx alias.

Rollback, backup and cleanup

Use the maintained rollback-release.sh entry point after reviewing its help and target. Rollback changes releases; it does not undo schema migrations. Encrypted backup requires an age recipient and a separate backup_env_file. Restore into an isolated destination with ops/restore-backup.py, then verify data and permissions before recovery. See operations.

Cleanup is a separate operation. In both production and staging, --clean authorizes deletion of the entire dedicated resource group, disks and data without additional confirmation flags. Review the coordinator's cleanup plan and retain off-host backups before authorizing deletion.

Local edits and publication

Automatic publication and deployment use the same source cleanliness policy. Unstaged changes to the root deployment.targets.json and asi-database-node-api.sh are local operator settings and do not block source publication or release transfer. Neither file is shipped in the application archive. Staging either file is rejected; all other uncommitted or untracked source still blocks the final deployment gate. The launcher is not automatically edited or committed.

Production cleanup no longer requires --confirm-clean or --allow-production-destruction; these flags remain accepted for compatibility. Use bash run.sh --13 --clean --plan to preview or bash run.sh --13 --clean to delete the selected production group. Ownership and cross-resource attachment checks still apply. A routine deployment can reuse the existing VM with bash run.sh --13; cleanup is not required. To retry application deployment on an already prepared VM, use bash run.sh --13 --core. Review the selected target first.

HTTP certificate challenge failures

If Certbot reports a connection error fetching /.well-known/acme-challenge/, the candidate may already be running while public HTTPS acceptance remains incomplete. Deployment and --core retries reconcile the owned VM NSG rules for TCP 80 and 443, while SSH remains restricted to admin_cidr. Existing subnet-level rules, higher-priority denies and host firewall rules can still prevent public access and require review.

During issuance, missing hostnames receive a temporary HTTP challenge-only server. The active application proxy remains intact. A loopback HTTP probe checks each hostname's challenge content before Certbot runs; this does not prove public access. Temporary routes and probe files are removed on success or failure.

After reviewing the target, retry with bash run.sh --13 --core. No cleanup is required. If local challenge checks pass but issuance still fails, verify public TCP 80 reachability, effective NIC/subnet NSG rules, host firewall rules and A/AAAA records before retrying. Do not disable certificate validation.