foundryvtt-docker

You can get a Foundry Virtual Tabletop instance up and running in minutes using this container. This Docker container 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.

Prerequisites

• A functioning Docker installation.
• A FoundryVTT.com account with a purchased software license.

Running

Running with Docker and credentials

You can use the following command to start up a Foundry Virtual Tabletop server. Your foundryvtt.com credentials are required so the container can install and license your server.

docker run \
  --env FOUNDRY_USERNAME='<your_username>' \
  --env FOUNDRY_PASSWORD='<your_password>' \
  --publish 30000:30000/tcp \
  --volume <your_data_dir>:/data \
  felddy/foundryvtt:release

If you are using bash, or a similar shell, consider pre-pending the Docker command with a space to prevent your credentials from being committed to the shell history list. See: HISTCONTROL

Running with Docker and a temporary URL

Alternatively, you may acquire a temporary download token from your user profile page on the Foundry website. On the "Purchased Licenses" page, click the [🔗] icon to the right of the standard Node.js download link to obtain a temporary download URL for the software.

docker run \
  --env FOUNDRY_RELEASE_URL='<temporary_url>' \
  --publish 30000:30000/tcp \
  --volume <your_data_dir>:/data \
  felddy/foundryvtt:release

Configuration management

Configuration options are specified using environment variables. It is highly recommended that you use docker compose or similar container orchestration to manage your server's configuration. A docker-compose.yml file, like the example below, is a reliable way to start and maintain a container while capturing its configurations.

Each time the container starts it generates the configuration files needed by Foundry Virtual Tabletop using the values of the environment variables. That means changes made in the server's configuration GUI will not persist between container restarts. If you would like to disable the regeneration of these configuration files, set CONTAINER_PRESERVE_CONFIG to true.

1. Create a docker-compose.yml file similar to the one below. Provide your credentials as values to the environment variables:

   ---
   version: "3.8"
   
   services:
     foundry:
       image: felddy/foundryvtt:release
       hostname: my_foundry_host
       init: true
       volumes:
         - type: bind
           source: <your_data_dir>
           target: /data
       environment:
         - FOUNDRY_PASSWORD=<your_password>
         - FOUNDRY_USERNAME=<your_username>
         - FOUNDRY_ADMIN_KEY=atropos
       ports:
         - target: 30000
           published: 30000
           protocol: tcp

2. Start the container and detach:

   docker compose up --detach

3. Access the web application at: http://localhost:30000.

If all goes well you should be prompted with the license agreement, and then "admin access key" set with the FOUNDRY_ADMIN_KEY variable.

Using secrets

This container also supports passing sensitive values via Docker secrets. Passing sensitive values like your credentials can be more secure using secrets than using environment variables. Your secrets json file can have any name. This example uses secrets.json. Regardless of the name you choose it must be targeted to config.json within the container as in the example below. See the secrets section below for a table of all supported secret keys.

1. To use secrets, create a secrets.json file containing the values you want set:

   {
     "foundry_admin_key": "atropos",
     "foundry_password": "your_password",
     "foundry_username": "your_username"
   }

2. Then add the secret to your docker-compose.yml file:

   ---
   version: "3.8"
   
   secrets:
     config_json:
       file: secrets.json
   
   services:
     foundry:
       image: felddy/foundryvtt:release
       hostname: my_foundry_host
       init: true
       volumes:
         - type: bind
           source: <your_data_dir>
           target: /data
       environment:
       ports:
         - target: 30000
           published: 30000
           protocol: tcp
       secrets:
         - source: config_json
           target: config.json

Updating your container

The Foundry "Update Software" tab is disabled by default in this container. To upgrade to a new version of Foundry pull an updated image version.

Updating with Docker Compose

1. Pull the new image from Docker Hub:

   docker compose pull

2. Recreate the running container:

   docker compose up --detach

Updating with Docker

1. Stop the running container:

   docker stop <container_id>

2. Pull the new image:

   docker pull felddy/foundryvtt:release

3. Follow the previous instructions for running the container above.

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. It is recommended that most users use the :release tag.

Image:tag	Description
felddy/foundryvtt:release	The most recent image from the stable channel. These images are considered stable, and well-tested. Most users will use this tag. The latest tag always points to the same version as release.
felddy/foundryvtt:10.291.0	An exact image version.
felddy/foundryvtt:10.291	The most recent image matching the major and minor version numbers.
felddy/foundryvtt:10	The most recent image matching the major version number.
felddy/foundryvtt:latest	See the release tag. Why does latest == release?

See the tags tab on Docker Hub for a list of all the supported tags.

Volumes

Mount point	Purpose
/data	Configuration, data, and log storage.

Ports

The following ports are exposed by this container:

Port	Purpose
30000	Foundry 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
2. FOUNDRY_USERNAME and FOUNDRY_PASSWORD, or
3. CONTAINER_CACHE

Credentials variables

Name	Purpose
FOUNDRY_PASSWORD	Account password for foundryvtt.com. Required for downloading an application distribution.
FOUNDRY_USERNAME	Account 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.

Pre-signed URL variable

Name	Purpose
FOUNDRY_RELEASE_URL	S3 pre-signed URL generate from the user's profile. Required for downloading an application distribution.

Optional variables

