Deploy

mountOS runs as a set of services. Each one ships as a binary. The supported way to deploy the server fleet is the Terraform package. It covers AWS, GCP, and Azure.

This page describes the shape of a deployment and how to set one up. The Kubernetes surfaces below are for mounting volumes into pods, not for running the server fleet. For the full configuration and environment reference, see the machine-readable docs under /llms.txt.

Deployment methods

There is no server-fleet Helm chart and no published container image. A Kubernetes workload consumes mountOS through the CSI driver, against a fleet deployed by one of the first two methods.

The deployment shape

A deployment has three levels. Map them before provisioning anything.

• One global HUB (appserv). It has its own admin database, replicated for HA. It serves discovery and the admin APIs. It is shared across every region.
• One or more regions. Each region has its own database and its own vault. Its storages point at one or more S3-compatible or Azure stores. A region is a self-contained locality. A volume belongs to exactly one region. Only the HUB needs a DNS record. See Regional internals.
• One or more metadata clusters per region. A metadata cluster partitions volume load inside a region. It shares that region's database and vault. The in-region services, dataserv and gcserv, are cluster-scoped. blockserv's servers run alongside them, providing block storage independent of any single metadata cluster.

The shared admin database belongs to the HUB. It is the single source of truth. It tracks which regions and metadata clusters exist, where each service node runs, and which metadata cluster owns each volume. In-region services reach the HUB only for discovery, region and metadata cluster resolution, and quota replies. They otherwise talk to their own region's database.

Cloud deployment with Terraform

The mountos-io/deployment package is the single source of the deploy. Its release.yaml records the package version. Set MOS_VERSION explicitly in the answers rather than letting the fleet take whatever is latest that day; that is what keeps the package, the binaries, the admin SDK, and the helper scripts on one version. Do not mix versions. Each cloud is self-contained under clouds/<cloud>/terraform and selected with CLOUD=<cloud> make ..., which defaults to aws.

git clone https://github.com/mountos-io/deployment.git
cd deployment

make interview      # scaffolds answers.env
# fill answers.env and clouds/<cloud>/terraform/terraform.tfvars
make plan
make apply          # network, keys, database, the appserv fleet, DNS
make bootstrap      # generates keys, seeds the secret store
make verify

The order matters. make bootstrap runs after make apply, never before. Each instance then installs its own binary from mountos.sh/install and starts under systemd. A green make verify means a usable HUB.

The package converges forward. apply, bootstrap, and region-bootstrap are all safe to re-run. There is no destroy target, by design.

Verification differs by cloud. AWS has been deployed and verified end to end. GCP and Azure are validated at the configuration level and have not yet been applied against a real project or subscription. Plan a small non-production environment for a first run on either.

Set up a region or metadata cluster

A region or metadata cluster is a control-plane record. You create it through the HUB's admin API, not through a separate orchestration tool. The sequence is the same whether the deployment has one region or many.

1. Create the region through the admin API. This creates a single default metadata cluster automatically. Read back its metadata cluster identifier.
2. Optionally create additional metadata clusters in the region. Metadata cluster names are unique within a region. Exactly one metadata cluster is the default.
3. Put the metadata cluster identifier into the region's Terraform values, along with the dataserv count, the arena size, and the region database and vault choices. Then provision:

# after the region record exists on the HUB and you hold its metadata cluster id
make apply              # region database, secret-store wiring, the dataserv fleet
make region-bootstrap   # seeds region secrets, fans out service verifiers both ways

4. The in-region services boot with REGION_CLUSTER_ID set, plus that region's database URL and vault credentials. They self-register with the HUB.
5. The first cluster-scoped service that registers marks its metadata cluster ready. You can then create volumes against the region and metadata cluster through the admin API.

The two make apply calls are not a mistake. The metadata cluster identifier does not exist until the HUB is running and the region has been created, so the region fleet can only be configured after that.

Registration is strict. A service whose metadata cluster id is unknown, or whose metadata cluster is deactivated, refuses to register. This prevents it from joining the wrong metadata cluster. You can relocate a volume later with the move-cluster operation. See Metadata clusters.

How clients find their region

Clients do not need to know their region or metadata cluster in advance. Every client, mount or protocol surface, resolves its endpoint through the HUB's unauthenticated discovery endpoint:

GET /api/v1/discover/meta?access_key_id=<volume-access-key-id>

The access key encodes the volume identity. The HUB returns the dataserv endpoints for the volume's current metadata cluster. After a metadata cluster move, the next resolve request returns the new metadata cluster.

Discovery returns each node's client-facing address. A machine inside the deployment's own network generally cannot reach that address, because most clouds do not route an instance's public address back into the same virtual network. Test a mount from outside the deployment network.

Kubernetes with the CSI driver

The CSI driver (csi.mountos.io) exposes mountOS volumes as ReadWriteMany PersistentVolumes. It mounts them through FUSE. It runs as a DaemonSet and launches the mountos client to mount each volume. A PersistentVolume references the driver and points at a dataserv metadata endpoint. It carries the volume's access-key and secret-key pair through a node-stage secret. Optional volume attributes tune caching, buffer sizes, and extended-attribute behavior.

Single host with systemd

For a single-host Linux mount, install the mountos client. Then use one of two unit styles. A templated service runs the client mount on start and unmount on stop. It reads its environment from a per-mount file. A native .mount unit also works after you install the mount helper with mountos mount --install-mount-helper.

Prerequisites

• A cloud account on AWS, GCP, or Azure, with permission to create network, compute, database, key-store, and DNS resources; or machines you already run, for the binary path.
• Terraform, with a remote state backend of your own.
• A DNS record for the HUB domain. In-region services need none.
• A PostgreSQL database for the HUB, and one per region. Bringing a managed database you already operate is the recommended production path; the package can also provision one.
• An S3-compatible or Azure store reachable from each region (existing services such as AWS S3 or Cloudflare R2 work as is), a Region vault for each region, and a Hub vault for the HUB. The cloud-native secret store is the default. See Vault and handshake.
• For multi-region: keep the admin database with the HUB only. Give each region its own database and vault. Point each region's storages at S3-compatible or Azure stores in the same locality. Regions share the HUB's identity provider and admin DNS.

The machine-readable reference at /ai/llms-full.txt lists the exact environment variables and ports. The deploy skill carries the full runbook, including the failure modes that report healthy while the system is broken. For anything else, contact support.