Add Unraid deployment template
GeoIntel CI / docs-smoke (push) Has been cancelled
GeoIntel CI / contract-smoke (push) Has been cancelled

This commit is contained in:
Codex
2026-06-17 04:22:38 +02:00
parent 47103ed1a9
commit 3a8b82f59a
14 changed files with 363 additions and 14 deletions
+10
View File
@@ -20,3 +20,13 @@ OSM_OVERPASS_URL=https://overpass-api.de/api/interpreter
VITE_API_BASE_URL=
VITE_API_PROXY_TARGET=http://localhost:8000
VITE_MAP_STYLE_URL=https://demotiles.maplibre.org/style.json
# Docker Compose / Unraid
GEOINTEL_FRONTEND_PORT=1202
GEOINTEL_BACKEND_PORT=8000
GEOINTEL_STORAGE_PATH=./storage
GEOINTEL_POSTGRES_DB=geointel
GEOINTEL_POSTGRES_USER=geointel
GEOINTEL_POSTGRES_PASSWORD=geointel
GEOINTEL_CORS_ORIGINS=http://localhost:1202,http://127.0.0.1:1202
GEOINTEL_MAX_UPLOAD_MB=500
+9
View File
@@ -7,6 +7,15 @@
# Changelog
## Sprint 31 Unraid deployment template (2026-06-17)
- Made Docker Compose ports, storage path, PostGIS credentials, CORS origins and upload limit configurable through `.env` defaults.
- Added `deploy/unraid/geointel.env.example` for Unraid/Tower setup.
- Added `deploy/unraid/geointel-unraid-template.xml` documenting editable Unraid settings for the multi-container Compose stack.
- Added GeoIntel SVG icon assets for Unraid/template use and frontend favicon serving.
- Added regression coverage for Compose env defaults, Unraid template settings, README instructions and icon availability.
- No API contracts, backend behavior, migrations, product features, provider fetching or AI behavior were introduced.
## Sprint 30 workbench component decomposition (2026-06-17)
- Moved persisted QA/QC result rendering into `QualityResultsPanel`.
+29
View File
@@ -67,6 +67,35 @@ This is a documentation-driven engineering repo. The documentation is not decora
make readiness
```
## Unraid / Tower deployment
GeoIntel runs on Unraid as a Docker Compose stack with PostGIS, backend and frontend services. The frontend is the browser entrypoint and proxies `/api` and `/health` to the backend.
Unraid template assets live in:
- `deploy/unraid/geointel.env.example`
- `deploy/unraid/geointel-unraid-template.xml`
- `deploy/unraid/geointel-icon.svg`
Copy the Unraid env template to `.env` in the checkout and edit ports there:
```bash
cd /mnt/user/appdata/geointel
cp deploy/unraid/geointel.env.example .env
nano .env
docker compose up -d --build
```
Common editable values:
```env
GEOINTEL_FRONTEND_PORT=1202
GEOINTEL_BACKEND_PORT=8000
GEOINTEL_STORAGE_PATH=/mnt/user/appdata/geointel/storage
```
The database port is intentionally not exposed to the LAN. See `deploy/unraid/README.md` for full setup, port-change and cleanup notes.
## Sprint 2 quick start
- Update dependencies:
+8 -5
View File
@@ -41,15 +41,18 @@ def test_compose_does_not_require_missing_root_env_file() -> None:
compose = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
assert "env_file:" not in compose
assert "DATABASE_URL: postgresql+psycopg://geointel:geointel@db:5432/geointel" in compose
assert "DATABASE_URL: postgresql+psycopg://${GEOINTEL_POSTGRES_USER:-geointel}" in compose
def test_compose_exposes_frontend_on_host_port_1202_with_cors_origin() -> None:
def test_compose_exposes_frontend_on_configurable_host_port_with_cors_origin() -> None:
compose = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
env_example = (ROOT / ".env.example").read_text(encoding="utf-8")
assert '"1202:80"' in compose
assert "CORS_ORIGINS: http://localhost:1202,http://127.0.0.1:1202" in compose
assert '"${GEOINTEL_FRONTEND_PORT:-1202}:80"' in compose
assert '"${GEOINTEL_BACKEND_PORT:-8000}:8000"' in compose
assert "CORS_ORIGINS: ${GEOINTEL_CORS_ORIGINS:-http://localhost:1202,http://127.0.0.1:1202}" in compose
assert "GEOINTEL_FRONTEND_PORT=1202" in env_example
assert "GEOINTEL_BACKEND_PORT=8000" in env_example
assert "http://localhost:1202" in env_example
assert "http://127.0.0.1:1202" in env_example
@@ -92,7 +95,7 @@ def test_compose_does_not_publish_postgis_on_default_host_port() -> None:
def test_compose_waits_for_healthy_database_and_applies_migrations() -> None:
compose = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
assert "pg_isready -U geointel -d geointel" in compose
assert "pg_isready -U ${GEOINTEL_POSTGRES_USER:-geointel} -d ${GEOINTEL_POSTGRES_DB:-geointel}" in compose
assert "condition: service_healthy" in compose
assert "sh /app/docker_start.sh" in compose
@@ -0,0 +1,63 @@
from __future__ import annotations
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
def test_unraid_template_documents_editable_runtime_settings() -> None:
template = (ROOT / "deploy" / "unraid" / "geointel-unraid-template.xml").read_text(encoding="utf-8")
assert "<Name>GeoIntel Kempen</Name>" in template
assert "GeoIntel is a multi-container Docker Compose stack" in template
assert "<WebUI>http://[IP]:[PORT:1202]/</WebUI>" in template
assert "<Icon>http://[IP]:[PORT:1202]/geointel-icon.svg</Icon>" in template
assert 'Target="GEOINTEL_FRONTEND_PORT"' in template
assert 'Target="GEOINTEL_BACKEND_PORT"' in template
assert 'Target="GEOINTEL_STORAGE_PATH"' in template
assert 'Target="GEOINTEL_POSTGRES_PASSWORD"' in template
assert 'Mask="true">change-me-before-shared-use</Config>' in template
def test_unraid_env_template_matches_compose_variables() -> None:
compose = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
env_template = (ROOT / "deploy" / "unraid" / "geointel.env.example").read_text(encoding="utf-8")
for key in (
"GEOINTEL_FRONTEND_PORT",
"GEOINTEL_BACKEND_PORT",
"GEOINTEL_STORAGE_PATH",
"GEOINTEL_POSTGRES_DB",
"GEOINTEL_POSTGRES_USER",
"GEOINTEL_POSTGRES_PASSWORD",
"GEOINTEL_CORS_ORIGINS",
"GEOINTEL_MAX_UPLOAD_MB",
):
assert key in compose
assert f"{key}=" in env_template
assert "GEOINTEL_FRONTEND_PORT=1202" in env_template
assert "GEOINTEL_STORAGE_PATH=/mnt/user/appdata/geointel/storage" in env_template
def test_unraid_readme_explains_port_changes_and_safe_cleanup() -> None:
readme = (ROOT / "deploy" / "unraid" / "README.md").read_text(encoding="utf-8")
assert "cp deploy/unraid/geointel.env.example .env" in readme
assert "GEOINTEL_FRONTEND_PORT=1203" in readme
assert "docker compose up -d --build" in readme
assert "bash scripts/live_migration_smoke.sh" in readme
assert "docker builder prune -af" in readme
assert "Avoid broad volume pruning" in readme
def test_frontend_and_unraid_icon_assets_are_present() -> None:
deploy_icon = (ROOT / "deploy" / "unraid" / "geointel-icon.svg").read_text(encoding="utf-8")
frontend_icon = (ROOT / "frontend" / "public" / "geointel-icon.svg").read_text(encoding="utf-8")
index = (ROOT / "frontend" / "index.html").read_text(encoding="utf-8")
assert "<svg" in deploy_icon
assert "GeoIntel Kempen" in deploy_icon
assert deploy_icon == frontend_icon
assert '<link rel="icon" type="image/svg+xml" href="/geointel-icon.svg" />' in index
+108
View File
@@ -0,0 +1,108 @@
# GeoIntel Unraid template
GeoIntel is a multi-container Docker Compose stack:
- `db`: PostGIS 16 / PostGIS 3.4
- `backend`: FastAPI/GIS runtime
- `frontend`: nginx-served React app with `/api` and `/health` proxying to the backend
The normal browser entrypoint is:
```text
http://<unraid-ip>:${GEOINTEL_FRONTEND_PORT}
```
## Files
- `geointel.env.example`: copy this to the repository checkout as `.env`.
- `geointel-unraid-template.xml`: Unraid/DockerMan-style metadata for the editable settings.
- `geointel-icon.svg`: icon source for template/app metadata.
The frontend also serves the same icon at:
```text
http://<unraid-ip>:${GEOINTEL_FRONTEND_PORT}/geointel-icon.svg
```
## First setup on Unraid
From the Unraid shell:
```bash
cd /mnt/user/appdata
git clone gitea-widefrog:NuklearRabbit/geointel.git geointel
cd /mnt/user/appdata/geointel
cp deploy/unraid/geointel.env.example .env
```
Edit `.env` before starting the stack:
```bash
nano .env
```
Common values:
```env
GEOINTEL_FRONTEND_PORT=1202
GEOINTEL_BACKEND_PORT=8000
GEOINTEL_STORAGE_PATH=/mnt/user/appdata/geointel/storage
GEOINTEL_POSTGRES_PASSWORD=change-me-before-shared-use
GEOINTEL_CORS_ORIGINS=http://localhost:1202,http://127.0.0.1:1202,http://192.168.10.150:1202
```
Start or rebuild:
```bash
docker compose config
docker compose up -d --build
```
Validate:
```bash
bash scripts/live_migration_smoke.sh
bash scripts/verify_browser_runtime.sh "http://192.168.10.150:${GEOINTEL_FRONTEND_PORT:-1202}"
```
## Change ports
Change the web UI port:
```env
GEOINTEL_FRONTEND_PORT=1203
```
If you expose a different web port, also update CORS origins:
```env
GEOINTEL_CORS_ORIGINS=http://localhost:1203,http://127.0.0.1:1203,http://192.168.10.150:1203
```
Apply:
```bash
docker compose up -d --build
```
The database port is intentionally not published to the LAN. The backend reaches it through the internal Compose service name `db`.
## Update from Gitea
```bash
cd /mnt/user/appdata/geointel
git fetch origin main
git reset --hard origin/main
docker compose up -d --build
bash scripts/live_migration_smoke.sh
```
## Cleanup notes
Safe cache cleanup if Docker build cache fills the Unraid Docker image:
```bash
docker builder prune -af
```
Avoid broad volume pruning unless you explicitly intend to remove persisted PostGIS data or GeoIntel artifacts.
+20
View File
@@ -0,0 +1,20 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-labelledby="title desc">
<title id="title">GeoIntel Kempen</title>
<desc id="desc">Hexagonal map and intelligence mark for the GeoIntel workbench.</desc>
<defs>
<linearGradient id="bg" x1="32" x2="224" y1="224" y2="32" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#0f766e"/>
<stop offset="0.52" stop-color="#2563eb"/>
<stop offset="1" stop-color="#111827"/>
</linearGradient>
</defs>
<rect width="256" height="256" rx="48" fill="url(#bg)"/>
<path d="M128 28 213 77v102l-85 49-85-49V77z" fill="#ffffff" opacity="0.12"/>
<path d="M128 45 198 86v84l-70 41-70-41V86z" fill="none" stroke="#e0f2fe" stroke-width="10"/>
<path d="M79 91 128 63l49 28v57l-49 28-49-28z" fill="#ecfeff" opacity="0.95"/>
<path d="M86 145c18-10 37-10 56 0 17 9 33 9 48 0v26l-62 36-62-36v-19c7 0 14-2 20-7z" fill="#14b8a6" opacity="0.9"/>
<path d="M66 106c17 9 34 9 51 0 20-11 40-11 60 0 5 3 10 5 15 6" fill="none" stroke="#2563eb" stroke-width="9" stroke-linecap="round"/>
<circle cx="128" cy="120" r="19" fill="#111827"/>
<circle cx="128" cy="120" r="8" fill="#67e8f9"/>
<path d="M128 101v-24M128 163v-24M109 120H85M171 120h-24" stroke="#111827" stroke-width="8" stroke-linecap="round"/>
</svg>

After

Width:  |  Height:  |  Size: 1.3 KiB

@@ -0,0 +1,33 @@
<?xml version="1.0" encoding="utf-8"?>
<Container version="2">
<Name>GeoIntel Kempen</Name>
<Repository>Local Docker Compose stack</Repository>
<Registry>gitea-widefrog:NuklearRabbit/geointel.git</Registry>
<Network>bridge</Network>
<Shell>sh</Shell>
<Privileged>false</Privileged>
<Support>http://192.168.10.150:1202</Support>
<Project>GeoIntel Kempen</Project>
<Overview>GeoIntel is a multi-container Docker Compose stack for the GeoIntel Kempen GeoAI Workbench: PostGIS, FastAPI and React/MapLibre. Use this template together with deploy/unraid/geointel.env.example and docker-compose.yml; it documents the editable Unraid settings for the Compose stack.</Overview>
<Category>Productivity: Tools: GIS:</Category>
<WebUI>http://[IP]:[PORT:1202]/</WebUI>
<TemplateURL>deploy/unraid/geointel-unraid-template.xml</TemplateURL>
<Icon>http://[IP]:[PORT:1202]/geointel-icon.svg</Icon>
<ExtraParams/>
<PostArgs/>
<CPUset/>
<DateInstalled/>
<DonateText/>
<DonateLink/>
<Description>
GeoIntel Kempen runs as a Docker Compose stack with services db, backend and frontend. Edit the matching .env variables to change ports and paths, then run docker compose up -d --build from /mnt/user/appdata/geointel.
</Description>
<Config Name="Web UI Port" Target="GEOINTEL_FRONTEND_PORT" Default="1202" Mode="" Description="Host port mapped to the frontend nginx container port 80." Type="Variable" Display="always" Required="true" Mask="false">1202</Config>
<Config Name="Backend API Port" Target="GEOINTEL_BACKEND_PORT" Default="8000" Mode="" Description="Optional host port mapped to backend container port 8000. Normal browser traffic uses the frontend /api proxy." Type="Variable" Display="advanced" Required="true" Mask="false">8000</Config>
<Config Name="Storage Path" Target="GEOINTEL_STORAGE_PATH" Default="/mnt/user/appdata/geointel/storage" Mode="rw" Description="Persistent GeoIntel artifact storage for uploads, tiles, masks, reports and exports." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/geointel/storage</Config>
<Config Name="Postgres Database" Target="GEOINTEL_POSTGRES_DB" Default="geointel" Mode="" Description="Internal PostGIS database name." Type="Variable" Display="advanced" Required="true" Mask="false">geointel</Config>
<Config Name="Postgres User" Target="GEOINTEL_POSTGRES_USER" Default="geointel" Mode="" Description="Internal PostGIS database user." Type="Variable" Display="advanced" Required="true" Mask="false">geointel</Config>
<Config Name="Postgres Password" Target="GEOINTEL_POSTGRES_PASSWORD" Default="change-me-before-shared-use" Mode="" Description="Internal PostGIS database password. Change before shared use." Type="Variable" Display="advanced" Required="true" Mask="true">change-me-before-shared-use</Config>
<Config Name="CORS Origins" Target="GEOINTEL_CORS_ORIGINS" Default="http://localhost:1202,http://127.0.0.1:1202,http://192.168.10.150:1202" Mode="" Description="Comma-separated browser origins allowed to call the backend directly." Type="Variable" Display="advanced" Required="false" Mask="false">http://localhost:1202,http://127.0.0.1:1202,http://192.168.10.150:1202</Config>
<Config Name="Max Upload MB" Target="GEOINTEL_MAX_UPLOAD_MB" Default="500" Mode="" Description="Maximum upload size in MiB enforced by the backend settings." Type="Variable" Display="advanced" Required="true" Mask="false">500</Config>
</Container>
+23
View File
@@ -0,0 +1,23 @@
# GeoIntel Unraid/Compose environment template.
# Copy this file to /mnt/user/appdata/geointel/.env and edit values there.
# Browser URL: http://<unraid-ip>:<GEOINTEL_FRONTEND_PORT>
GEOINTEL_FRONTEND_PORT=1202
# Optional direct backend API port. The frontend proxies /api and /health, so this
# does not need to be exposed to normal browser users.
GEOINTEL_BACKEND_PORT=8000
# Persisted application artifacts: uploads, tiles, masks, reports and exports.
GEOINTEL_STORAGE_PATH=/mnt/user/appdata/geointel/storage
# Internal PostGIS database settings. The database is not published to the LAN.
GEOINTEL_POSTGRES_DB=geointel
GEOINTEL_POSTGRES_USER=geointel
GEOINTEL_POSTGRES_PASSWORD=change-me-before-shared-use
# Browser origins allowed when directly calling the backend API.
GEOINTEL_CORS_ORIGINS=http://localhost:1202,http://127.0.0.1:1202,http://192.168.10.150:1202
# Upload guard in MiB.
GEOINTEL_MAX_UPLOAD_MB=500
+10 -9
View File
@@ -2,13 +2,13 @@ services:
db:
image: postgis/postgis:16-3.4
environment:
POSTGRES_DB: geointel
POSTGRES_USER: geointel
POSTGRES_PASSWORD: geointel
POSTGRES_DB: ${GEOINTEL_POSTGRES_DB:-geointel}
POSTGRES_USER: ${GEOINTEL_POSTGRES_USER:-geointel}
POSTGRES_PASSWORD: ${GEOINTEL_POSTGRES_PASSWORD:-geointel}
volumes:
- geointel_postgis:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U geointel -d geointel"]
test: ["CMD-SHELL", "pg_isready -U ${GEOINTEL_POSTGRES_USER:-geointel} -d ${GEOINTEL_POSTGRES_DB:-geointel}"]
interval: 5s
timeout: 5s
retries: 10
@@ -17,13 +17,14 @@ services:
build:
context: ./backend
environment:
DATABASE_URL: postgresql+psycopg://geointel:geointel@db:5432/geointel
DATABASE_URL: postgresql+psycopg://${GEOINTEL_POSTGRES_USER:-geointel}:${GEOINTEL_POSTGRES_PASSWORD:-geointel}@db:5432/${GEOINTEL_POSTGRES_DB:-geointel}
STORAGE_ROOT: /app/storage
CORS_ORIGINS: http://localhost:1202,http://127.0.0.1:1202
CORS_ORIGINS: ${GEOINTEL_CORS_ORIGINS:-http://localhost:1202,http://127.0.0.1:1202}
MAX_UPLOAD_MB: ${GEOINTEL_MAX_UPLOAD_MB:-500}
ports:
- "8000:8000"
- "${GEOINTEL_BACKEND_PORT:-8000}:8000"
volumes:
- ./storage:/app/storage
- ${GEOINTEL_STORAGE_PATH:-./storage}:/app/storage
- ./fixtures:/app/fixtures:ro
command: sh /app/docker_start.sh
depends_on:
@@ -40,7 +41,7 @@ services:
build:
context: ./frontend
ports:
- "1202:80"
- "${GEOINTEL_FRONTEND_PORT:-1202}:80"
depends_on:
backend:
condition: service_healthy
+27
View File
@@ -1,3 +1,30 @@
## Sprint 31 Unraid deployment template (2026-06-17)
Changed:
- Made `docker-compose.yml` configurable through `.env` defaults for frontend port, backend port, storage path, PostGIS database/user/password, CORS origins and upload limit.
- Added `deploy/unraid/geointel.env.example` for Unraid/Tower runtime configuration.
- Added `deploy/unraid/geointel-unraid-template.xml` as Unraid/DockerMan-style metadata for the editable Compose stack settings.
- Added `deploy/unraid/geointel-icon.svg` and served the same icon through `frontend/public/geointel-icon.svg`.
- Added the frontend favicon link for the GeoIntel icon.
- Added Sprint 31 tests for Unraid template coverage, compose variable coverage, docs and icon availability.
- Updated root README, TODO and changelog docs.
Validation:
- `python -m pytest backend/tests/test_sprint31_unraid_template.py backend/tests/test_docker_runtime_config.py` passed: 22 tests.
- `cd frontend && npm run typecheck` passed.
- `cd frontend && npm run build` passed.
- `python -m compileall backend/app` passed.
- `cd backend && python -m pytest` passed: 177 tests.
- `bash scripts/run_readiness_check.sh` passed: 177 backend tests, frontend typecheck/build, Alembic head check and script syntax checks.
- `cd backend && python -m alembic heads` passed: single head `202606120900`.
- `cd backend && python -m alembic upgrade head --sql` passed.
- `bash -n scripts/live_migration_smoke.sh` passed.
Notes:
- Local Windows environment does not have `docker` in PATH, so local `docker compose config` could not be run from this machine.
- The Tower deployment pass should validate Docker Compose config and live runtime after commit.
- No API contracts, backend behavior, migrations, product features, provider fetching or AI behavior changed.
## Sprint 30 workbench component decomposition (2026-06-17)
Changed:
+2
View File
@@ -10,6 +10,7 @@ This file now starts with the current implementation status. Older preparation/b
- [x] Fix Docker backend package install order and remove mandatory root `.env` dependency.
- [x] Add Docker build context ignores for backend and frontend.
- [x] Run Docker/PostGIS live validation on Tower/Unraid.
- [x] Add Unraid Compose template assets with editable ports, storage path and app icon.
## Current implementation status
@@ -41,6 +42,7 @@ This file now starts with the current implementation status. Older preparation/b
- [x] Dataset, raster and vector workflow hook extraction beyond Sprint 10.
- [x] Dataset detail, raster controls and vector controls component decomposition.
- [x] QA/QC results and map workspace component decomposition.
- [x] Docker Compose port/storage/database configuration via `.env` defaults for Unraid.
- [ ] Further frontend component decomposition for export preview and shared workbench orchestration.
## Sprint 8 status
+1
View File
@@ -3,6 +3,7 @@
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="icon" type="image/svg+xml" href="/geointel-icon.svg" />
<title>GeoIntel Kempen</title>
</head>
<body>
+20
View File
@@ -0,0 +1,20 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-labelledby="title desc">
<title id="title">GeoIntel Kempen</title>
<desc id="desc">Hexagonal map and intelligence mark for the GeoIntel workbench.</desc>
<defs>
<linearGradient id="bg" x1="32" x2="224" y1="224" y2="32" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#0f766e"/>
<stop offset="0.52" stop-color="#2563eb"/>
<stop offset="1" stop-color="#111827"/>
</linearGradient>
</defs>
<rect width="256" height="256" rx="48" fill="url(#bg)"/>
<path d="M128 28 213 77v102l-85 49-85-49V77z" fill="#ffffff" opacity="0.12"/>
<path d="M128 45 198 86v84l-70 41-70-41V86z" fill="none" stroke="#e0f2fe" stroke-width="10"/>
<path d="M79 91 128 63l49 28v57l-49 28-49-28z" fill="#ecfeff" opacity="0.95"/>
<path d="M86 145c18-10 37-10 56 0 17 9 33 9 48 0v26l-62 36-62-36v-19c7 0 14-2 20-7z" fill="#14b8a6" opacity="0.9"/>
<path d="M66 106c17 9 34 9 51 0 20-11 40-11 60 0 5 3 10 5 15 6" fill="none" stroke="#2563eb" stroke-width="9" stroke-linecap="round"/>
<circle cx="128" cy="120" r="19" fill="#111827"/>
<circle cx="128" cy="120" r="8" fill="#67e8f9"/>
<path d="M128 101v-24M128 163v-24M109 120H85M171 120h-24" stroke="#111827" stroke-width="8" stroke-linecap="round"/>
</svg>

After

Width:  |  Height:  |  Size: 1.3 KiB