Portainer Templates logo

Portainer Templates

FoundryVTT Server FoundryVTT Server

Container

OtherGames

This docker image provides the FoundryVTT system for hosting your own virtual table top games.

Image details

Pulls: 31.0M
Architecture: amd64, arm64, arm/v7, ppc64le, s390x
Image size: 115 MB
Latest: 14.370
User: felddy
Created: Jun 03, 2020
Updated: 12 days ago
Status: active

Configuration

Type
Container
Platform
linux
Image
felddy/foundryvtt:release
Ports
30000:30000/tcp
Volumes
/data : /portainer/Files/AppData/Config/foundryvtt
Env vars
FOUNDRY_USERNAME=JohnFOUNDRY_PASSWORD=passwordFOUNDRY_ADMIN_KEY=changemeCONTAINER_PRESERVE_CONFIG=true
Restart
unless-stopped

Notes

Template created by Pi-Hosted Series
Check our Github page: https://github.com/pi-hosted/pi-hosted

Official Webpage: https://foundryvtt.com/
Official Docker Documentation: https://hub.docker.com/r/felddy/foundryvtt


Standalone Install

Select an install method, to see config/commands for deploying FoundryVTT Server

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select FoundryVTT Server, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo

More install options in our documentation.


Docker whale logo carrying the FoundryVTT icosahedron logo while floating
  in water.

foundryvtt-docker #

Build CodeQL OpenSSF Scorecard CII Best Practices SLSA 3
FoundryVTT Release Version: v14.370 Platforms
You can get a Foundry Virtual Tabletop instance up and running in minutes using this container. This image is designed to be secure, reliable, compact, and simple to use. It only requires that you provide the credentials or URL needed to download a Foundry Virtual Tabletop distribution.
This README is the reference for the image itself — its tags, volumes, ports, environment variables, and secrets. For step-by-step setups on a particular platform, see the deployment guides.

Prerequisites ##

  • An OCI-compatible container runtime such as Kubernetes,
Podman, or Docker. software license.

Quick start ##

The fastest way to see the server running is a single command. Your foundryvtt.com credentials let the container install and license your server:
docker run \
  --env FOUNDRY_USERNAME='<your_username>' \
  --env FOUNDRY_PASSWORD='<your_password>' \
  --hostname my_foundry_host \
  --publish 30000:30000/tcp \
  --volume <your_data_dir>:/data \
  ghcr.io/felddy/foundryvtt:14

Then open http://localhost:30000.
!TIP Don't want to share your password with the container? Acquire a temporary download URL from the Purchased Software Licenses page (set Operating System to Node.js, then use the 🔗 Timed URL button) and pass it as FOUNDRY_RELEASE_URL instead of your username and password. Sensitive values can also be supplied as secrets.

This is enough to try things out. For a durable, real-world deployment, pick a deployment guide below.

Configuration ##

Configuration options are supplied through environment variables. Each time the container starts, it generates the configuration files Foundry needs from the values of those variables. This means changes made in the in-application configuration GUI do not persist between container restarts. Manage configuration through your runtime's environment settings — a compose.yaml file, a Kubernetes manifest, or similar. To disable the regeneration of these files, set CONTAINER_PRESERVE_CONFIG to true.
!IMPORTANT Always set a stable hostname for the container (hostname: in a compose.yaml file, --hostname for docker/podman, or hostname: in a pod spec). Foundry binds its software license to the container hostname. If no hostname is set, the runtime assigns a random container ID on each start, causing license verification to fail after every restart.

Using secrets ##

Sensitive values — your credentials, admin key, or license key — can be supplied through a secret file instead of environment variables. The file may have any name, but it must be presented to the container as config.json. See the secrets reference below for the full list of supported keys, and the deployment guides for how to wire up a secret on your runtime.

Deployment guides ##

