Added examples and documentation for the published docker image

README.md

@@ -158,6 +158,38 @@ This may be combined with the other build environment variables described above.
 
 The [topola-webpack](https://github.com/develancer/topola-webpack) tool can 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.
+
+### Running Topola Viewer
+To pull and run Topola Viewer:
+```bash
+docker run -d -p 8080:8080 ghcr.io/pewu/topola-viewer:latest
+```
+Open your web browser and go to `http://localhost:8080` to upload your family tree files locally.
+
+### Running with Your Own Data (Zero-Build Run)
+You can serve a standalone, pre-loaded family tree with zero compilation by mounting your family tree data (a `.ged` file or a zipped `.gdz` archive containing photos) directly into the running container:
+```bash
+docker run -d -p 8080:8080 \
+  -e STATIC_URL=my_family.gdz \
+  -v ./my_family.gdz:/app/public/my_family.gdz \
+  ghcr.io/pewu/topola-viewer:latest
+```
+
+### Building the Base Image Locally
+To build the base image from source:
+```bash
+docker build -t topola-viewer -f docker/Dockerfile .
+```
+
+### Ready-To-Use Standalone Templates
+For creating completely self-contained Docker images that bundle your genealogy data and serve it instantly, see these pre-configured examples:
+
+1. **[Simple Standalone Tree](docker/examples/simple/)**: Demonstrates how to package and pre-load a `.ged` file directly inside a custom image.
+2. **[Standalone Tree with Photos](docker/examples/photos/)**: Packages your family tree and a `photos/` folder into a valid `.gdz` archive on-the-fly.
+
 ## Additional options
 
 ### `handleCors`

docker/examples/photos/Dockerfile

@@ -0,0 +1,13 @@
+# Stage 1: Multi-stage helper to zip GEDCOM & photos together preserving directory structure
+FROM alpine:latest AS zipper
+RUN apk add --no-cache zip
+WORKDIR /build
+COPY family.ged ./
+COPY photos/ ./photos/
+# Zip contents relative to build root to preserve directories as referenced in GEDCOM
+RUN zip -r family.gdz family.ged photos/
+
+# Stage 2: Load the zip file into the official container
+FROM ghcr.io/pewu/topola-viewer:latest
+COPY --from=zipper /build/family.gdz /app/public/family.gdz
+ENV STATIC_URL=family.gdz

docker/examples/photos/README.md

@@ -0,0 +1,18 @@
+# Standalone Zipped Family Tree Container with Photos
+
+This example leverages a multi-stage Docker build to automatically compress your `.ged` file and `photos/` folder into a secure `.gdz` archive on-the-fly, preserving your image directory path structures.
+
+## Structure
+* Place your `family.ged` file here.
+* Place your photos also in this directory, or inside a `photos/` folder in this directory. If you put the photos in the `photos/` directory, make sure your GEDCOM file contains file references containing the `photos/` prefix. See the sample [family.ged](family.ged).
+
+## Instructions
+
+1. Build your custom container:
+   ```bash
+   docker build -t my-photo-tree .
+   ```
+2. Run your container:
+   ```bash
+   docker run -d -p 8080:8080 my-photo-tree
+   ```

docker/examples/photos/family.ged

@@ -0,0 +1,32 @@
+0 HEAD
+1 SOUR GENJ
+2 VERS 1.0
+1 GEDC
+2 VERS 5.5.1
+2 FORM Lineage-Linked
+1 CHAR UTF-8
+0 @I1@ INDI
+1 NAME John /Doe/
+1 SEX M
+1 OBJE
+2 FILE photos/I1.jpg
+3 FORM JPG
+3 TITL John Doe Photo
+1 FAMS @F1@
+0 @I2@ INDI
+1 NAME Jane /Smith/
+1 SEX F
+1 OBJE
+2 FILE photos/I2.jpg
+3 FORM JPG
+3 TITL Jane Smith Photo
+1 FAMS @F1@
+0 @F1@ FAM
+1 HUSB @I1@
+1 WIFE @I2@
+1 CHIL @I3@
+0 @I3@ INDI
+1 NAME Bobby /Doe/
+1 SEX M
+1 FAMC @F1@
+0 TRLR

docker/examples/simple/Dockerfile

@@ -0,0 +1,8 @@
+# Start from the official compiled container
+FROM ghcr.io/pewu/topola-viewer:latest
+
+# Copy the unzipped GEDCOM file directly into public folder
+COPY family.ged /app/public/family.ged
+
+# Configure server to pre-load this raw GEDCOM file
+ENV STATIC_URL=family.ged

docker/examples/simple/README.md

@@ -0,0 +1,15 @@
+# Standalone GEDCOM Container Example
+
+This example builds a self-contained image that hosts a single `.ged` file directly (no photos).
+
+## Instructions
+
+1. Put your GEDCOM file in this directory and name it `family.ged`.
+2. Build your custom container:
+   ```bash
+   docker build -t my-simple-tree .
+   ```
+3. Run your container:
+   ```bash
+   docker run -d -p 8080:8080 my-simple-tree
+   ```

docker/examples/simple/family.ged

@@ -0,0 +1,37 @@
+0 HEAD
+1 SOUR GENJ
+2 VERS 1.0
+1 GEDC
+2 VERS 5.5.1
+2 FORM Lineage-Linked
+1 CHAR UTF-8
+0 @I1@ INDI
+1 NAME John /Doe/
+1 SEX M
+1 FAMS @F1@
+1 FAMC @F2@
+0 @I2@ INDI
+1 NAME Jane /Smith/
+1 SEX F
+1 FAMS @F1@
+0 @F1@ FAM
+1 HUSB @I1@
+1 WIFE @I2@
+1 CHIL @I3@
+1 CHIL @I4@
+0 @I3@ INDI
+1 NAME Bobby /Doe/
+1 SEX M
+1 FAMC @F1@
+0 @I4@ INDI
+1 NAME Sally /Doe/
+1 SEX F
+1 FAMC @F1@
+0 @I5@ INDI
+1 NAME Grandpa /Doe/
+1 SEX M
+1 FAMS @F2@
+0 @F2@ FAM
+1 HUSB @I5@
+1 CHIL @I1@
+0 TRLR