Name	Purpose	Default
CONTAINER_CACHE	Set 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. Note: When the cache is disabled the container may sleep instead of exiting, in certain circumstances, to prevent a download loop. A distribution can be pre-downloaded and placed into a cache directory. The distribution's name must be of the form: foundryvtt-10.291.zip	/data/container_cache
CONTAINER_PATCHES	Set 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/container_patches Patch files are sourced in lexicographic order. CONTAINER_PATCHES are processed after CONTAINER_PATCH_URLS.
CONTAINER_PATCH_URLS	Set 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. CONTAINER_PATCH_URLS are processed before CONTAINER_PATCHES. ⚠️ Only use patch URLs from trusted sources!
CONTAINER_PRESERVE_CONFIG	Normally 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
CONTAINER_PRESERVE_OWNER	Normally the ownership of the /data directory and its contents are changed to match that of the server at startup. Setting this to a regular expression will exclude any matching paths and preserve their ownership. Note: This is a match on the whole path, not a search. This is useful if you want mount a volume as read-only inside /data (e.g.; a volume that contains assets mounted at /data/Data/assets).
CONTAINER_URL_FETCH_RETRY	Number of times to retry fetching the S3 pre-signed 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
CONTAINER_VERBOSE	Set to true to enable verbose logging for the container utility scripts.	false
FOUNDRY_ADMIN_KEY	Admin password to be applied at startup. If omitted the admin password will be cleared. May be set using secrets.
FOUNDRY_AWS_CONFIG	An absolute or relative path that points to the awsConfig.json or true for AWS environment variable credentials evaluation usage.	null
FOUNDRY_DEMO_CONFIG	Demo 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.
FOUNDRY_GID	gid the daemon will be run under.	foundry
FOUNDRY_HOSTNAME	A 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.	null
FOUNDRY_IP_DISCOVERY	Allow 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
FOUNDRY_LANGUAGE	The default application language and module which provides the core translation files.	en.core
FOUNDRY_LOCAL_HOSTNAME	Override the local network address used for invitation links, mirroring the functionality of the FOUNDRY_HOSTNAME option which configures the external address.	null
FOUNDRY_LICENSE_KEY	The 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.
FOUNDRY_MINIFY_STATIC_FILES	Set 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
FOUNDRY_PASSWORD_SALT	Custom salt string to be applied to the admin password instead of the default salt string. May be set using secrets.	null
FOUNDRY_PROTOCOL	If 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.	null
FOUNDRY_PROXY_PORT	Inform 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.	null
FOUNDRY_PROXY_SSL	Indicates 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
FOUNDRY_ROUTE_PREFIX	A 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/.	null
FOUNDRY_SSL_CERT	An 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.	null
FOUNDRY_SSL_KEY	An 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.	null
FOUNDRY_UID	uid the daemon will be run under.	foundry
FOUNDRY_UPNP	Allow Universal Plug and Play to automatically request port forwarding for the Foundry server port to your local network address.	false
FOUNDRY_UPNP_LEASE_DURATION	Sets 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.	null
FOUNDRY_VERSION	Version of Foundry Virtual Tabletop to install.	10.291
FOUNDRY_WORLD	The world to startup at system start.	null
TIMEZONE	Container TZ database name	UTC

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.

Name	Purpose
NODE_DEBUG	,-separated list of core modules that should print debug information.
NODE_EXTRA_CA_CERTS	When 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.
NODE_OPTIONS	A 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.
NODE_TLS_REJECT_UNAUTHORIZED	If 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

Filename	Key	Purpose
config.json	foundry_admin_key	Overrides FOUNDRY_ADMIN_KEY environment variable.
config.json	foundry_license_key	Overrides FOUNDRY_LICENSE_KEY environment variable.
config.json	foundry_password	Overrides FOUNDRY_PASSWORD environment variable.
config.json	foundry_password_salt	Overrides FOUNDRY_PASSWORD_SALT environment variable.
config.json	foundry_username	Overrides FOUNDRY_USERNAME environment variable.

Building from source

Build the image locally using this git repository as the build context:

docker build \
  --build-arg VERSION=10.291.0 \
  --tag felddy/foundryvtt:10.291.0 \
  https://github.com/felddy/foundryvtt-docker.git#develop

Cross-platform builds

To create images that are compatible with other platforms you can use the buildx feature of Docker:

1. Copy the project to your machine using the Clone button above or the command line:

   git clone https://github.com/felddy/foundryvtt-docker.git
   cd foundryvtt-docker

2. Build the image using buildx:

   docker buildx build \
     --platform linux/amd64 \
     --build-arg VERSION=10.291.0 \
     --output type=docker \
     --tag felddy/foundryvtt:10.291.0 .

Pre-installed distribution builds

It is possible to install a Foundry Virtual Tabletop distribution into the Docker image at build-time. This results in a significantly larger Docker image, but removes the need to install a distribution at container startup, resulting in a faster startup. It also moves the user authentication to build-time instead of start-time. Note: Credentials are only used to fetch a distribution, and are not stored in the resulting image.

Build the image with credentials:

docker build \
  --build-arg FOUNDRY_USERNAME='<your_username>' \
  --build-arg FOUNDRY_PASSWORD='<your_password>' \
  --build-arg VERSION=10.291.0 \
  --tag felddy/foundryvtt:10.291.0 \
  https://github.com/felddy/foundryvtt-docker.git#develop

Or build the image using a temporary URL:

docker build \
  --build-arg FOUNDRY_RELEASE_URL='<temporary_url>' \
  --build-arg VERSION=10.291.0 \
  --tag felddy/foundryvtt:10.291.0 \
  https://github.com/felddy/foundryvtt-docker.git#develop

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

This project is released as open source under the MIT license.

All contributions to this project will be released under the same MIT license. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.