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

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

Navigate to the Purchased Software Licenses page.
Change the Operating System menu item to Linux/NodeJS.
Click the 🔗 Timed URL button to obtain the temporary URL.
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 \
  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.

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

Start the container and detach:
```
docker compose up --detach
```
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.

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"
}

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

Pull the new image from Docker Hub:
```
docker compose pull
```
Recreate the running container:
```
docker compose up --detach
```

Updating with Docker

Stop the running container:
```
docker stop <container_id>
```
Pull the new image:
```
docker pull felddy/foundryvtt:release
```
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:12.331.0`	An exact image version.
`felddy/foundryvtt:12.331`	The most recent image matching the major and minor version numbers.
`felddy/foundryvtt:12`	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:

FOUNDRY_RELEASE_URL, or
FOUNDRY_USERNAME and FOUNDRY_PASSWORD, or
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.

Presigned URL variable

Name	Purpose
`FOUNDRY_RELEASE_URL`	The presigned 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-12.331.zip`	`/data/container_cache`
`CONTAINER_CACHE_SIZE`	Set the maximum number of distribution versions to keep in the cache. The minimum is `1`. When the limit is exceeded, the oldest versions (lowest version numbers) are removed first. Unset to disable cache size management and keep all versions.
`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