Deployment Options

Genesis Mesh supports four deployment shapes. Pick the one that matches your operational target.

        flowchart TB
    secrets["Mounted secrets<br/>genesis.signed.json + na.key"]
    operator["OPERATOR_PUBLIC_KEYS_JSON"]
    container["Genesis Mesh container"]
    gunicorn["Gunicorn"]
    flask["Network Authority app"]
    sqlite["SQLite DB on durable volume"]
    ingress["Ingress / TLS termination"]

    ingress --> gunicorn
    gunicorn --> flask
    flask --> sqlite
    secrets -->|GENESIS_FILE, NA_PRIVATE_KEY_FILE| container
    operator --> container
    container --> gunicorn

Live Deployment

A public Network Authority runs on Azure (Sweden Central):

https://na.genesismesh.connectorzzz.com

Architecture

  • Azure VM (Terraform provisioned, Standard_B2ts_v2, Sweden Central)

  • Nginx with TLS termination (Let’s Encrypt)

  • Gunicorn (4 workers, sync worker class)

  • Genesis Mesh Network Authority (systemd-managed genesis-mesh-na.service)

  • SQLite persistence on a durable disk

  • Public endpoint: https://na.genesismesh.connectorzzz.com

Two enrolled nodes from separate IP addresses with active heartbeats.

Network Authority operator console

/nodes endpoint showing two enrolled nodes with different remote addresses

1. Local Process

The fastest way to run a Network Authority. Suitable for development, demos, and CI smoke tests.

genesis-mesh init
genesis-mesh na start

genesis-mesh na start uses the Flask development server. For production container or VM startup, use Gunicorn through start.sh.

See: In-process smoke demo and Live CLI process smoke demo

2. Docker

The container entry point is start.sh. In Network Authority mode it runs Gunicorn and requires mounted genesis and NA key files.

docker run --rm \
  -e SERVICE_ROLE=na \
  -e GENESIS_FILE=/run/secrets/genesis.signed.json \
  -e NA_PRIVATE_KEY_FILE=/run/secrets/na.key \
  -e OPERATOR_PUBLIC_KEYS_JSON='{"operator-local":"<base64-public-key>"}' \
  -e DB_PATH=/data/genesis_mesh_na.db \
  -p 8443:8443 \
  genesis-mesh:local

For multi-container orchestration with a writable database volume, use the included Docker Compose example.

See: Docker image smoke demo and Docker Compose example

3. Kubernetes

A minimal set of manifests is provided under examples/kubernetes/:

kubectl apply -f examples/kubernetes/namespace.yaml
kubectl apply -f examples/kubernetes/na-secrets.yaml
kubectl apply -f examples/kubernetes/na-pvc.yaml
kubectl apply -f examples/kubernetes/na-deployment.yaml
kubectl apply -f examples/kubernetes/na-service.yaml

The Deployment runs a single non-root replica, mounts the genesis block and NA key as a Secret, and persists the SQLite database to a PersistentVolumeClaim.

See: Kubernetes deployment guide and examples/kubernetes/README.md

4. Terraform on Azure

The infrastructure/azure/ directory contains a self-contained Terraform module that provisions a complete Network Authority environment on Azure: resource group, virtual network, subnet, public IP, NSG, network interface, and an Ubuntu 22.04 VM.

cd infrastructure/azure
terraform init \
  -backend-config="resource_group_name=terraform-state-rg" \
  -backend-config="storage_account_name=tfstategenesismesh" \
  -backend-config="container_name=tfstate" \
  -backend-config="key=genesis-mesh-na.tfstate"
terraform apply

The same module is driven from CI via .github/workflows/deploy-azure.yml, which is how the live deployment at https://na.genesismesh.connectorzzz.com was provisioned.

See: Terraform deployment guide

Release CD to the Azure VM

Terraform provisions the VM. Code updates for an existing VM are handled by .github/workflows/deploy-release-azure-vm.yml.

The release deployment workflow runs when a GitHub release is published. It can also be triggered manually from the Actions tab. The workflow connects to the VM over SSH, backs up /var/lib/genesis-mesh/na.db, checks out the release tag, updates the virtual environment, installs the current package, refreshes the systemd unit files, restarts the NA and router services, then probes:

  • GET /healthz

  • GET /readyz

  • GET /connectome.json

Required GitHub secrets:

Secret

Value

NA_VM_HOST

Public hostname or IP address of the live VM

NA_VM_SSH_PRIVATE_KEY

Private SSH key allowed to log in to the VM

Optional GitHub variables:

Variable

Default

Description

NA_VM_USER

azureuser

SSH username

NA_VM_SSH_PORT

22

SSH port

These can be loaded from .env with:

bash infrastructure/scripts/setup-github-secrets.sh

Set NA_VM_SSH_PRIVATE_KEY_FILE in .env to read the private key from disk, or set NA_VM_SSH_PRIVATE_KEY directly if your local shell can safely handle multi-line values. The script never prints the private key.

The workflow deploys the release tag on release.published. For manual runs, pass a tag such as v0.12.0 or a branch such as main.

This workflow is intentionally Azure-specific because the next proof levels may use a second VM on another cloud or a physical host. Add separate release-CD workflows for those targets instead of hiding multiple deployment environments behind one generic VM workflow.

Production Readiness Checks

Before promoting any of the deployment shapes above to production:

  • the container starts as a non-root user

  • required secret files are mounted

  • startup fails closed when required secret files are missing

  • /healthz and /readyz work behind the selected ingress

  • SQLite data is persisted on durable storage

  • backups are tested

  • operator public keys are reviewed and rotated through policy

  • logs do not expose private key material

Do not run two Network Authority processes against the same SQLite database file. Genesis Mesh treats SQLite as a single-writer deployment store.