AgrarianGameArchive/Docs/Ops/MapTileDeliveryServerRunbook.md

Agrarian MVP Map Tile Delivery Server Runbook

The near-term tile server is intentionally simple: static files served by nginx from an Ubuntu VM. This proves the contract for tile manifest lookup, package download, checksums, local cache, and redownload before investing in a database or application service.

Build The Ground Zero Tile Package

On Ubuntu-Codex or any Linux machine with the repo mounted:

cd /mnt/projects/AgrarianGameBulid
Scripts/build_ground_zero_tile_delivery_package.sh

Output:

• BuildArtifacts/TileDelivery/public/manifest.json
• BuildArtifacts/TileDelivery/public/ground_zero_tiles.json
• BuildArtifacts/TileDelivery/public/tiles/gz_us_ca_pacifica_utm10n_e544_n4160/v0/
• BuildArtifacts/TileDelivery/public/SHA256SUMS
• BuildArtifacts/TileDelivery/agrarian-ground-zero-tile-delivery.tar.gz

BuildArtifacts/ is a local build output and should not be committed.

Bootstrap A New Ubuntu Tile Server

Copy the archive to a fresh Ubuntu VM, then run:

sudo AGRARIAN_TILE_SERVER_NAME=tiles.example.test \
  Operations/cloud-map-tile-server/bootstrap_ubuntu_tile_server.sh \
  /path/to/agrarian-ground-zero-tile-delivery.tar.gz

For an IP-only MVP test, omit AGRARIAN_TILE_SERVER_NAME.

The bootstrap installs nginx, creates:

/srv/agrarian/tile-delivery/public

and publishes:

• http://SERVER_IP/health
• http://SERVER_IP/manifest.json
• http://SERVER_IP/ground_zero_tiles.json
• http://SERVER_IP/tiles/gz_us_ca_pacifica_utm10n_e544_n4160/v0/...

Current MVP VM

The first Unraid-hosted MVP tile server is running inside its own dedicated Ubuntu VM. Unraid is only the hypervisor and VM storage host for this service; the tile service itself does not run on the Unraid OS.

Current endpoint:

http://192.168.5.14:18080

VM:

Agrarian-TileServer

The uncommon port is intentional for this local MVP proof. The server publishes from /srv/agrarian/tile-delivery/public:

• http://192.168.5.14:18080/health
• http://192.168.5.14:18080/manifest.json
• http://192.168.5.14:18080/ground_zero_tiles.json
• http://192.168.5.14:18080/tiles/gz_us_ca_pacifica_utm10n_e544_n4160/v0/...

The Ubuntu cloud image was downloaded from the workstation and copied to Unraid's ISO storage because direct download from Unraid was too slow. The VM was then created from that cloud image with cloud-init.

Verify Client Lookup And Cache

From a representative Linux client with the repo mounted:

cd /mnt/projects/AgrarianGameBulid
Scripts/verify_tile_delivery_client.sh http://192.168.5.14:18080

The verification script:

• downloads manifest.json;
• resolves the tile registry and package paths;
• downloads the Ground Zero terrain package files into a local cache;
• verifies SHA256SUMS;
• checks that immediate-neighbor metadata exists for the Ground Zero tile;
• deletes and redownloads the heightmap to prove cache recovery.

Cost Control

Keep the MVP server small:

• Ubuntu LTS, smallest useful VM size.
• Static nginx only.
• No database for the first proof.
• No public write endpoints.
• No Unreal server process on the tile VM unless explicitly testing combined hosting.
• Shut down or destroy the VM when not testing.

Security Baseline

• Allow inbound 18080/tcp for the local MVP endpoint. Use 80/tcp or 443/tcp only when a real DNS name and HTTPS path are assigned.
• Allow SSH only from trusted admin IPs.
• Add HTTPS with certbot when a real DNS name is assigned.
• Treat tile packages as immutable by version. Publish fixes as a new package version instead of editing files in place.

Next Proof

The current implementation proves static lookup/download/cache/redownload on the LAN. The next operational hardening step is deciding whether this VM stays LAN-only or is replaced by an external cloud host when we need public testing.