FoundryVTT Container

A containerized FoundryVTT Virtual Tabletop built on Red Hat UBI10 Minimal.

Features

• Red Hat UBI10 Minimal base image
• Runs as non-root user for security
• OCI-compliant image labels
• Automated CI/CD builds

Quick Start

Pull the latest image:

podman pull registry.belway.me/public/foundryvtt:latest

Run with persistent data:

podman run -d \
  --name foundryvtt \
  -p 30000:30000 \
  -v /path/to/data:/foundryvtt/data:Z \
  --hostname $(hostname) \
  registry.belway.me/public/foundryvtt:latest

Note: Set --hostname to your server's hostname to avoid re-accepting the license on each restart.

Building the Container

Prerequisites

• A valid FoundryVTT license
• The timed download URL from your FoundryVTT account (Purchased Licenses → Linux/NodeJS)

Manual Build

./build.sh -U "$FOUNDRY_URL" -I -v "$VERSION"

CI/CD

The repository includes a Gitea Actions workflow that automatically builds when:

• Changes are pushed to main branch
• Manually triggered via workflow dispatch

Required secrets:

• FOUNDRY_URL - Timed download URL from FoundryVTT
• BELWAY_REGISTRY_USER / BELWAY_REGISTRY_TOKEN - Registry credentials

Running with Quadlets (Recommended)

Create a quadlet file at ~/.config/containers/systemd/foundryvtt.container:

[Unit]
Description=FoundryVTT Virtual Tabletop
After=network-online.target

[Container]
AutoUpdate=registry
Image=registry.belway.me/public/foundryvtt:latest
HostName=your-server-hostname
PublishPort=30000:30000
Timezone=America/Montreal
Volume=/path/to/your/data:/foundryvtt/data:Z

# Healthcheck at runtime (OCI images don't include healthcheck)
HealthCmd=curl -f http://localhost:30000 || exit 1
HealthInterval=30s
HealthTimeout=10s
HealthStartPeriod=60s
HealthRetries=3

[Service]
Restart=always

[Install]
WantedBy=multi-user.target default.target

Then start the service:

systemctl --user daemon-reload
systemctl --user start foundryvtt
systemctl --user enable foundryvtt

Healthcheck Options

Since OCI-compliant images don't include healthchecks, add them at runtime:

With podman run:

podman run -d \
  --name foundryvtt \
  --health-cmd="curl -f http://localhost:30000 || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-start-period=60s \
  -p 30000:30000 \
  -v /path/to/data:/foundryvtt/data:Z \
  registry.belway.me/public/foundryvtt:latest

With Quadlet:

Add to [Container] section:

HealthCmd=curl -f http://localhost:30000 || exit 1
HealthInterval=30s
HealthTimeout=10s
HealthStartPeriod=60s

Volume Mounts

Container Path	Purpose
/foundryvtt/data	Persistent data (worlds, systems, modules)

Ports

Port	Protocol	Purpose
30000	TCP	Web interface

Environment Variables

FoundryVTT supports various command-line options that can be passed as arguments. See the official documentation for details.

License

See LICENSE file.