mirror of
https://github.com/n30nex/CartoLite-Server.git
synced 2026-10-17 07:09:54 +00:00
n30nex
cc41644493
* Fix ingest indexing, stream replay and shutdown reliability * Verify upgrades from the published Worldwide release * Require an existing release tag before image promotion
77 lines
5.5 KiB
Markdown
77 lines
5.5 KiB
Markdown
# Deployment
|
||
|
||
## Install the published image
|
||
|
||
Docker Engine and Compose v2 are required. Published images support `linux/amd64` and `linux/arm64`, including 64-bit Raspberry Pi hosts. No Node, Go, source build or map-provider account is required.
|
||
|
||
In a new directory, download `compose.yml` and `default.env.example` from the latest release. Save the environment example as `.env`, then set your MQTT broker, topic and any required username/password. Leave `MQTT_CLIENT_ID` empty for an automatically unique clean-session identity, or set a unique ID if your broker requires one. Existing configured IDs are preserved; installations using the old shared `cartolite-server` default should clear it or choose their own ID.
|
||
|
||
```sh
|
||
docker compose pull
|
||
docker compose up -d --no-build
|
||
docker compose ps
|
||
curl --fail http://127.0.0.1:8080/healthz
|
||
curl --fail http://127.0.0.1:8080/readyz
|
||
```
|
||
|
||
The map is at `http://localhost:8080/`; Netgraph is at `/netgraph/`. Default maps and buildings use OpenFreeMap without a key. `/api/config` contains only public map-provider settings; the traffic API remains schema v2.
|
||
|
||
## Configuration
|
||
|
||
| Variable | Default | Purpose |
|
||
|---|---|---|
|
||
| `CARTOLITE_IMAGE` | versioned `ghcr.io/n30nex/cartolite-server` image | Published tag or exact release-manifest digest |
|
||
| `CARTOLITE_BIND_ADDR` | `127.0.0.1` | Host bind address |
|
||
| `CARTOLITE_PORT` | `8080` | Host HTTP port |
|
||
| `MQTT_BROKER_URL` | required | Your MeshCore broker URL (`tcp`, `ssl`, `ws`, or `wss`) |
|
||
| `MQTT_TOPIC` | `meshcore/#` | Subscription filter |
|
||
| `MQTT_CLIENT_ID` | generated per process | Optional explicit ID; must be unique per instance |
|
||
| `MQTT_USERNAME` / `MQTT_PASSWORD` | empty | Configure both when authentication is required |
|
||
| `REGION_ALLOWLIST` | empty | Accept all valid regions, or exact comma-separated labels |
|
||
| `MQTT_INGEST_QUEUE_SIZE` | `4096` | Bounded ingest queue |
|
||
| `STATE_PATH` | `/data/state-v1.json` | Atomic checkpoint |
|
||
| `LOG_LEVEL` | `info` | Application logging |
|
||
|
||
Use the loopback bind behind a TLS reverse proxy for public operation. Set `CARTOLITE_BIND_ADDR=0.0.0.0` explicitly for appropriate LAN access. Keep the non-root user, read-only filesystem, dropped capabilities, data volume, health checks and resource/log limits supplied by Compose.
|
||
|
||
## Optional CARTO provider
|
||
|
||
Download `compose.carto.yml` from the same release. Store your site-restricted CARTO browser key in `.secrets/carto-basemap-api-key`. The file must be readable by the container’s UID 65532; on Linux, give that UID ownership and mode 0400. A custom host path can be set with `CARTO_BASEMAP_API_KEY_FILE` in `.env`.
|
||
|
||
```sh
|
||
docker compose -f compose.yml -f compose.carto.yml up -d --no-build
|
||
```
|
||
|
||
The override mounts the file at `/run/secrets/carto_basemap_api_key` and selects `BASEMAP_PROVIDER=carto`. The key is read at startup; restart the service after changing it. It is intentionally visible in browser configuration/tile requests, just as with the previous compiled browser key. It is never included in the published image. MQTT credentials are never returned by `/api/config`. OpenFreeMap remains the building source when CARTO is selected.
|
||
|
||
## Upgrades
|
||
|
||
Record the current image/digest and keep a private, verified checkpoint backup before upgrading. Retain the current `.env`, project name and `cartolite-data` volume. Download the new Compose file without replacing your environment file, set `CARTOLITE_IMAGE` to the new version or release-manifest digest, then run `docker compose pull` and `docker compose up -d --no-build`.
|
||
|
||
When upgrading from the 0.4.x source distribution, replace `cartolite-server:local` in `.env` with the published image. The default becomes key-free OpenFreeMap; add the CARTO override above to keep your existing provider. Old build-only version variables are no longer required. The checkpoint format is unchanged.
|
||
|
||
Verify health/readiness, retained nodes and routes, live traffic, Map and Netgraph after the upgrade. Roll back by selecting the recorded image and recreating only the CartoLite service; use the verified checkpoint recovery copy if state recovery is necessary. Never run `docker compose down -v` against an installation you intend to keep.
|
||
|
||
## Source builds
|
||
|
||
A source checkout can use `compose.build.yml` explicitly:
|
||
|
||
```sh
|
||
docker compose -f compose.yml -f compose.build.yml build --pull
|
||
docker compose -f compose.yml -f compose.build.yml up -d --no-build
|
||
```
|
||
|
||
Runtime provider configuration is identical for source-built and published images. Maintainer builds, tests and releases run only in GitHub Actions; no workstation build is used for a release.
|
||
|
||
## Release verification
|
||
|
||
Actions tests native amd64 and arm64 images, including synthetic MQTT/privacy/load checks and a checkpoint-preserving upgrade from 0.4.1. Browser checks run against the same frontend on amd64. Main publishes and attests the tested platform digests, assembles their index without rebuilding, and verifies anonymous pulls and the Compose recipe on both architectures. Tag releases promote that exact index and publish Compose files, source archives, a release manifest and SHA256SUMS.
|
||
|
||
## Proxy content integrity
|
||
|
||
Preserve the HTML response's `Cache-Control: public, no-cache, no-transform` header at
|
||
reverse proxies and CDNs. This prevents automatic script injection, including
|
||
Cloudflare Web Analytics, without weakening CartoLite's Content Security Policy.
|
||
Do not add analytics hosts to the script allowlist to silence CSP errors. See
|
||
[Cloudflare's automatic setup documentation](https://developers.cloudflare.com/web-analytics/get-started/).
|