Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions .github/workflows/docker-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,35 @@ jobs:
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max

# Runs after the image job so a released chart never points at an image that
# hasn't been published yet. Only git tags publish; everything else just checks.
chart:
needs: build
runs-on: ubuntu-latest
permissions:
contents: read
packages: write

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Set up Helm
uses: azure/setup-helm@v4

- name: Lint and render
run: |
helm lint install/helm/mapserver
helm template mapserver install/helm/mapserver \
--set ingress.enabled=true --set ingress.host=tiles.example.com > /dev/null

- name: Publish chart
if: startsWith(github.ref, 'refs/tags/v')
env:
REGISTRY_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
run: |
version="${GITHUB_REF_NAME#v}"
helm package install/helm/mapserver --version "$version" --app-version "$version"
echo "$REGISTRY_PASSWORD" | helm registry login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
helm push "mapserver-$version.tgz" oci://ghcr.io/ollebo/charts
21 changes: 12 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ ollebo.com only ever sees URLs that point at your mapserver. The raster pixels s

Everyone in that space on ollebo.com can then see your maps the same way you do.

> **Status — `OLLEBO_KEY` is reserved, not yet consumed.**
> The mapserver does not currently call back to ollebo.com to register itself. Set the key now so your config is ready; the registration handshake activates in a future release. Until then, maps are visible through the local UI at `http://localhost:8888` but won't appear on ollebo.com automatically.
> **Status — pairing isn't built yet.**
> ollebo.com issues the key, but nothing on ollebo.com accepts it yet, so the Settings page shows Disconnected even with a valid key. The mapserver does not call back to ollebo.com to register itself. Until then, maps are visible through the local UI at `http://localhost:8888` but won't appear on ollebo.com automatically.

## External reachability

Expand All @@ -56,7 +56,7 @@ ngrok http 5001

Re-run the install script (or edit `.env`) with the new URL and `docker compose up -d` again.

**Kubernetes install — use an Ingress.** The Helm chart ships an optional Ingress (`--set ingress.enabled=true --set ingress.host=tiles.example.com`). Put it behind a public DNS name with TLS. For high-traffic installs, add a CDN (CloudFront, Cloudflare, Fastly) in front of the Ingress.
**Kubernetes install — use an Ingress.** The Helm chart ships an optional Ingress (`--set ingress.enabled=true --set ingress.host=tiles.example.com`). It publishes the tile routes only; the web UI has no login, so it stays private unless you set `ingress.exposeUi=true`. Put it behind a public DNS name with TLS. For high-traffic installs, add a CDN (CloudFront, Cloudflare, Fastly) in front of the Ingress.

> The tile server has **no authentication** today. Anything that can reach `TERRACOTTA_PUBLIC_URL` can request tiles. Treat the URL as a shared secret, put it behind a network policy, or wait for the auth module on the roadmap.

Expand Down Expand Up @@ -101,7 +101,7 @@ To change configuration, edit `.env` and re-run `docker compose up -d` — no ne
For a hosted install on a cloud provider — bigger map catalog, multiple users, public Ingress.

```sh
helm install mapserver install/helm/mapserver \
helm install mapserver oci://ghcr.io/ollebo/charts/mapserver \
--set ollebo.key=YOUR_KEY \
--set ollebo.spaceId=YOUR_SPACE_ID \
--set ingress.enabled=true \
Expand All @@ -115,11 +115,12 @@ Key `values.yaml` knobs:

| Value | What it controls |
|---|---|
| `image.repository`, `image.tag` | Image to deploy. Defaults to `ghcr.io/ollebo/mapserver:latest` (built and published by CI on every push to `main`). Pin to `sha-<short>` or a `vX.Y.Z` release tag for a stable rollout. |
| `ollebo.key` | Stored in a Secret. Reserved for future ollebo.com registration. |
| `image.repository`, `image.tag` | Image to deploy. Defaults to the chart's `appVersion`. Set `latest` for the newest build of `main`, or `sha-<short>` for a specific commit. |
| `ollebo.key` | Stored in a Secret. Pairing with ollebo.com isn't built yet. |
| `ollebo.spaceId`, `ollebo.apiUrl` | Non-sensitive config, stored in a ConfigMap. |
| `terracotta.publicUrl` | Public URL for tile fetches — must match your Ingress host. |
| `ingress.enabled`, `ingress.host`, `ingress.className`, `ingress.tlsSecret` | Ingress wiring. |
| `ingress.exposeUi` | Also publish the web UI. Off by default because it has no login. |
| `persistence.{maps,cogs,db}.size` | PVC size per dataset folder. |
| `persistence.{maps,cogs,db}.storageClassName` | Per-PVC StorageClass override. |

Expand Down Expand Up @@ -156,14 +157,16 @@ CI (`.github/workflows/docker-publish.yml`) builds `Dockerfile_build` on every p

- `ghcr.io/ollebo/mapserver:latest` — current `main`.
- `ghcr.io/ollebo/mapserver:sha-<short>` — pinned to a specific commit.
- `ghcr.io/ollebo/mapserver:vX.Y.Z` — on git tags matching `v*.*.*`.
- `ghcr.io/ollebo/mapserver:X.Y.Z` — on git tags matching `v*.*.*`.
- `oci://ghcr.io/ollebo/charts/mapserver` version `X.Y.Z` — the Helm chart, on the same git tags, after its image has been published.