The deployment guides cover each runtime in depth and include worked networking examples. The image is the same everywhere; these guides show how to run it well on a given platform.
GuideDescription
KubernetesCluster deployment, including running multiple Foundry instances.
PodmanDaemonless and rootless, optionally managed by systemd.
Docker ComposeSingle-host setup with the image, configuration, storage, and ports in one file.
Reverse proxy with CaddyAutomatic HTTPS in front of the server.
Reverse proxy with nginxTLS termination with certificates you already have.
Cloudflare TunnelPublic access without port forwarding or NAT.

Updating ##

The Foundry "Update Software" tab is disabled by default in this container. To upgrade to a new version of Foundry, pull an updated image and recreate the container. Because the recommended :14 tag tracks the latest release for that major version, pulling it fetches the newest version compatible with your data. Your deployment guide lists the exact commands for your runtime.

Image tags ##

The images of this container are tagged with semantic versions that align with the version and build of Foundry Virtual Tabletop that they support.
!TIP It is recommended that users use the major version tag: :14 Using the major tag will ensure that you receive the most recent version of the software that is compatible with your saved data, and prevents inadvertent upgrades to a new major version.

Image:tagDescription
ghcr.io/felddy/foundryvtt:14The most recent image matching the major version number. Most users will use this tag.
ghcr.io/felddy/foundryvtt:14.370The most recent image matching the major and minor version numbers.
ghcr.io/felddy/foundryvtt:14.370.0An exact image version.
ghcr.io/felddy/foundryvtt:releaseThe most recent image from the stable channel. These images are considered stable, and well-tested. The latest tag always points to the same version as release.
ghcr.io/felddy/foundryvtt:latestSame as the release tag. Why does latest == release?

See the packages page for a complete list of available tags.
!NOTE Stable releases are also mirrored to Docker Hub and can be referenced using the full registry path: docker.io/felddy/foundryvtt:14

Volumes ##

Mount pointPurpose
/dataConfiguration, data, and log storage.

Ports ##

The following ports are exposed by this container:
PortPurpose
30000Foundry Virtual Tabletop server web interface

Environment variables ##

Required variable combinations ###

One of the three combinations of environment variables listed below must be set in order for the container to locate and install a Foundry Virtual Tabletop distribution. Although all variables may be specified together, they are evaluated in the following order of precedence:
1. FOUNDRY_RELEASE_URL, or 1. FOUNDRY_USERNAME and FOUNDRY_PASSWORD, or 1. CONTAINER_CACHE

Credentials variables ####

NamePurpose
FOUNDRYPASSWORDAccount password for foundryvtt.com. Required for downloading an application distribution.
FOUNDRYUSERNAMEAccount username or email address for foundryvtt.com. Required for downloading an application distribution.

Note: FOUNDRY_USERNAME and FOUNDRY_PASSWORD may be set using secrets instead of environment variables.

Presigned URL variable ####

NamePurpose
FOUNDRYRELEASEURLThe presigned URL generated from the user's profile. Required for downloading an application distribution.

Optional variables ###

