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 on the existing Ubuntu-Codex VM while we keep costs at zero and avoid creating a new paid cloud host too early.

Current endpoint:

http://192.168.5.10:18080

The uncommon port is intentional for this local MVP proof. The server publishes:

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

The attempted dedicated Agrarian-TileServer VM bootstrap was deferred because the Ubuntu cloud image download from Unraid was too slow to be practical during this pass. A dedicated VM remains the next hardening step before exposing the tile server outside the LAN.

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.10: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 to move this from shared Ubuntu-Codex hosting to a dedicated Agrarian-TileServer VM or external cloud host when we need public testing.