diff --git a/README.md b/README.md index 2ff4868..54bcf8a 100644 --- a/README.md +++ b/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` diff --git a/docker/examples/photos/Dockerfile b/docker/examples/photos/Dockerfile new file mode 100644 index 0000000..ad7f030 --- /dev/null +++ b/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 diff --git a/docker/examples/photos/README.md b/docker/examples/photos/README.md new file mode 100644 index 0000000..d27bb3d --- /dev/null +++ b/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 + ``` diff --git a/docker/examples/photos/family.ged b/docker/examples/photos/family.ged new file mode 100644 index 0000000..608902c --- /dev/null +++ b/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 diff --git a/docker/examples/photos/photos/I1.jpg b/docker/examples/photos/photos/I1.jpg new file mode 100644 index 0000000..e759458 Binary files /dev/null and b/docker/examples/photos/photos/I1.jpg differ diff --git a/docker/examples/photos/photos/I2.jpg b/docker/examples/photos/photos/I2.jpg new file mode 100644 index 0000000..4abddd2 Binary files /dev/null and b/docker/examples/photos/photos/I2.jpg differ diff --git a/docker/examples/simple/Dockerfile b/docker/examples/simple/Dockerfile new file mode 100644 index 0000000..84da28f --- /dev/null +++ b/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 diff --git a/docker/examples/simple/README.md b/docker/examples/simple/README.md new file mode 100644 index 0000000..6557164 --- /dev/null +++ b/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 + ``` diff --git a/docker/examples/simple/family.ged b/docker/examples/simple/family.ged new file mode 100644 index 0000000..0397e57 --- /dev/null +++ b/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