Boolean variables accept true/false case-insensitively, along with 1/0, yes/no, and on/off. An unrecognized value logs a warning naming the variable and falls back to that variable's default. An empty Default means no value is configured, and Foundry's (or the system's) own behavior applies.
NamePurposeDefault
CONTAINERCACHESet a path to cache downloads of the Foundry distribution archive and speed up subsequent container startups. The path should be in /data or another persistent mount point in the container. Set to "" to disable. The cache may be shared by multiple containers: simultaneous startups coordinate among themselves so each release is downloaded only once.
Note: When the cache is disabled the container will sleep indefinitely on failure rather than exiting, to prevent a restart loop. A distribution can be pre-downloaded and placed into a cache directory. The distribution's name must be of the form: foundryvtt-14.370.zip, and its contents must match the version in its name — mislabeled archives are rejected and removed.
/data/containercache
CONTAINERCACHESIZESet the maximum number of distribution archives to keep in the cache. The minimum is 1. When the limit is exceeded, the least recently used archives are removed first — an archive counts as used each time a container installs from it, so a shared cache retains whatever its instances actually run, regardless of version numbers. Unset to disable cache size management and keep all versions.
CONTAINERPATCHESSet a path to a directory of shell scripts to be sourced after Foundry is installed but before it is started. The path should be in /data or another persistent mount point in the container. e.g.; /data/containerpatches Patch files are sourced in lexicographic order. CONTAINERPATCHES are processed after CONTAINERPATCHURLS.
CONTAINERPATCHURLSSet to a space-delimited list of URLs to be sourced after Foundry is installed but before it is started. Patch URLs are sourced in the order specified. CONTAINERPATCHURLS are processed before CONTAINERPATCHES. ⚠️ Only use patch URLs from trusted sources!
CONTAINERPRESERVECONFIGNormally new options.json and admin.txt files are generated by the container at each startup. Setting this to true prevents the container from modifying these files when they exist. If they do not exist, they will be created as normal.false
CONTAINERUMASKControl the default permissions on new files and directories created by Foundry VTT. Set the umask to "0002" if you need new files to be writable by other users in the same group as the foundry user. If this is empty or not set, the umask will not be changed (the system default is "0022").
CONTAINERURLFETCHRETRYNumber of times to retry fetching the presigned URL using exponential back off. This behavior is useful in continuous integration environments where multiple parallel workflows can exceed the rate-limit of the URL generation service.0
CONTAINERVERBOSESet to true to enable verbose logging for the container utility scripts.false
FOUNDRYADMINKEYAdmin password to be applied at startup. If omitted the admin password will be cleared. May be set using secrets.
FOUNDRYAWSCONFIGAn absolute or relative path that points to the awsConfig.json, or true for AWS environment variable credentials evaluation (e.g. ECS task or EC2 instance roles). Set to false or leave unset to disable.
FOUNDRYCOMPRESSWEBSOCKETSet to true to enable compression of data sent from the server to the client via websocket. This is recommended for network performance.false
FOUNDRYCSSTHEMEChoose the CSS theme for the setup page. Valid values are dark, fantasy, and scifi.dark
FOUNDRYDEMOCONFIGDemo mode allows you to configure a world which will be automatically launched and reset at a frequency of your choosing. When the world is reset, it is deactivated. The source data for the world is restored to its original state using a provided .zip file, and the next reset is automatically scheduled. See: Configuring demo mode.
FOUNDRYDELETENEDBSet to true to automatically delete legacy NeDB .db files after they have been migrated to the LevelDB format introduced in Version 11. Enabling this recovers disk space but removes the ability to roll back to a pre-migration state. Only relevant for data volumes previously used with Foundry Version 10 or earlier.false
FOUNDRYHOSTNAMEA custom hostname to use in place of the host machine's public IP address when displaying the address of the game session. This allows for reverse proxies or DNS servers to modify the public address.
FOUNDRYHOTRELOADSet to true to allow packages to hot-reload certain assets, such as CSS, HTML, and localization files without a full refresh. This setting is only recommended for developers.false
FOUNDRYIPDISCOVERYAllow the Foundry server to discover and report the accessibility of the host machine's public IP address and port. Setting this to false may reduce server startup time in instances where this discovery would timeout.true
FOUNDRYLANGUAGEThe default application language, as <language>.<module>. Languages other than English are provided by a translation module that must already be installed in your user data — for example, install the fr-core module and set fr.fr-core for French. The default English translations are built in.en.core
FOUNDRYLOCALHOSTNAMEOverride the local network address used for invitation links, mirroring the functionality of the FOUNDRYHOSTNAME option which configures the external address.
FOUNDRYLICENSEKEYThe license key to install. e.g.; AAAA-BBBB-CCCC-DDDD-EEEE-FFFF If left unset, a license key will be fetched when using account authentication. If multiple license keys are associated with an account, one will be chosen at random. Specific licenses can be selected by passing in an integer index. The first license key being 1. May be set using secrets.
FOUNDRYLOGSIZEThe maximum size a log file can reach before it is rotated. Units must be included. e.g.; 1024k, 64m, 1g.
FOUNDRYMAXLOGSThe maximum number of log files to retain before older ones are deleted.
FOUNDRYMINIFYSTATICFILESSet to true to reduce network traffic by serving minified static JavaScript and CSS files. Enabling this setting is recommended for most users, but module developers may wish to disable it.false
FOUNDRYNOBACKUPSSet to true to disable the automatic backup of world data that Foundry creates before performing major version migrations. Users with an external backup strategy or constrained storage may wish to enable this.false
FOUNDRYPASSWORDSALTCustom salt string to be applied to the admin password instead of the default salt string. May be set using secrets.
FOUNDRYPROTOCOLIf left unset Foundry VTT will bind to IPv4 and IPv6 interfaces. To limit to IPv4 only, set to 4. To limit to IPv6 only set to 6.
FOUNDRYPROXYPORTInform the Foundry server that the software is running behind a reverse proxy on some other port. This allows the invitation links created to the game to include the correct external port.
FOUNDRYPROXYSSLIndicates whether the software is running behind a reverse proxy that uses SSL. This allows invitation links and A/V functionality to work as if the Foundry server had SSL configured directly.false
FOUNDRYROUTEPREFIXA string path which is appended to the base hostname to serve Foundry VTT content from a specific namespace. For example setting this to demo will result in data being served from http://x.x.x.x:30000/demo/.
FOUNDRYSERVICECONFIGThe absolute path inside the container to a service configuration file. Must be set together with FOUNDRYSERVICEKEY.
FOUNDRYSERVICEKEYUsed in conjunction with FOUNDRYSERVICECONFIG. Setting this without FOUNDRYSERVICECONFIG will cause the container to exit with an error.
FOUNDRYSSLCERTAn absolute or relative path that points towards a SSL certificate file which is used jointly with the sslKey option to enable SSL and https connections. If both options are provided, the server will start using HTTPS automatically.
FOUNDRYSSLKEYAn absolute or relative path that points towards a SSL key file which is used jointly with the sslCert option to enable SSL and https connections. If both options are provided, the server will start using HTTPS automatically.
FOUNDRYTELEMETRYSet to true to enable FoundryVTT telemetry, false to disable. This option allows the collection of anonymous usage data to help improve FoundryVTT. It is recommended to explicitly set this value. Leaving this unset will cause Foundry to prompt the user to make a choice on every launch.(prompt)
FOUNDRYTEMPDIRAn absolute path to a directory used for temporary storage of package .zip archives while they are being downloaded and installed. When set, archives land outside the user data directory, so only the unpacked content counts against data volume space. Useful for hosts with constrained /data storage.
FOUNDRYUNIXSOCKETAn absolute path to a Unix domain socket for the server listener. When set, Foundry binds to the socket instead of the TCP port, which is useful for local reverse-proxy configurations (e.g. nginx or caddy via socket). If both a port and a socket path are configured, the socket takes precedence.
FOUNDRYUPNPAllow Universal Plug and Play to automatically request port forwarding for the Foundry server port to your local network address.false
FOUNDRYUPNPLEASEDURATIONSets the Universal Plug and Play lease duration, allowing for the possibility of permanent leases for routers which do not support temporary leases. To define an indefinite lease duration set the value to 0.
FOUNDRYVERSIONVersion of Foundry Virtual Tabletop to install.14.370
FOUNDRYWORLDThe directory name of the world to launch at system start.
TZContainer TZ database nameUTC
PROXYProxy settings to use during container initialization and by Foundry at runtime. See proxy-from-env for the list of supported environment variable names. See proxy-agent for list of supported proxy protocols.

Node.js variables ###

Any Node.js variables (NODE_*) supplied to the container will be passed to the underlying Node.js server running FoundryVTT. Listed below are some variables that are particularly useful.
NamePurpose
NODEDEBUG,-separated list of core modules that should print debug information.
NODEEXTRACACERTSWhen set, the well known "root" CAs (like VeriSign) will be extended with the extra certificates. The file should consist of one or more trusted certificates in PEM format. A message will be emitted (once) with process.emitWarning() if the file is missing or malformed, but any errors are otherwise ignored.
NODEOPTIONSA space-separated list of command-line options that are interpreted before command-line options, so command-line options will override or compound after anything supplied. Node.js will exit with an error if an option that is not allowed in the environment is used, such as -p or a script file.
NODETLSREJECTUNAUTHORIZEDIf the value equals 0, certificate validation is disabled for TLS connections. This makes TLS, and HTTPS by extension, insecure. ⚠️ The use of this environment variable is strongly discouraged.

Secrets ##

FilenameKeyPurpose
config.jsonfoundryadminkeyOverrides FOUNDRYADMINKEY environment variable.
config.jsonfoundrylicensekeyOverrides FOUNDRYLICENSEKEY environment variable.
config.jsonfoundrypasswordOverrides FOUNDRYPASSWORD environment variable.
config.jsonfoundrypasswordsaltOverrides FOUNDRYPASSWORDSALT environment variable.
config.jsonfoundryservicekeyOverrides FOUNDRYSERVICEKEY environment variable.
config.jsonfoundryusernameOverrides FOUNDRYUSERNAME environment variable.

Foundry VTT CLI ##

The image bundles the official Foundry VTT CLI as the fvtt command. It comes pre-configured with the container's installation and data paths, so package development workflows — such as packing and unpacking compendium databases — work in a running contain

Serve FoundryVTT Server on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxying foundryvtt-server.example.com to http://FoundryVTT:30000

Add this to your Caddyfile

foundryvtt-server.example.com {
	reverse_proxy http://FoundryVTT:30000
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs FoundryVTT
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:30000 failed: port is already allocated", something else on your server is using that port.

  • Find what's using it: sudo ss -tlnp | grep :30000
  • Stop the other service, or pick a different host port. In 30000:30000 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

  • Use your server's real IP: http://your-server-ip:30000. The 0.0.0.0 link Portainer shows isn't a real address.
  • Give it a minute after first deploy, FoundryVTT can take a while to initialise.
  • Make sure your firewall allows the port, e.g. sudo ufw allow 30000

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

  • Fix the ownership: sudo chown -R 1000:1000 /portainer/Files/AppData/Config/foundryvtt

Image won't pull

Test the pull directly on the host: docker pull felddy/foundryvtt:release

  • "manifest unknown" means the tag no longer exists.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • This image supports: amd64, arm64, arm/v7, ppc64le, s390x
  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect FoundryVTT --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A single container

FoundryVTT Server runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.

The app image

An image is the app packed up ready to go, everything FoundryVTT Server needs bundled into one download. This template pulls felddy/foundryvtt:release, which Docker fetches once (about 115 MB) and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. FoundryVTT Server's comes from Docker Hub, published by felddy.

Version tags

The bit after the colon in the image name is the version tag. This one pins release, so every redeploy gives you that exact build until you bump it yourself.

Which machines it runs on

Every image is built for particular CPU types. This one ships for amd64, arm64, arm/v7, ppc64le, s390x, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.

Ports

A port is the door the app answers on. A mapping like 30000:30000 means it's reachable on port 30000 of your server, where the left number is yours to change and the right one belongs to the app. It opens:

  • 30000:30000

Volumes

A volume is where FoundryVTT Server keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /data from /portainer/Files/AppData/Config/foundryvtt on the host

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. FoundryVTT Server takes 4 of them, all with defaults you can leave alone or tweak:

  • FOUNDRY_USERNAME, defaults to John. Foundry Account Name
  • FOUNDRY_PASSWORD, defaults to password. Foundry Password
  • FOUNDRY_ADMIN_KEY, defaults to changeme. Instance Admin Password
  • CONTAINER_PRESERVE_CONFIG, defaults to true

Restart policy

The restart policy here is unless-stopped, so Docker restarts FoundryVTT Server after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Networking

Nothing custom is set, so FoundryVTT Server sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container FoundryVTT. That's what you'll spot in the containers list and use in commands like docker logs FoundryVTT.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set FoundryVTT Server up. Add the template list to Portainer once, then deploying FoundryVTT Server is a click rather than a wall of config.