forked/topola-viewer
1
0
Fork 0
mirror of https://github.com/PeWu/topola-viewer.git synced 2026-05-26 15:16:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Dockerfile and automation to build and publish a docker image

Browse Source
This commit is contained in:
Przemek Więch
2026-05-06 00:02:53 +02:00
parent fdc0f50a97
commit 40df8112bd
9 changed files with 609 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.dockerignore Normal file
View File

@@ -0,0 +1,7 @@
node_modules
dist
.git
.github
cypress
.vscode
README.md

51
.github/workflows/deploy-docker.yml vendored Normal file
View File

@@ -0,0 +1,51 @@
name: Build and Publish Docker Image
on:
workflow_dispatch:
workflow_call:
jobs:
build-and-push:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Convert Repository Name to Lowercase
run: |
echo "GHCR_IMAGE_NAME=$(echo "ghcr.io/${{ github.repository }}" | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.GHCR_IMAGE_NAME }}
tags: |
type=sha
type=raw,value=latest,enable=${{ github.ref == 'refs/heads/master' }}
- name: Build and push Docker image
uses: docker/build-push-action@v6
with:
context: .
file: docker/Dockerfile
platforms: linux/amd64
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max

4
.github/workflows/deploy-everywhere.yml vendored
View File

@@ -9,3 +9,7 @@ jobs:
deploy-wikitree-apps:
uses: ./.github/workflows/deploy-wikitree-apps.yml
secrets: inherit
deploy-docker:
uses: ./.github/workflows/deploy-docker.yml
secrets: inherit

41
docker/Caddyfile Normal file
View File

