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 needed to download a Foundry Virtual Tabletop release.
Prerequisites
- A functioning Docker installation.
- A FoundryVTT.com account with a purchased software license.
Running
Using Docker
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 FOUNDRT_PASSWORD='<your_password>' \
--publish 30000:30000/tcp \
--volume /data:<your_data_dir> \
felddy/foundryvtt:latest
Using a Docker composition
Using docker-compose
to manage your
server is highly recommended. A docker-compose.yml
file is a more reliable
way to start and maintain a container while capturing its configurations. All
of Foundry's configuration
options can be specified using
environment variables.
-
Create a
docker-compose.yml
file similar to the one below. Provide your credentials as values to the environment variables:version: "3.8" volumes: data: services: foundry: image: felddy/foundryvtt:latest hostname: my_foundry_host init: true restart: "unless-stopped" 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 mode: host
-
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.
Updating
The Foundry "Update Software" tab is disabled by default in this container. To upgrade to a new version of Foundry, update your image to the latest version.
Docker-compose
-
Pull the latest image from Docker hub:
docker-compose pull
-
Recreate the running container:
docker-compose up --detach
Docker
-
Stop the running container:
docker stop <container_id>
-
Pull the latest image:
docker pull felddy/foundryvtt:latest
-
Follow the previous instructions for running the container above.
Volumes
Mount point | Purpose |
---|---|
/data | configuration, data, and log storage |
Environment Variables
Required
Name | Purpose |
---|---|
FOUNDRY_USERNAME | Account username or email address for foundryvtt.com. Required for downloading an application release. |
FOUNDRY_PASSWORD | Account password for foundryvtt.com. Required for downloading an application release. |
Optional
Name | Purpose | Default |
---|---|---|
FOUNDRY_ADMIN_KEY | Admin password to be applied at startup. If omitted the admin password will be cleared. | |
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_GID | gid the deamon 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_NO_UPDATE | Prevent the application from being updated from the web interface. The application code is immutable when running in a container. See the Updating section for the steps needed to update this container. | true |
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_UPDATE_CHANNEL | The update channel to subscribe to. "alpha", "beta", or "release". | "release" |
FOUNDRY_UPNP | Allow Universal Plug and Play to automatically request port forwarding for the Foundry VTT port to your local network address. | false |
FOUNDRY_VERSION | Version of Foundry Virtual Tabletop to install. | 0.6.2 |
FOUNDRY_WORLD | The world startup at system start. | null |
TIMEZONE | Container TZ database name | UTC |
Building from source
-
Copy the project to your machine using the
Clone or download
button above or the command line:git clone https://github.com/felddy/foundryvtt-docker.git cd foundryvtt-docker
-
Build the image:
docker build \ --build-arg VERSION=0.6.2 \ --tag felddy/foundryvtt:0.6.2 .
See the Cross-platform builds instructions below for additional build options.
Cross-platform builds
To create images that are compatible with other platforms you can use the
buildx
feature of
Docker:
-
Create the
Dockerfile-x
file withbuildx
platform support:./buildx-dockerfile.sh
-
Build the image using
buildx
:docker buildx build \ --file Dockerfile-x \ --platform linux/amd64 \ --build-arg VERSION=0.6.2 \ --output type=docker \ --tag felddy/foundryvtt:0.6.2 .
Hosting behind Nginx with TLS
Below is an example configuration that will serve the Foundry Virtual Tabletop
application at a specific path. In this example, the application container will
be accessible at https://example.com/vtt
:
server {
listen 443 ssl http2 default_server;
listen [::]:443 ssl http2 default_server;
server_name example.com www.example.com;
if ($host = www.example.com) {
return 301 https://example.com$request_uri;
}
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
add_header Access-Control-Allow-Origin https://example.com always;
location /vtt {
# Foundry Virtual Tabletop routePrefix = "vtt"
proxy_http_version 1.1;
access_log /var/log/nginx/upstream_log upstream_logging;
proxy_read_timeout 90;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://localhost:30000;
}
}
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name example.com www.example.com;
return 301 https://example.com$request_uri;
}
Debugging
Here are a couple of options that can help if the container isn't working as it should.
Making the logging more verbose will provide more information about what is
going on during container startup. When reporting an issue, verbose output is
always more helpful. Simply set the CONTAINER_VERBOSE
environment variable to
true
to generate more detailed logging.
Name | Purpose | Default |
---|---|---|
CONTAINER_VERBOSE | Set to true to enable verbose logging for the container utility scripts. |
To drop into a shell after release installation but before it is started, you
can pass the --shell
option to then entrypoint:
Purpose | Command |
---|---|
Drop into a shell in the container | docker-compose run foundry --shell |
Contributing
We welcome contributions! Please see here for details.
License
This project is in the worldwide public domain.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.