# 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:

```bash
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:

```bash
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:

```text
/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:

```text
http://192.168.5.14:18080
```

VM:

```text
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:

```bash
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.
