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:

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

1. Start the container and detach:

```console
docker compose up --detach
```

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

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

1. Then add the secret to your compose.yml file:

```yaml
---
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:

```console
docker compose pull
```

1. Recreate the running container:

```console
docker compose up --detach
```

Updating with Docker ###

1. Stop the running container:

```console
docker stop <container_id>
```

1. Pull the new image:

```console
docker pull ghcr.io/felddy/foundryvtt:14
```

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

Image:tag	Description
ghcr.io/felddy/foundryvtt:14	The most recent image matching the major version number. Most users will use this tag.
ghcr.io/felddy/foundryvtt:14.365	The most recent image matching the major and minor version numbers.
ghcr.io/felddy/foundryvtt:14.365.0	An exact image version.
ghcr.io/felddy/foundryvtt:release	The 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:latest	Same 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 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 1. FOUNDRY_USERNAME and FOUNDRY_PASSWORD, or 1. CONTAINER_CACHE

Credentials variables ####

Name	Purpose
FOUNDRYPASSWORD	Account password for foundryvtt.com. Required for downloading an application distribution.
FOUNDRYUSERNAME	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
FOUNDRYRELEASEURL	The presigned URL generated from the user's profile. Required for downloading an application distribution.

Optional variables ###

Name	Purpose	Default
CONTAINERCACHE	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 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.365.zip	/data/containercache
CONTAINERCACHESIZE	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.
CONTAINERPATCHES	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/containerpatches Patch files are sourced in lexicographic order. CONTAINERPATCHES are processed after CONTAINERPATCHURLS.
CONTAINERPATCHURLS	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. CONTAINERPATCHURLS are processed before CONTAINERPATCHES. ⚠️ Only use patch URLs from trusted sources!
CONTAINERPRESERVECONFIG	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
CONTAINERUMASK	Control 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").
CONTAINERURLFETCHRETRY	Number 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
CONTAINERVERBOSE	Set to true to enable verbose logging for the container utility scripts.	false
FOUNDRYADMINKEY	Admin password to be applied at startup. If omitted the admin password will be cleared. May be set using secrets.
FOUNDRYAWSCONFIG	An absolute or relative path that points to the awsConfig.json or true for AWS environment variable credentials evaluation usage.	null
FOUNDRYCOMPRESSWEBSOCKET	Set to true to enable compression of data sent from the server to the client via websocket. This is recommended for network performance.	false
FOUNDRYCSSTHEME	Choose the CSS theme for the setup page. Valid values are dark, fantasy, and scifi.	dark
FOUNDRYDEMOCONFIG	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.
FOUNDRYDELETENEDB	Set 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
FOUNDRYHOSTNAME	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
FOUNDRYHOTRELOAD	Set 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
FOUNDRYIPDISCOVERY	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
FOUNDRYLANGUAGE	The default application language and module which provides the core translation files.	en.core
FOUNDRYLOCALHOSTNAME	Override the local network address used for invitation links, mirroring the functionality of the FOUNDRYHOSTNAME option which configures the external address.	null
FOUNDRYLICENSEKEY	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.
FOUNDRYLOGSIZE	The maximum size a log file can reach before it is rotated. Units must be included. e.g.; 1024k, 64m, 1g.
FOUNDRYMAXLOGS	The maximum number of log files to retain before older ones are deleted.
FOUNDRYMINIFYSTATICFILES	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
FOUNDRYNOBACKUPS	Set 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
FOUNDRYPASSWORDSALT	Custom salt string to be applied to the admin password instead of the default salt string. May be set using secrets.	null
FOUNDRYPROTOCOL	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
FOUNDRYPROXYPORT	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
FOUNDRYPROXYSSL	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
FOUNDRYROUTEPREFIX	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
FOUNDRYSERVICECONFIG	The absolute path inside the container to a service configuration file. Must be set together with FOUNDRYSERVICEKEY.	null
FOUNDRYSERVICEKEY	Used in conjunction with FOUNDRYSERVICECONFIG. Setting this without FOUNDRYSERVICECONFIG will cause the container to exit with an error.
FOUNDRYSSLCERT	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
FOUNDRYSSLKEY	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
FOUNDRYTELEMETRY	Set 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.
FOUNDRYTEMPDIR	An 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.
FOUNDRYUNIXSOCKET	An 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.	null
FOUNDRYUPNP	Allow Universal Plug and Play to automatically request port forwarding for the Foundry server port to your local network address.	false
FOUNDRYUPNPLEASEDURATION	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
FOUNDRYVERSION	Version of Foundry Virtual Tabletop to install.	14.365
FOUNDRYWORLD	The directory name of the world to launch at system start.	null
TZ	Container TZ database name	UTC
PROXY	Proxy 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.	null

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
NODEDEBUG	,-separated list of core modules that should print debug information.
NODEEXTRACACERTS	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.
NODEOPTIONS	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.
NODETLSREJECTUNAUTHORIZED	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	foundryadminkey	Overrides FOUNDRYADMINKEY environment variable.
config.json	foundrylicensekey	Overrides FOUNDRYLICENSEKEY environment variable.
config.json	foundrypassword	Overrides FOUNDRYPASSWORD environment variable.
config.json	foundrypasswordsalt	Overrides FOUNDRYPASSWORDSALT environment variable.
config.json	foundryservicekey	Overrides FOUNDRYSERVICEKEY environment variable.

| config.json