@@ -0,0 +1,41 @@
{
# Disable administrative API to prevent permission errors in read-only environments
admin off
}
:8080 {
root * /app/public
# Compress static assets (HTML, JS, CSS, GEDCOM text files)
encode gzip zstd
file_server
# Robust Security Headers
header {
X-Frame-Options "SAMEORIGIN"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
Permissions-Policy "geolocation=(), microphone=(), camera=()"
}
# Cache Control: Long-lived cache ONLY for immutable hashed build assets
@immutable_assets {
path /assets/*
}
header @immutable_assets Cache-Control "public, max-age=31536000, immutable"
# Cache Control: Immediate revalidation for all mutable assets (HTML, mounted dynamic family trees/photos)
@mutable_assets {
not {
path /assets/*
}
}
header @mutable_assets Cache-Control "public, max-age=0, must-revalidate"
templates {
mime text/html
}
try_files {path} /index.html
}

24
docker/Dockerfile Normal file
View File

@@ -0,0 +1,24 @@
# Stage 1: Compile the React/TypeScript bundle
FROM node:20-alpine AS react-builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Stage 2: Package static assets & Caddy binary on Distroless Static
FROM gcr.io/distroless/static-debian12
USER nonroot:nonroot
WORKDIR /app
# Copy static Caddy binary from the official Caddy image
COPY --from=caddy:2.7.6-alpine /usr/bin/caddy /usr/bin/caddy
# Copy Caddy server config with nonroot ownership
COPY --chown=nonroot:nonroot docker/Caddyfile ./
# Copy React build outputs with nonroot ownership to support strict read-only filesystem deployments
COPY --chown=nonroot:nonroot --from=react-builder /app/dist ./public
EXPOSE 8080
ENTRYPOINT ["/usr/bin/caddy", "run", "--config", "./Caddyfile", "--adapter", "caddyfile"]

447
docs/DOCKER_DESIGN.md Normal file
View File

@@ -0,0 +1,447 @@
# Topola Viewer: Docker Packaging & Deployment Design
## 1. Problem Description
Topola Viewer is a modern, client-side web application designed for exploring and visualizing genealogy data from GEDCOM files. Currently, running a custom instance with a pre-loaded family tree and photos requires manual local development builds or setting up complex web hosting environments. This project aims to package Topola Viewer inside an ultra-lightweight, secure, and production-ready Docker container. This container will allow users to instantly deploy a vanilla viewer or easily serve their own private, self-contained family trees with zero local compilation or build-tool dependencies.
## 2. Major Components & How They Interact
At a high level, the containerized Topola Viewer consists of three primary components working together to serve and display family trees:
1. **The User's Web Browser (The App)**: This is where Topola Viewer actually runs. Since it is a single-page React application, the browser downloads the application files once and executes all the logic, chart rendering, and user interactions locally on the user's computer.
2. **The Caddy Web Server (The Helper)**: This is a lightweight, secure, and fast background server running inside the Docker container. Its job is to serve the application files (HTML, CSS, JavaScript) and the family tree package when the browser requests them. Additionally, Caddy dynamically updates the main HTML page on-the-fly when it is loaded, injecting the path or address of the family tree file specified by the container's configuration.
3. **The Genealogy Data (The Data)**: This is the family tree description file. Depending on whether you have local photo assets:
* **Unzipped File (`.ged`)**: If you do not have local photos, you can serve your standard, plain-text `.ged` file directly.
* **Zipped Archive (`.gdz` or `.zip`)**: If you want to bundle family photos, you compress the `.ged` file and the photos together into a single archive. Topola Viewer will automatically unzip and map the photos to the tree.
Serving this as a single file (either `.ged` or `.gdz`) keeps the container setup simple and highly portable.
## 3. Alternative Designs Considered & Rejected
To ensure future development does not regress or re-argue established choices, this section documents the architectural patterns that were thoroughly evaluated but ultimately rejected.
### Option A: Build-Time Variable Injection (`VITE_STATIC_URL`)
* **Design Proposal**: Build custom container images by setting `VITE_STATIC_URL` during the Vite production build step (`npm run build`) inside the Dockerfile.
* **Why Rejected**:
* **Heavy & Slow Builds**: Recompiling a modern React SPA inside Docker requires a full Node.js runtime, downloading `node_modules`, and compiling TypeScript. This takes minutes, consumes significant system resources, and makes building a custom image locally a highly friction-filled developer experience.
* **No Runtime Dynamism**: Since the static URL is hardcoded into minified JS assets during compiling, users cannot change their genealogy file path dynamically when running the container. A simple task like pointing the container to a new GEDCOM file would require a full image rebuild, rather than a simple environment variable or volume mount adjustment.
### Option B: Client-Side Config Fetching (`fetch('/config.json')`)
* **Design Proposal**: At React application startup, trigger an asynchronous HTTP request (`fetch('/config.json')`) to retrieve the configuration and target tree location.
* **Why Rejected**:
* **Unnecessary Startup Latency**: Every asynchronous network call in a client-side SPA blocks the React application mount lifecycle. Even on high-performance servers, fetching `/config.json` introduces an extra network roundtrip at boot time.
### Option C: Shell-Based Template Rendering (Nginx Alpine + `envsubst`)
* **Design Proposal**: Run the static application on an Nginx Alpine base container, using a startup shell script and the `envsubst` tool to substitute environment variables inside `index.html` before launching the web server.
* **Why Rejected**:
* **Vulnerability Attack Surface**: Standard Linux and Alpine base images contain shell environments (`/bin/sh`), package managers (`apk`), and standard operating system utilities. These represent a non-zero container attack surface, leading to vulnerability alerts (CVEs) in enterprise environments.
### Option D: Custom Compiled Go Static Server
* **Design Proposal**: Compile a custom, lightweight 35-line Go static web server program that handles SPA routing and dynamically injects environment variables directly into the `index.html` served from memory.
* **Why Rejected**:
* **Maintenance Complexity Overhead**: Although highly performant and lightweight (~10MB total container size), introducing custom compiled server source code adds to repository maintenance. Developers would have to test, audit, and maintain custom Go HTTP routing logic alongside their main React/TypeScript codebase. Using an off-the-shelf server (Caddy) eliminates this maintenance entirely.
### Option E: Multi-Architecture Image Support (`linux/arm64`)
* **Design Proposal**: Package and publish multi-architecture container images targeting both standard x86_64 (`linux/amd64`) and ARM64 (`linux/arm64`) platforms.
* **Why Rejected**:
* **Pipeline Emulation Latency**: Building multi-architecture images on standard AMD64 GitHub Actions runners requires virtualized instruction emulation via QEMU. Emulating the TypeScript build and Go compiler inside a QEMU virtual environment increases container compilation cycles by up to 10x to 20x, significantly bloating release delays.
* **No Server-Side Execution Penalty**: Topola Viewer is a pure, client-side React single-page application (SPA). The browser executes all chart rendering and data logic on the end-user's computer (whether it runs on x86_64, ARM64/Apple Silicon, or mobile platforms). The container's internal web server (Caddy) simply serves static HTML/JS assets. Running the `linux/amd64` image under standard Docker architecture translation (e.g., Rosetta 2 or Docker Desktop VM) on ARM64/M-series hosts has absolutely zero visible performance penalty.
* **Workflow Stability**: Focusing exclusively on `linux/amd64` standardizes our GitHub Actions runner steps, completely removes complex third-party dependencies like `setup-qemu-action`, and ensures build cycles remain blazingly fast, secure, and reliable.
## 4. Detailed Implementation Plan
This section outlines the complete, step-by-step implementation plan. It lists every file that will be modified or created, the exact code modifications or configurations required, and the explicit engineering rationale for each.
### Step 1: Add Global Config Injection Target to HTML
* **Target File**: [index.html](../index.html) (Modify)
* **Action**: Add a `<meta>` tag containing the dynamic injection placeholder inside the `<head>` tag:
```html
<meta name="topola-static-url" content="{{ env `STATIC_URL` | html }}">
```
* **Rationale**:
* Storing the configuration safely inside a `<meta>` tag content attribute ensures it is parsed strictly as data rather than executable code, preventing Reflected Cross-Site Scripting (XSS) or script injection vulnerabilities.
* **HTML Parsing Protection**: Enclosing the template expression in backticks (`` `STATIC_URL` ``) prevents syntactically broken nested double quotes in the HTML `content` attribute, which would otherwise break standard browser HTML tag parsing.
* The Caddy `| html` filter guarantees that the environment variable is fully HTML-entity-escaped before injection.
* The placeholder syntax `{{ env `STATIC_URL` | html }}` is evaluated dynamically by Caddy when serving the page, adding zero network latency.
### Step 2: Update Application Boot Logic to Handle Global Config
* **Target File**: [src/app.tsx](../src/app.tsx) (Modify)
* **Action**: Update the application boot logic to handle dynamic config via the `<meta>` tag or Vite static URL, override standalone/CORS properties, and adjust route settings:
* **Config Resolution**: Retrieve the statically-served GEDCOM/GDZ URL.
* **Arguments Setup**: Disable standalone mode and bypass CORS handling when a static URL is provided.
* **Conditional Routing**: Force routing directly to `/view` (bypassing the standard intro landing page) when `staticUrl` is set.
```typescript
// 1. Global Config Resolution
function getStaticUrl(): string | undefined {
const envUrl = import.meta.env.VITE_STATIC_URL;
if (envUrl) return envUrl;
const metaTag = document.querySelector('meta[name="topola-static-url"]');
const metaUrl = metaTag?.getAttribute('content');
// Safely ignore if it is empty, the raw caddy template expression, or Vite's raw template placeholder
if (
metaUrl &&
!metaUrl.startsWith("__") &&
!metaUrl.includes("{{ env")
) {
return metaUrl;
}
return undefined;
}
const staticUrl = getStaticUrl();
// 2. Arguments and Source Spec Override
if (staticUrl) {
sourceSpec = {
source: DataSourceEnum.GEDCOM_URL,
url: staticUrl,
handleCors: false,
};
}
...
standalone: getParam('standalone') !== 'false' && !embedded && !staticUrl,
// 3. Conditional Routing in JSX Return
{staticUrl ? (
<Routes>
<Route path="/view" element={renderMainArea()} />
<Route path="*" element={<Navigate to="/view" replace />} />
</Routes>
) : (
<Routes>
<Route path="/" element={<Intro />} />
<Route path="/view" element={renderMainArea()} />
<Route path="*" element={<Navigate to="/" replace />} />
</Routes>
)}
```
* **Rationale**:
* **Security & Safety**: Retrieving configuration via the DOM's `<meta>` element ensures we parse data context safely rather than relying on direct executable script template injection.
* **UX Modularity (Zero-Friction Mode)**: Bypassing the Intro page and disabling the standard "open file" menus (`standalone: false`) transforms the general-purpose viewer into a streamlined, dedicated instance for the preloaded tree.
* **Backward Compatibility**: Keeps standard dev runs (`npm start`) and static deployments (GitHub Pages/WikiTree) working out-of-the-box because the template string `{{ env "STATIC_URL" }}` is safely ignored when it hasn't been evaluated by Caddy.
### Step 3: Create Caddy Server Configuration
* **Target File**: `docker/Caddyfile` (New File in dedicated directory)
* **Action**: Add Caddy serving rules to handle robust security headers, optimized caching, SPA routing, and active template evaluation:
```caddy
{
# Disable administrative API to prevent permission errors in read-only environments
admin off
}
:8080 {
root * /app/public
# Compress static assets (HTML, JS, CSS, GEDCOM text files)
encode gzip zstd
file_server
# Robust Security Headers
header {
X-Frame-Options "SAMEORIGIN"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
Permissions-Policy "geolocation=(), microphone=(), camera=()"
}
# Cache Control: Long-lived cache ONLY for immutable hashed build assets
@immutable_assets {
path /assets/*
}
header @immutable_assets Cache-Control "public, max-age=31536000, immutable"
# Cache Control: Immediate revalidation for all mutable assets (HTML, mounted dynamic family trees/photos)
@mutable_assets {
not {
path /assets/*
}
}
header @mutable_assets Cache-Control "public, max-age=0, must-revalidate"
templates {
mime text/html
}
try_files {path} /index.html
}
```
* **Rationale**:
* **Security Headers**: Protects production deployments against clickjacking, MIME-sniffing, and referrer leaks through standard secure response headers.
* **Disable Admin Endpoint**: Setting `admin off` prevents Caddy from attempting to bind administrative sockets or write auto-saved configuration files (`caddy_autosave.json`) to its working directory, avoiding fatal startup failures in rootless containers and secure read-only filesystems.
* **Asset Compression**: Adding `encode gzip zstd` ensures that large client-side JS bundles and plain-text GEDCOM files are compressed, dramatically reducing load-time latency and server bandwidth costs.
* **Precise Caching Rules**: Restructures caching to only apply `immutable` tags to assets in `/assets/*` (which contains Vite's hashed JS/CSS files). This ensures user-supplied dynamic family trees (`.ged`, `.gdz`) and mounted photos do not get cached permanently, allowing instant runtime updates.
* **HTML Templating**: Caddy dynamically processes variables (like `{{ env `STATIC_URL` | html }}`) for HTML documents, avoiding performance overhead on other resources.
* **Non-Root Port**: Serving from port `8080` permits the container to run as an unprivileged user without root capabilities.
---
### Step 4: Create Multi-Stage Dockerfile
* **Target File**: `docker/Dockerfile` (New File in dedicated directory)
* **Action**: Write the multi-stage compilation and assembly pipeline using a pre-compiled Caddy binary and Google's library-free Distroless Static base image running as nonroot:
```dockerfile
# Stage 1: Compile the React/TypeScript bundle
FROM node:20-alpine AS react-builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Stage 2: Package static assets & Caddy binary on Distroless Static
FROM gcr.io/distroless/static-debian12
USER nonroot:nonroot
WORKDIR /app
# Copy static Caddy binary from the official Caddy image
COPY --from=caddy:2.7.6-alpine /usr/bin/caddy /usr/bin/caddy
# Copy Caddy server config with nonroot ownership
COPY --chown=nonroot:nonroot docker/Caddyfile ./
# Copy React build outputs with nonroot ownership to support strict read-only filesystem deployments
COPY --chown=nonroot:nonroot --from=react-builder /app/dist ./public
EXPOSE 8080
ENTRYPOINT ["/usr/bin/caddy", "run", "--config", "./Caddyfile", "--adapter", "caddyfile"]
```
* **Rationale**:
* **Clean Compilation Separation**: Restructures compilation using a multi-stage build where the heavy Node.js and TypeScript compiler packages are restricted entirely to the builder stage, keeping the final runner image extremely lightweight and free of development tools.
* **Static Caddy Binary**: Copying the pre-compiled, statically linked Caddy binary directly from the official `caddy` Alpine image. Since the official Caddy binary is a pure, library-independent Go executable built without CGO, it runs flawlessly on top of a Google Distroless Static image, completely bypassing the need to compile Caddy from source and reducing build times by several minutes.
* **Distroless Static Base**: Standardizing on `distroless/static-debian12` removes *all* dynamic libraries, shells, and packages from the runtime container. This cuts container image size to under ~25MB and eliminates runtime vulnerability scan alerts (CVEs) completely.
* **Non-Root Execution**: Switching to `USER nonroot:nonroot` inside the production stage ensures the application runs with minimum privileges, satisfying strict enterprise and Kubernetes execution policies.
* **Explicit File Ownership**: Using `COPY --chown=nonroot:nonroot` guarantees that all files in the runtime container are owned by the runtime non-root user, bypassing permissions conflicts.
### Step 5: Create Docker Ignore File
* **Target File**: `.dockerignore` (New File at root)
* **Action**: Exclude local development folders and build environments from entering the Docker context:
```text
node_modules
dist
.git
.github
cypress
.vscode
README.md
```
* **Rationale**:
* Speeds up local `docker build` times by preventing megabytes of local folders (like `node_modules` and local `dist` directories) from uploading to the Docker daemon build context.
### Step 6: Create GitHub Actions Container Deployment Workflow
* **Target File**: `.github/workflows/deploy-docker.yml` (New File)
* **Action**: Setup a GitHub Actions workflow to compile, tag, and publish the container images to GHCR, handling lowercase names and safe tagging:
```yaml
name: Build and Publish Docker Image
on:
workflow_dispatch:
workflow_call:
jobs:
build-and-push:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Convert Repository Name to Lowercase
run: |
echo "GHCR_IMAGE_NAME=$(echo "ghcr.io/${{ github.repository }}" | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.GHCR_IMAGE_NAME }}
tags: |
type=sha
type=raw,value=latest,enable=${{ github.ref == 'refs/heads/master' }}
- name: Build and push Docker image
uses: docker/build-push-action@v6
with:
context: .
file: docker/Dockerfile
platforms: linux/amd64
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
```
* **Rationale**:
* **Strict Lowercase Registry Names**: Registry image names must be strictly lowercase. Converting the repository path to lowercase prevents Docker push failures due to uppercase organization or repository names (e.g. `PeWu`).
* **Safe Production Tagging**: Restricts pushing the `latest` tag to master branch runs only, preventing development branches or forks from accidentally overwriting the stable master production image.
* **No QEMU Dependency**: Because the image targets standard `linux/amd64` servers directly, we bypass slow CPU instruction emulation completely. This eliminates the `setup-qemu-action` dependency, protecting the workflow against virtualizer crashes and speeding up build initialization.
* **Git SHA Tagging**: Generates git SHA tags automatically, allowing precise auditing and rolling back of deployments.
* **Modern Actions Standard**: Upgrades all critical deployment actions to their latest major releases to optimize runner speeds, secure security improvements, and align with Node 20/22 GitHub Action standard runner specifications.
* **Active GitHub Caching**: Leverages standard action build cache stores to reuse layers and accelerate build cycles.
### Step 7: Couple Docker Publication to existing Main Deployment Pipeline
* **Target File**: [.github/workflows/deploy-everywhere.yml](deploy-everywhere.yml) (Modify)
* **Action**: Integrate the newly created Docker workflow as a concurrent job:
```yaml
name: Deploy everywhere
on: workflow_dispatch
jobs:
deploy-gh-pages:
uses: ./.github/workflows/deploy-gh-pages.yml
deploy-wikitree-apps:
uses: ./.github/workflows/deploy-wikitree-apps.yml
secrets: inherit
deploy-docker:
uses: ./.github/workflows/deploy-docker.yml
secrets: inherit
```
* **Rationale**:
* Integrates the container deployment pipeline seamlessly into the main release trigger (`deploy-everywhere`), ensuring that Docker, GH Pages, and WikiTree versions are always updated in lockstep.
### Step 8: Document Container Usage in Main README
* **Target File**: `README.md` (Modify)
* **Action**: Add a dedicated "Docker Container Deployment" section with clear run, build, mount, and standalone template instructions:
```markdown
## 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.
```
* **Rationale**:
* Ensures the new Docker feature has first-class visibility, clear instructions, and easy references to packaged standalone templates for end users, enabling both basic runs, volume-mounted local data serving, and built-in custom imagery.
### Step 9: Provide Custom Image Templates (Simple & Zipped on the Fly)
* **Target Files**:
* `docker/examples/simple/Dockerfile` (New File)
* `docker/examples/simple/README.md` (New File)
* `docker/examples/simple/family.ged` (New simple, valid example GEDCOM file)
* `docker/examples/photos/Dockerfile` (New File)
* `docker/examples/photos/README.md` (New File)
* `docker/examples/photos/family.ged` (New simple, valid example GEDCOM file)
* `docker/examples/photos/photos/I1.jpg` (New simple, valid example photo asset)
* `docker/examples/photos/photos/I2.jpg` (New simple, valid example photo asset)
* **Action**: Create two dedicated subdirectories containing turnkey templates. To make these examples instantly runnable out-of-the-box, we provide simple, valid example files (`family.ged`, `I1.jpg`, and `I2.jpg`) inside the repository so users can immediately run `docker build` and test the container features without having to prepare their own private files first.
#### 1. Simple GEDCOM Template (`docker/examples/simple`)
* **`docker/examples/simple/Dockerfile`**:
```dockerfile
# 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`**:
```markdown
# 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
```
```
#### 2. Zipped Media Template (`docker/examples/photos`)
* **`docker/examples/photos/Dockerfile`**:
```dockerfile
# 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`**:
```markdown
# 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
```
```
* **Rationale**:
* **Simple Template**: Demonstrates the standard, zero-friction path for users who just have a raw `.ged` file.
* **Photos Template (On-The-Fly Zipper)**: Solves the problem of executing commands in a shell-less, commandless distroless container. By spinning up a lightweight Alpine zipper image to execute the native `zip` tool, and copying *only* the finished `.gdz` artifact into the final stage, we achieve a completely self-contained, secure target image.
* **Preserved Path Zip File Structure**: Packaging photos by zipping from the build root (`zip -r family.gdz family.ged photos/`) preserves the exact folder hierarchy relative to the GEDCOM. This guarantees that any complex or structured media folders (e.g., `photos/1990s/wedding.jpg`) match the exact file references declared inside the GEDCOM file, avoiding broken images from flattened zip scopes.

12
docs/README.md Normal file
View File

@@ -0,0 +1,12 @@
# Topola Viewer Feature Designs
This directory contains technical design documents for some of the new features and architectural updates of the Topola Viewer.
These documents are inspired by the design methodology described in the blog post [Elephants, Goldfish and the New Golden Age of Software Engineering](https://drensin.medium.com/elephants-goldfish-and-the-new-golden-age-of-software-engineering-c33641a48874) by Dave Rensin.
While new features *may* follow this methodology to ensure robust design validation and context safety before writing code, doing so is optional.
## Design Documents Registry
* **[DOCKER_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/DOCKER_DESIGN.md)**: Docker container packaging, lightweight Caddy web server configuration, and GitHub Actions publishing pipelines.
* **[WEBMCP_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/WEBMCP_DESIGN.md)**: Model Context Protocol (MCP) bridge and TS tool registration for AI agent interaction.

1
index.html
View File

@@ -12,6 +12,7 @@
<!-- GOOGLE_ANALYTICS_END -->
<meta charset="utf-8">
<meta name="viewport" content="minimum-scale=1, initial-scale=1, width=device-width, shrink-to-fit=no">
<meta name="topola-static-url" content="{{ env `STATIC_URL` | html }}">
<link rel="icon" href="favicon.png" type="image/png"/>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

25
src/app.tsx
View File

@@ -52,12 +52,31 @@ import {idToIndiMap, TopolaData} from './util/gedcom_util';
import {WebMcpBridge} from './webmcp';
/**
* Load GEDCOM URL from VITE_STATIC_URL environment variable.
* Load GEDCOM URL from environment variable (Vite VITE_STATIC_URL or dynamically
* injected via a meta tag from Caddy server).
*
* If this environment variable is provided, the viewer is switched to
* If this static URL is provided, the viewer is switched to
* single-tree mode without the option to load other data.
*/
const staticUrl = import.meta.env.VITE_STATIC_URL;
function getStaticUrl(): string | undefined {
const envUrl = import.meta.env.VITE_STATIC_URL;
if (envUrl) return envUrl;
const metaTag = document.querySelector('meta[name="topola-static-url"]');
const metaUrl = metaTag?.getAttribute('content');
// Safely ignore if it is empty, the raw caddy template expression, or Vite's raw template placeholder
if (
metaUrl &&
!metaUrl.startsWith("__") &&
!metaUrl.includes("{{ env")
) {
return metaUrl;
}
return undefined;
}
const staticUrl = getStaticUrl();
/** Shows an error message in the middle of the screen. */
function ErrorMessage(props: {message?: string}) {