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

• An OCI-compatible container runtime such as Kubernetes, Podman, or Docker.
• 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 \
  ghcr.io/felddy/foundryvtt:14

[!TIP] 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 URL from your user profile page on the Foundry website.

1. Navigate to the Purchased Software Licenses page.
2. Change the Operating System menu item to Node.js.
3. Click the 🔗 Timed URL button to obtain the temporary URL.
4. Use the following command to start up a Foundry Virtual Tabletop server:

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

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 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.

[!IMPORTANT] Always set a stable hostname in your compose.yml (or --hostname in docker run). Foundry binds its software license to the container hostname. If no hostname is set, Docker assigns a random container ID on each start, causing license verification to fail after every restart.

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

   ---
   services:
     foundry:
       image: ghcr.io/felddy/foundryvtt:14
       hostname: my_foundry_host
       volumes:
         - type: bind
           source: <your_data_dir>
           target: /data
       environment:
         - FOUNDRY_USERNAME=<your_username>
         - FOUNDRY_PASSWORD=<your_password>
         - FOUNDRY_ADMIN_KEY=atropos
         - FOUNDRY_TELEMETRY=true
       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 compose.yml file:

   ---
   secrets:
     config_json:
       file: secrets.json
   
   services:
     foundry:
       image: ghcr.io/felddy/foundryvtt:14
       hostname: my_foundry_host
       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 the registry:

   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 ghcr.io/felddy/foundryvtt:14
   

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.

[!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.

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

Ports

The following ports are exposed by this container:

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

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

Presigned URL variable

Optional variables

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.

Secrets

Building from source

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

docker build \
  --build-arg CONTAINER_VERSION=14.364.0 \
  --build-arg FOUNDRY_VERSION=14.364 \
  --tag ghcr.io/felddy/foundryvtt:14.364.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 CONTAINER_VERSION=14.364.0 \
     --build-arg FOUNDRY_VERSION=14.364 \
     --output type=docker \
     --tag ghcr.io/felddy/foundryvtt:14.364.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.

Image build with credentials

[!NOTE] Credentials are only used to fetch a distribution, and are not stored in the resulting image.

docker build \
  --build-arg CONTAINER_VERSION=14.364.0 \
  --build-arg FOUNDRY_VERSION=14.364 \
  --secret id=foundry_username,src=<(echo "<your_username>") \
  --secret id=foundry_password,src=<(echo "<your_password>") \
  --tag ghcr.io/felddy/foundryvtt:14.364.0 \
  https://github.com/felddy/foundryvtt-docker.git#develop

[!TIP] If you have stored your credentials in a json file, as documented in the using secrets section above, you can extract the username and password and pass them as build secrets using the following syntax:

docker build \
  --build-arg CONTAINER_VERSION=14.364.0 \
  --build-arg FOUNDRY_VERSION=14.364 \
  --secret id=foundry_username,src=<(jq -r '.foundry_username' path/to/credentials.json) \
  --secret id=foundry_password,src=<(jq -r '.foundry_password' path/to/credentials.json) \
  --tag ghcr.io/felddy/foundryvtt:14.364.0 \
  https://github.com/felddy/foundryvtt-docker.git#develop

More information about Docker build secrets can be found in the Docker documentation.

Image build with a temporary URL

docker build \
  --build-arg CONTAINER_VERSION=14.364.0 \
  --build-arg FOUNDRY_VERSION=14.364 \
  --build-arg FOUNDRY_RELEASE_URL='<temporary_url>' \
  --tag ghcr.io/felddy/foundryvtt:14.364.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.