From 6311c3e8ada6d9ddac592f0aa6ddd40f8cb6a552 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Przemek=20Wi=C4=99ch?= <pwiech@gmail.com>
Date: Tue, 15 Sep 2026 17:11:56 +0200
Subject: [PATCH] Add Docker Compose support for Topola Viewer

---
 PROJECT_STRUCTURE.md     |  4 ++++
 README.md                | 40 ++++++++++++++++++++++++++++++++++++++--
 docker-compose.build.yml | 11 +++++++++++
 docker-compose.yml       |  8 ++++++++
 4 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 docker-compose.build.yml
 create mode 100644 docker-compose.yml

diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md
index fa34356..0cd87d7 100644
--- a/PROJECT_STRUCTURE.md
+++ b/PROJECT_STRUCTURE.md
@@ -26,6 +26,10 @@ in the project:
 ### Build & Environment
 
 - **[.env](.env)**: Contains environment variables for the project.
+- **[docker-compose.yml](docker-compose.yml)**: Runs the published GHCR image
+  using Docker Compose.
+- **[docker-compose.build.yml](docker-compose.build.yml)**: Builds and runs the
+  application from local source using Docker Compose.
 - **[vite.config.mts](vite.config.mts)**: Configuration file for the Vite build
   tool.
 
diff --git a/README.md b/README.md
index 5ffaab4..336e58a 100644
--- a/README.md
+++ b/README.md
@@ -217,9 +217,45 @@ build a Topola Genealogy Viewer package bundled together with a GEDCOM file.
 ## Docker Container Deployment
 
 Topola Viewer can be run locally or deployed to standard cloud environments
-using Docker.
+using Docker and Docker Compose.
 
-### Running Topola Viewer
+### Running with Docker Compose
+
+To pull and run the official published image
+(`ghcr.io/pewu/topola-viewer:latest`) using Docker Compose:
+
+```bash
+docker compose up
+```
+
+To build from local source and start:
+
+```bash
+docker compose -f docker-compose.build.yml up
+```
+
+To force a rebuild from source and start:
+
+```bash
+docker compose -f docker-compose.build.yml up --build
+```
+
+#### Custom Port and Static URL
+
+You can customize the host port (`PORT`, default: `8080`) and pre-load a static
+tree URL (`STATIC_URL`) using environment variables or a `.env` file:
+
+```bash
+PORT=3000 STATIC_URL=https://example.org/sample.ged docker compose up
+```
+
+Or when building from source:
+
+```bash
+PORT=3000 STATIC_URL=https://example.org/sample.ged docker compose -f docker-compose.build.yml up
+```
+
+### Running Topola Viewer with Docker
 
 To pull and run Topola Viewer:
 
diff --git a/docker-compose.build.yml b/docker-compose.build.yml
new file mode 100644
index 0000000..b59781b
--- /dev/null
+++ b/docker-compose.build.yml
@@ -0,0 +1,11 @@
+services:
+  topola-viewer:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile
+    image: topola-viewer
+    container_name: topola-viewer
+    ports:
+      - '${PORT:-8080}:8080'
+    environment:
+      - STATIC_URL=${STATIC_URL:-}
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..9536bcd
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,8 @@
+services:
+  topola-viewer:
+    image: ghcr.io/pewu/topola-viewer:latest
+    container_name: topola-viewer
+    ports:
+      - '${PORT:-8080}:8080'
+    environment:
+      - STATIC_URL=${STATIC_URL:-}