Pull requests build the image for verification but don't push. The Docker install script builds locally from `Dockerfile_build`; the Helm chart pulls `ghcr.io/ollebo/mapserver:latest` by default.
Pull requests build the image for verification but don't push. The Docker install script builds locally from `Dockerfile_build`; the Helm chart runs the image matching its release by default.

## Known rough edges

- **No auth on the tile server.** See "External reachability."
- **`OLLEBO_KEY` is dormant.** See the pairing section above.
- **Pairing with ollebo.com isn't built.** See the pairing section above.
- **No login on the web UI.** It can upload files and show the map key, so keep it private.
- **Single-replica only on Kubernetes** because of SQLite + RWO PVCs.
- **Container build is fragile.** `Dockerfile_build` uses `--break-system-packages` on Ubuntu 24.04 with pinned `terracotta==0.10.1`. A move to a venv-based image is on the roadmap; for now, rebuild from the pinned base if pip breakage occurs.
- **Dev bind-mount is in a separate file.** `docker-compose.yaml` deploys the baked-in image. `docker-compose.override.yaml` adds the `./code:/code` live-reload mount and is auto-merged by `docker compose` when present. Delete it before publishing an image to production.
6 changes: 3 additions & 3 deletions install/helm/mapserver/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ For onboarding, env vars, and architecture, see the [top-level README](../../../
## Quick install

```sh
helm install mapserver . \
helm install mapserver oci://ghcr.io/ollebo/charts/mapserver \
--set ollebo.key=YOUR_KEY \
--set ollebo.spaceId=YOUR_SPACE_ID \
--set ingress.enabled=true \
Expand All @@ -21,13 +21,13 @@ helm install mapserver . \
- **One initContainer**: `terracotta-init` runs `ensure_schema()` against the SQLite DB so terracotta starts with a populated schema.
- **Three PVCs**: `-maps`, `-cogs`, `-db`. Independently sized and class-able via `persistence.{name}.size` / `persistence.{name}.storageClassName`.
- **One Service** with two named ports (`flask`, `terracotta`).
- **Optional Ingress** routing `/` → flask and `/tiles` → terracotta on a single host.
- **Optional Ingress** publishing terracotta's `/rgb` and `/singleband` tile routes. The Flask UI has no login, so it's only added with `ingress.exposeUi=true`.

`replicas: 1` is hard-coded with `strategy: Recreate`. This is intentional: the PVCs default to `ReadWriteOnce` (the only access mode universally supported by GKE/EKS/AKS managed disks), and SQLite is a single-writer database. Scaling out requires a `ReadWriteMany` StorageClass + a non-SQLite terracotta backend; neither is exposed today.

## Pre-install checklist

1. **Use the published image (default) or build your own.** The chart defaults to `ghcr.io/ollebo/mapserver:latest`, which CI publishes on every push to `main`. To pin a specific build, set `--set image.tag=sha-<short>` or `--set image.tag=vX.Y.Z`. To use your own registry, run `docker build -f Dockerfile_build -t YOUR_REGISTRY/mapserver:TAG .` from the repo root, push it, then `--set image.repository=YOUR_REGISTRY/mapserver --set image.tag=TAG`.
1. **Use the published image (default) or build your own.** The chart runs the image version it was released with (`appVersion`). For the newest build of `main`, set `--set image.tag=latest`. To pin a specific build, set `--set image.tag=sha-<short>`. To use your own registry, run `docker build -f Dockerfile_build -t YOUR_REGISTRY/mapserver:TAG .` from the repo root, push it, then `--set image.repository=YOUR_REGISTRY/mapserver --set image.tag=TAG`.
2. **Pick a StorageClass.** If your cluster's default doesn't fit, set `persistence.{maps,cogs,db}.storageClassName` per PVC.
3. **DNS + TLS for the Ingress.** Point your chosen host at the Ingress controller's external IP, and create a TLS Secret (or rely on `cert-manager`). Pass `ingress.tlsSecret` and any controller-specific `ingress.annotations`.
4. **Set `terracotta.publicUrl`** to match the public scheme+host you're publishing — both the browser client and the server-side tile URL builder read it.
Expand Down
28 changes: 17 additions & 11 deletions install/helm/mapserver/templates/NOTES.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,22 @@ OlleBo Mapserver installed as release: {{ .Release.Name }}

{{- if .Values.ingress.enabled }}

Tile URL (public):
https://{{ .Values.ingress.host }}{{ .Values.ingress.paths.terracotta }}

Web UI:
https://{{ .Values.ingress.host }}{{ .Values.ingress.paths.flask }}
Tile server (public):
https://{{ .Values.ingress.host }}

Make sure DNS for {{ .Values.ingress.host }} points at your Ingress controller's
external IP, and that `terracotta.publicUrl` in values.yaml matches the public
tile URL above.
external IP, and that `terracotta.publicUrl` is set to the URL above.

{{- if .Values.ingress.exposeUi }}

WARNING: ingress.exposeUi is on. The web UI has no login, so anyone who can
reach it can upload files and read the map key. Put authentication in front.
{{- else }}

The web UI is not public. Reach it with port-forward:
kubectl --namespace {{ .Release.Namespace }} port-forward svc/{{ include "mapserver.fullname" . }} 8888:{{ .Values.service.flaskPort }}
Then open http://localhost:8888
{{- end }}
{{- else }}

No Ingress was created. Reach the services with port-forward:
Expand All @@ -28,8 +35,7 @@ terracotta.publicUrl to a publicly resolvable URL.

{{- if not .Values.ollebo.key }}

WARNING: ollebo.key is empty. The mapserver runs fine, but it has no key to
pair with an ollebo.com space. Set --set ollebo.key=YOUR_KEY when you have one.
The registration handshake isn't wired up in code yet; this is preparation for
a future release.
NOTE: ollebo.key is empty. The mapserver runs fine without it. Pairing with
ollebo.com isn't built yet, so setting a key does not link the two, and the
Settings page will show Disconnected either way.
{{- end }}
6 changes: 3 additions & 3 deletions install/helm/mapserver/templates/deployment.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ spec:
{{- end }}
initContainers:
- name: terracotta-init
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
workingDir: /code
command:
Expand All @@ -55,7 +55,7 @@ spec:
mountPath: /data/db
containers:
- name: map-server
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
{{- with .Values.securityContext }}
securityContext:
Expand All @@ -82,7 +82,7 @@ spec:
{{- toYaml . | nindent 12 }}
{{- end }}
- name: terracotta
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
{{- with .Values.securityContext }}
securityContext:
Expand Down
8 changes: 6 additions & 2 deletions install/helm/mapserver/templates/ingress.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -23,18 +23,22 @@ spec:
- host: {{ .Values.ingress.host | quote }}
http:
paths:
- path: {{ .Values.ingress.paths.terracotta }}
{{- range .Values.ingress.paths.terracotta }}
- path: {{ . }}
pathType: Prefix
backend:
service:
name: {{ include "mapserver.fullname" . }}
name: {{ include "mapserver.fullname" $ }}
port:
name: terracotta
{{- end }}
{{- if .Values.ingress.exposeUi }}
- path: {{ .Values.ingress.paths.flask }}
pathType: Prefix
backend:
service:
name: {{ include "mapserver.fullname" . }}
port:
name: flask
{{- end }}
{{- end }}
19 changes: 12 additions & 7 deletions install/helm/mapserver/values.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

image:
repository: ghcr.io/ollebo/mapserver
tag: latest
# Empty means the chart's appVersion, so a chart release always runs the
# image it was published with.
tag: ""
pullPolicy: IfNotPresent
pullSecrets: []

Expand All @@ -17,8 +19,8 @@ ollebo:

terracotta:
# Browser-facing tile URL. Must be reachable from any viewer (including
# ollebo.com). When ingress.enabled=true, set this to the same scheme+host
# as ingress.host.
# ollebo.com). When ingress.enabled=true, set this to https://<ingress.host>,
# with no path.
publicUrl: http://localhost:5001
dbPath: /data/db/terracotta.sqlite
provider: sqlite
Expand All @@ -34,18 +36,21 @@ service:
flaskPort: 8080
terracottaPort: 5000

# Optional public Ingress in front of both ports.
# The default rule routes / to the Flask UI and /tiles to terracotta. Adjust
# `paths` if your Ingress controller needs different path semantics.
# Optional public Ingress. It publishes the tile routes only. The web UI has no
# login and can upload files and show the map key, so it stays private unless
# you set exposeUi=true, and then only behind your own authentication.
ingress:
enabled: false
className: ""
host: tiles.example.com
tlsSecret: ""
annotations: {}
exposeUi: false
paths:
flask: /
terracotta: /tiles
terracotta:
- /rgb
- /singleband

# Three independent PVCs back the three data directories.
persistence:
Expand Down
Loading