English | 简体中文
Documentation snapshot:
2026-08-31· Product identity:TerraSys
TerraSys is a local-first personal geographic information system for owning, exploring, and recovering offline map data. It combines an OpenStreetMap-style local renderer, portable regional vector maps, private places and tracks, address search, routing, terrain, weather, nautical references, a Chinese encyclopedia and travel guide, resource lifecycle management, backups, and disconnected recovery.
The project is designed for one trusted user on a trusted local computer or LAN. Its only host-facing endpoint is:
http://localhost:8080/
When the web service is started on a trusted LAN, scripts/start-web.ps1 also prints the reachable LAN URL. Internal databases and engines remain behind nginx and are not published directly.
The resource and map-version console is available at:
http://localhost:8080/resources.html
- Data ownership: source snapshots, regional packages, personal records, indexes, build tools, and recovery materials remain locally inspectable and portable.
- Offline first: installed maps, the world overview, personal data, search, routing, terrain, and local knowledge continue to work without the internet.
- Truthful state: downloads, builds, verification, updates, rollback, and failures are reported from real jobs and manifests rather than placeholders or guessed progress.
- Replaceable layers: rendering, storage, geocoding, routing, knowledge, and the browser UI have explicit boundaries.
- Recoverability: personal backups and complete offline kits use SHA256 manifests and can be tested on an isolated Docker network.
| Capability | Implementation |
|---|---|
| Familiar local map | OpenStreetMap Carto rendered locally with osm2pgsql, PostGIS, Mapnik, and mod_tile |
| Interactive regional map | Independently versioned PMTiles packages rendered by MapLibre GL JS |
| World overview | Local Natural Earth 110m/50m/10m vector PMTiles with land, water, boundaries, cities, major roads, rail, and rivers at zoom 0-7 |
| Personal data | PostGIS places, collections, tracks, notes, tags, ratings, and content-addressed media |
| Search | Lightweight local OSM reference index plus Nominatim address search and reverse geocoding |
| Routing | Valhalla driving, cycling, and walking routes with elevation profiles |
| Terrain | Local HGT elevation, Terrarium tiles, hillshade, and browser-generated contours |
| Context layers | Weather snapshots, nautical references, and emergency facilities |
| Local knowledge | Kiwix-hosted Chinese Wikipedia and Wikivoyage archives |
| Resource lifecycle | Global catalog, install/update/rebuild/verify/disable/rollback/remove jobs, and storage accounting |
| Recovery | Versioned database migrations, daily backups, portable exports, and disconnected recovery kits |
Jiangsu, Anhui, and Shandong are the current local map and shared-index scope. Regional derivative resources are derived from every installed and enabled package rather than a hard-coded province list. The catalog contains all 34 Chinese province-level units and more than 550 Geofabrik country or regional packages; only verified local products count as installed.
flowchart LR
Browser["Browser / MapLibre"] --> Nginx["nginx :8080"]
Nginx --> Web["UI, fonts, sprites"]
Nginx --> Carto["OSM Carto raster"]
Nginx --> PMTiles["Regional PMTiles"]
Nginx --> API["FastAPI"]
Nginx --> Martin["Martin vector tiles"]
Nginx --> Kiwix["Kiwix knowledge"]
API --> PostGIS["Personal PostGIS"]
API --> Nominatim["Nominatim"]
API --> Valhalla["Valhalla"]
API --> LocalData["Terrain, weather, nautical, media"]
The active Compose profile contains eight services: web, api, postgis, martin, nominatim, valhalla, kiwix, and osm-carto. Only nginx publishes host port 8080; internal databases and engines are not published directly.
Windows:
D:\TerraSys\start-terrasys.cmd
D:\TerraSys\health-check.cmd
D:\TerraSys\smoke-test.cmdLinux:
./terrasys.sh start
./terrasys.sh health
./terrasys.sh smokeFor a fresh host, start with the deployment guide, then follow either the Windows workstation or Linux server procedure. The two methods share data formats and lifecycle scripts but use platform-specific startup and backup scheduling.
Ongoing development uses the layered test suite: static for every commit, browser for map and resource UI coverage, full for API and personal-data lifecycles, and recovery for the isolated disconnected recovery drill.
The start command creates local secrets when required, ensures Docker is available, applies ordered PostGIS migrations, builds the API image, starts the core stack, enables prepared advanced services, and starts the allowlisted maintenance worker.
Prepare or rebuild advanced offline capabilities:
D:\TerraSys\prepare-advanced.cmdBuild or resume the OSM Carto renderer independently:
powershell -NoProfile -ExecutionPolicy Bypass -File D:\TerraSys\scripts\build-osm-carto.ps1Heavy builds are intentionally serialized on a 16 GiB host. Existing validated products remain active until their staged replacements pass verification.
D:\TerraSys\backup-terrasys.cmd
D:\TerraSys\region-pack.cmd List
D:\TerraSys\region-pack.cmd Verify
D:\TerraSys\rebuild-shared-indexes.cmd -Plan
D:\TerraSys\create-offline-kit.cmd
D:\TerraSys\test-offline-recovery.cmd
D:\TerraSys\stop-terrasys.cmdThe resource console exposes Available, Local, and Updates views. Regular update-all jobs exclude heavy map, knowledge, and shared-index builds. Each active task owns its queue position, stage, measured transfer or generation rate, cancellation action, and retry state.
The complete tracked/generated/private-data boundary is documented in Project structure.
| Path | Role |
|---|---|
web/ |
Browser application, local assets, and resource console |
services/ |
Compose topology, API, nginx, Martin, tools, and PostGIS migrations |
config/ |
OSM Carto and Planetiler build configuration |
raw/osm/ |
Downloaded OSM snapshots, boundaries, state, and provenance |
products/tiles/pmtiles/ |
Verified regional vector-map products and manifests |
products/routing/ |
Valhalla graph versions |
products/elevation/ |
Retained global HGT elevation grids synchronized for installed regions |
products/encyclopedia/ |
Verified Kiwix ZIM archives |
data/ |
Personal media, exports, terrain cache, and maintenance state |
backups/ |
Personal PostGIS and media recovery points |
offline-kit/ |
Complete disconnected recovery packages |
runtime/ and tmp/ |
Audits, logs, candidate builds, and renewable scratch data |
The canonical project path is D:\TerraSys; C:\Users\Administrator\Documents\TerraSys is a junction to the same files. Docker Desktop data is stored at D:\DockerData\wsl. Product text, scripts, containers, images, environment variables, browser keys, recovery payloads, and new database names use the TerraSys identity. Upgrade code migrates prior browser settings and can attach the existing verified Docker index volumes without copying them.
The documentation index provides every guide in English and Simplified Chinese.
| Subject | English | 简体中文 |
|---|---|---|
| Deployment | English | 中文 |
| Project structure | English | 中文 |
| Architecture | English | 中文 |
| Configuration | English | 中文 |
| Data pipeline | English | 中文 |
| Operations | English | 中文 |
| MCP adapter | English | 中文 |
| Rebuild | English | 中文 |
| Offline recovery | English | 中文 |
| Resource lifecycle | English | 中文 |
| Sources and licenses | English | 中文 |
| Roadmap | English | 中文 |
| Version history | English | 中文 |
The repository had no Git tags or GitHub Releases before this documentation snapshot. CHANGELOG.md reconstructs seven development milestones from non-merge commits and records the authoritative commit hash and ISO 8601 timestamp for each one. These milestone labels are documentation aids, not retroactively created releases.
TerraSys is a trusted, single-user local/LAN application. Do not expose it to the internet without authentication, TLS, rate limits, and a stricter upload policy. The MCP adapter in mcp/ is intentionally read-only by default and talks to the existing HTTP API instead of receiving database credentials.
The project is actively evolving. Derived map and search products can be rebuilt; personal PostGIS records and content-addressed media are the durable source of truth.