Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/felddy/foundryvtt-docker
An easy-to-deploy Dockerized Foundry Virtual Tabletop server.
https://github.com/felddy/foundryvtt-docker
docker docker-image foundry foundryvtt hacktoberfest icosahedron opendnd virtual-tabletop vtt
Last synced: 7 days ago
JSON representation
An easy-to-deploy Dockerized Foundry Virtual Tabletop server.
- Host: GitHub
- URL: https://github.com/felddy/foundryvtt-docker
- Owner: felddy
- License: mit
- Created: 2020-04-23T19:13:49.000Z (over 4 years ago)
- Default Branch: develop
- Last Pushed: 2024-05-01T08:53:10.000Z (8 months ago)
- Last Synced: 2024-05-01T16:44:19.034Z (8 months ago)
- Topics: docker, docker-image, foundry, foundryvtt, hacktoberfest, icosahedron, opendnd, virtual-tabletop, vtt
- Language: Shell
- Homepage: https://hub.docker.com/r/felddy/foundryvtt
- Size: 2.66 MB
- Stars: 522
- Watchers: 14
- Forks: 110
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# foundryvtt-docker #
[](https://github.com/felddy/foundryvtt-docker/actions/workflows/build.yml)
[](https://github.com/felddy/foundryvtt-docker/actions/workflows/codeql-analysis.yml)
[](https://securityscorecards.dev/viewer/?uri=github.com/felddy/foundryvtt-docker)
[](https://bestpractices.coreinfrastructure.org/projects/5966)
[](https://foundryvtt.com/releases/12.331)
[](https://hub.docker.com/r/felddy/foundryvtt)
[](https://hub.docker.com/r/felddy/foundryvtt)
[](https://hub.docker.com/r/felddy/foundryvtt/tags)
You can get a [Foundry Virtual Tabletop](https://foundryvtt.com) 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](https://docs.docker.com/get-docker/) installation.
- A [FoundryVTT.com](https://foundryvtt.com/auth/register/) 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](https://foundryvtt.com) credentials are required so the
container can install and license your server.
```console
docker run \
--env FOUNDRY_USERNAME='' \
--env FOUNDRY_PASSWORD='' \
--publish 30000:30000/tcp \
--volume :/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`](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-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](https://foundryvtt.com/me/licenses).
1. Change the `Operating System` menu item to `Linux/NodeJS`.
1. Click the `🔗 Timed URL` button to obtain the temporary URL.
1. Use the following command to start up a Foundry Virtual Tabletop server:
```console
docker run \
--env FOUNDRY_RELEASE_URL='' \
--publish 30000:30000/tcp \
--volume :/data \
felddy/foundryvtt:release
```
### Configuration management ###
[Configuration options](https://foundryvtt.com/article/configuration/) are
specified using [environment variables](#environment-variables). It is highly
recommended that you use [`docker compose`](https://docs.docker.com/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:
```yaml
---
version: "3.8"
services:
foundry:
image: felddy/foundryvtt:release
hostname: my_foundry_host
volumes:
- type: bind
source:
target: /data
environment:
- FOUNDRY_PASSWORD=
- FOUNDRY_USERNAME=
- FOUNDRY_ADMIN_KEY=atropos
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](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](https://docs.docker.com/engine/swarm/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](#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 `docker-compose.yml` file:
```yaml
---
version: "3.8"
secrets:
config_json:
file: secrets.json
services:
foundry:
image: felddy/foundryvtt:release
hostname: my_foundry_host
volumes:
- type: bind
source:
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:
```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
```
1. Pull the new image:
```console
docker pull felddy/foundryvtt:release
```
1. Follow the previous instructions for [running](#running) the container above.
## Image tags ##
The images of this container are tagged with [semantic
versions](https://semver.org) that align with the [version and build of Foundry
Virtual Tabletop](https://foundryvtt.com/article/versioning/) 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`?](https://vsupalov.com/docker-latest-tag/) |
See the [tags tab](https://hub.docker.com/r/felddy/foundryvtt/tags) 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*
1. `FOUNDRY_USERNAME` and `FOUNDRY_PASSWORD`, *or*
1. `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](#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 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 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` |
| `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](#using-secrets). | |
| `FOUNDRY_AWS_CONFIG` | An absolute or relative path that points to the [awsConfig.json](https://foundryvtt.com/article/aws-s3/) or `true` for AWS environment variable [credentials evaluation](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html) usage. | `null` |
| `FOUNDRY_COMPRESS_WEBSOCKET` | Set to `true` to enable compression of data sent from the server to the client via websocket. This is recommended for network performance. | `true` |
| `FOUNDRY_CSS_THEME` | Choose the CSS theme for the setup page. Choose from `foundry`, `fantasy`, or `scifi`. | `foundry` |
| `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](https://foundryvtt.com/article/configuration/#command-line). | |
| `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_HOT_RELOAD` | 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` |
| `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](#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](#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_TELEMETRY` | Set to `true` to enable FoundryVTT telemetry, `false` to disable. This options allows the collection of anonymous usage data to help improve FoundryVTT. | `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. | `12.331` |
| `FOUNDRY_WORLD` | The world to startup at system start. | `null` |
| `TIMEZONE` | Container [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) | `UTC` |
### Node.js variables ###
Any [Node.js
variables](https://nodejs.org/docs/latest-v16.x/api/cli.html#environment-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](https://docs.docker.com/engine/reference/commandline/build/#git-repositories):
```console
docker build \
--build-arg VERSION=12.331.0 \
--tag felddy/foundryvtt:12.331.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`](https://docs.docker.com/buildx/working-with-buildx/) feature of
Docker:
1. Copy the project to your machine using the `Clone` button above
or the command line:
```console
git clone https://github.com/felddy/foundryvtt-docker.git
cd foundryvtt-docker
```
1. Build the image using `buildx`:
```console
docker buildx build \
--platform linux/amd64 \
--build-arg VERSION=12.331.0 \
--output type=docker \
--tag felddy/foundryvtt:12.331.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:
```console
docker build \
--build-arg FOUNDRY_USERNAME='' \
--build-arg FOUNDRY_PASSWORD='' \
--build-arg VERSION=12.331.0 \
--tag felddy/foundryvtt:12.331.0 \
https://github.com/felddy/foundryvtt-docker.git#develop
```
Or build the image using a temporary URL:
```console
docker build \
--build-arg FOUNDRY_RELEASE_URL='' \
--build-arg VERSION=12.331.0 \
--tag felddy/foundryvtt:12.331.0 \
https://github.com/felddy/foundryvtt-docker.git#develop
```
## Contributing ##
We welcome contributions! Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for
details.
## License ##
This project is released as open source under the [MIT license](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.