Set up a region

A region is where data lives. It has its own database and its own vault, shared by all of its clusters, and writes data to the S3-compatible or Azure stores its storage records point at, one or many. A cluster is a volume-load partition. It owns a set of volumes and serves them.

Take the region and cluster IDs

The region was created during the HUB setup, and its default cluster, uno, was created with it. Use uno, or add a cluster when one partition is not enough.

// the region from the HUB setup already has its default cluster, "uno"
// add a cluster only to partition volume load further
const { id: clusterId } = await client.regionClusters.create(regionId, { name: 'dos' })

// the region from the HUB setup already has its default cluster, "uno"
// add a cluster only to partition volume load further
cluster, err := client.RegionClusters.Create(ctx, regionID, &sdk.CreateRegionClusterRequest{Name: "dos"})

// the region from the HUB setup already has its default cluster, "uno"
// add a cluster only to partition volume load further
let cluster = client.region_clusters.create(region_id, &CreateRegionClusterRequest {
    name: "dos".into(),
}).await?;

Every region and cluster record carries an exportId. The region's services take the cluster's value as REGION_CLUSTER_ID and resolve it against the HUB at startup. No separate REGION_ID is set.

Provision the region's infrastructure

Out of band, give the region its own database and a Region vault. Copy the verifier set from the Hub vault into the Region vault, since mountOS does not replicate vaults. One database and one vault serve the whole region. Adding a cluster adds neither.

Object storage is pointed at, not provisioned. A storage record holds an endpoint, credentials, and some configuration for any S3-compatible or Azure store, S3 and R2 included. Ideally it sits in the same locality as the region, and it need not be self-operated. For block devices as the backend, run a block storage.

Block storage

A block storage gives a volume's content a region-local home on raw block devices, with object storage as the durable source of truth behind it. It runs as up to three active-active block volumes. Each block volume is one blockserv node with its own attached volume, placed in a distinct cluster so one cluster failing does not take the storage offline. Block volumes replicate peer-to-peer with no primary, and clients reach them through appserv discovery, not DNS.

Each block volume runs with its own BLOCK_VOLUME_ID and REGION_CLUSTER_ID, caching object-storage parts on its block device. The public surface is the block protocol, not an S3 endpoint.

The Region vault

Each service reads its secrets from the Region vault under its own key, mountos/dataserv, mountos/gcserv, and so on. Seed each key with these values.

• DB_URL is the regional database connection.
• DB_DIALECT picks the schema, postgresql or mysql.
• DB_PROVIDER_VERSION is the engine version for capability detection, like 16 or 8.0.32.
• ED25519_SIGNING_KEY is the service's own private signing key.
• ED25519_VERIFICATION_KEY is its matching public key.

The database values matter to dataserv and gcserv, the two that touch the regional database. Every service carries its own key pair. The HUB checks a joining service against the verifier set, which is why that set is copied in from the Hub vault.

Every service machine needs a public IPv4, advertised as ADVERTISE_ADDR (an IP, not a hostname). No regional service needs DNS. dataserv, gcserv, and blockserv are all reached by address. Discovery hands clients the addresses, and gcserv stays hidden inside the region entirely, reached through the HUB.

Size the dataserv nodes

dataserv is the metadata backbone. Each cluster runs three or five instances forming a Raft group, an odd count for quorum. More instances only add quorum overhead. Every metadata operation from every mount flows through them, so give these machines large RAM and high network bandwidth.

Hot metadata is served from memory. METAENGINE_ARENA_SIZE sets the arena, 1GB at minimum, and about five million files fit per GiB. Size the arena to the metadata working set and the machine's RAM around the arena. Keep RAFT_PORT and RAFT_DATA_DIR stable across restarts.

Bring up the services

Each service follows the install pattern, and <service> env -w .env writes its template, every variable documented inline. The environment file carries these values.

• SERVICE_RPC_ADDR is the HUB address the service registers and heartbeats against.
• REGION_CLUSTER_ID is the cluster export ID above. It carries the region, so no separate REGION_ID is set.
• VAULT_PROVIDER names the secret store and carries its address and role credentials.
• ADVERTISE_ADDR is the public IPv4 the service advertises.
• MOUNTOS_LICENSE_PATH is the license path, a file or a directory of stacked license files.
• METAENGINE_ARENA_SIZE is the dataserv metadata arena from above.

The regional schema belongs to the database pair, dataserv and gcserv. Run db install once on the fresh regional database. It reads DB_URL and DB_DIALECT from the Region vault, downloads the schema for that dialect, and applies it, all in one step. The schema is cached locally, fetched once and reused.

./mountos-install --pkg mountos-dataserv
mountos-dataserv env -w .env     # the template documents every variable inline
export MOUNTOS_LICENSE_PATH=$PWD/license
set -a
. ./.env

mountos-dataserv db install      # create the regional schema, once per region
mountos-dataserv                 # start, register with the HUB, heartbeat

To upgrade an existing region later, run db migrate. It applies only the new migrations in range for the binary. The command is idempotent and safe to run from more than one instance at once.

mountos-dataserv db migrate   # apply pending schema changes, then restart

On boot a service registers itself with the HUB and heartbeats. The first registration into uno flips it to ready, and volumes can then be assigned. A service pointed at a cluster in another region, or at a deactivated cluster, refuses to register, raises a topology alert, and retries until the topology is fixed.

S3 and WebHDFS are protocol surfaces of the mountos client, bound to the one volume the client is authenticated for. There is no multi-tenant gateway fleet to deploy, so a region has nothing extra to provision for them.

Verify

The dashboard's region detail shows each cluster with its nodes, health, and the region audit log, and the nodes view shows every registered instance with memory, load, and heartbeat. See Region clusters and Regional internals for how the pieces serve a mount.