133 lines
3.1 KiB
Markdown
133 lines
3.1 KiB
Markdown
# 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:
|
|
```bash
|
|
podman pull registry.belway.me/public/foundryvtt:latest
|
|
```
|
|
|
|
Run with persistent data:
|
|
```bash
|
|
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
|
|
```bash
|
|
./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`:
|
|
|
|
```ini
|
|
[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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```ini
|
|
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](https://foundryvtt.com/article/configuration/) for details.
|
|
|
|
## License
|
|
|
|
See [LICENSE](LICENSE) file.
|