FoundryVTT + Cloudflare Tunnel Docker Stack

A Docker Compose stack for running Foundry Virtual Tabletop with Cloudflare Tunnel for secure external access without port forwarding.

Features

• 🎲 Foundry VTT - Pinned to version 13.348.0
• 🔒 Cloudflare Tunnel - Secure access without opening ports
• 📦 Docker Compose - Easy deployment and management
• ⚙️ Environment-based config - All settings via .env file
• 🔄 Persistent data - Foundry data stored in ./data volume

Prerequisites

• Docker and Docker Compose
• Cloudflare account (free tier works)
• Foundry VTT license

Quick Start

1. Clone and Configure

git clone https://github.com/zdaar/foundryvtt-cloudflared-docker.git
cd foundryvtt-cloudflared-docker
cp .env.example .env

2. Configure Environment

Edit .env and set required variables:

# Required
FOUNDRY_USERNAME=your_foundryvtt_username
FOUNDRY_PASSWORD=your_foundryvtt_password
FOUNDRY_ADMIN_KEY=your_admin_password
FOUNDRY_LICENSE_KEY=AAAA-BBBB-CCCC-DDDD-EEEE-FFFF
TUNNEL_TOKEN=your_cloudflare_tunnel_token

# Optional (defaults provided)
FOUNDRY_HOSTNAME=foundry.example.com
TZ=UTC

3. Create Cloudflare Tunnel

1. Go to Cloudflare Zero Trust Dashboard
2. Navigate to Networks → Tunnels
3. Click Create a tunnel
4. Choose Cloudflared connector
5. Name your tunnel (e.g., "foundryvtt")
6. Select Docker and copy the token from the command
7. Paste the token into your .env file as TUNNEL_TOKEN

4. Configure Public Hostname

In the Cloudflare Tunnel dashboard:

1. Go to Public Hostname tab
2. Click Add a public hostname
3. Configure:
   • Subdomain: foundry (or your choice)
   • Domain: Select your domain
   • Service Type: HTTP
   • URL: foundryvtt:30000
4. Save

5. Launch Stack

docker compose up -d

6. Access Foundry

Visit your configured hostname (e.g., https://foundry.example.com)

Configuration

Environment Variables

See .env.example for all available options. Key variables:

Variable	Description	Default
FOUNDRY_USERNAME	FoundryVTT account username	required
FOUNDRY_PASSWORD	FoundryVTT account password	required
FOUNDRY_ADMIN_KEY	Admin access password	required
FOUNDRY_LICENSE_KEY	License key (optional if using account auth)	-
FOUNDRY_HOSTNAME	Public hostname for invitation links	-
FOUNDRY_COMPRESS_WEBSOCKET	Enable websocket compression	true
FOUNDRY_MINIFY_STATIC_FILES	Minify JS/CSS files	true
FOUNDRY_TELEMETRY	Enable Foundry telemetry	false
TUNNEL_TOKEN	Cloudflare tunnel token	required
TZ	Timezone (TZ database name)	UTC

For complete list of options, see the felddy/foundryvtt documentation.

Using Custom Domain

If you own the domain but the tunnel is in a different Cloudflare account:

1. Create a CNAME record in your DNS:

   foundry.yourdomain.com  CNAME  <tunnel-id>.cfargotunnel.com
   

2. The tunnel ID can be found in the tunnel dashboard or container logs
3. Configure the public hostname route in the tunnel dashboard

Data Persistence

Foundry data is stored in ./data directory. This includes:

• Worlds
• Systems
• Modules
• User uploads

Back up this directory regularly!

Updating

Update Foundry VTT

Edit compose.yml and change the image tag:

foundryvtt:
  image: felddy/foundryvtt:release-13.348.0  # Change version here

Then:

docker compose pull
docker compose up -d

Update Cloudflare Tunnel

Edit compose.yml and change the cloudflared image tag, then pull and restart:

docker compose pull cloudflared
docker compose up -d cloudflared

Troubleshooting

Check Logs

# All services
docker compose logs -f

# Foundry only
docker compose logs -f foundryvtt

# Cloudflare Tunnel only
docker compose logs -f cloudflared

Tunnel Not Connecting

• Verify TUNNEL_TOKEN is correct
• Check tunnel status in Cloudflare dashboard
• Ensure Docker container has internet access

Foundry Not Downloading

• Verify FOUNDRY_USERNAME and FOUNDRY_PASSWORD are correct
• Check if license is valid and not already in use
• Review logs for authentication errors

Can't Access via Domain

• Verify public hostname is configured in tunnel dashboard
• Check DNS propagation (if using CNAME)
• Ensure service URL is foundryvtt:30000 (not localhost)

Security Notes

• Never commit .env file to git (already in .gitignore)
• Use strong passwords for FOUNDRY_ADMIN_KEY
• Cloudflare Tunnel provides automatic HTTPS encryption
• No ports need to be exposed on your host machine

License

This repository contains configuration files only. See respective projects for licensing:

• Foundry VTT - Proprietary (license required)
• felddy/foundryvtt-docker - CC0 1.0
• Cloudflare Tunnel - Apache 2.0

Credits

• Foundry Gaming LLC - Foundry Virtual Tabletop
• felddy - Docker image for Foundry VTT
• Cloudflare - Cloudflare Tunnel

Contributing

Issues and pull requests welcome!