Skip to main content

Foundry SelfHost With Cloudflare & Docker Compose

An alternative to port forwarding utilizing cloudflare tunnels and a docker installation on a local machine.

caution

USE AT YOUR OWN RISK!!

These guides are presented as is with no waranty, expectation of security, or anything like that. These are simply guides for how someone who has contributed to this github projected has set something up. They do not come with security audits, stats, dashboards, metrics, or ANY promises of being up to date or safe and secure to begin with.

1. Setup a Cloudflare Account​

If you don't already have one, sign up for one.

2. Purchase or Transfer a Domain Name​

This is the domain (or a subdomain of this domain) where your instance will be available online. You only need one domain if you plan to run multiple foundry instances as you will be able to assign subdomains when setting up tunnel(s) in a later step.

2.a If You Already Purchased A Domain Elsewhere...​

There are a few steps to setup your domain with cloudflare if you purchased it elsewhere.

Before you can set up your tunnel, you will need to add a site and configure cloudflare domain servers.

These are the prereqs you will see in the tunnel docs.

2.b If You Would Like To Just Buy One At Cloudflare​

You can register a new domain name with Cloudflare Registrar.

You will want to add a site in either case as I believe it is a required step for the tunnel. I cannot confirm if registering a domain through Cloudflare sets up a site or not as I already had a domain and thus did 2.a.

3. Setup a new Tunnel​

This can be done either through Cloudflare's WebUI or for those prefering the command line, the Cloudflare CLI. Up to date instructions for both can be found in Cloudflare's create your first tunnel docs.

If you are uncomfortable with the command line I would recommend Setting up a tunnel through the web dashboard as it is point and click. I have provided a few notes below to help clarify the cloudflare instructions for those new to all of this.

  • you can hold off on steps 1.5 and 1.6 until after you have everything set up.
  • you will ideally want to keep your tunnel token from these steps, and keep it somewhere SAFE like a password manager. If you do not, you can always log in and access it later by editing the existing tunnel.
  • for the hostname of this (and any tunnel you set up for use with the docker compose setup below) you can use foundry:30000. This is explained more in the Docker Compose steps.

4. Docker Compose​

You will want to install docker, and docker compose (now comes bundled with docker) in order to run foundry with the cloudflare daemon. If you are new to docker and docker compose, there are some (hopefully) helpful links and snippets in the Docker General Info / Links section.

4.1 Install Docker & Docker Compose​

Install docker for your desktop environment using the steps below.

info

HOW TO: Install Docker & Docker Compose On Linux​

Install Docker Desktop On Linux (Debian, Ubuntu, Fedora) -- This will install the docker desktop GUI and docker compose for Linux (Debian, Ubuntu, Fedora).

Install Docker Engine on Linux -- This will install docker engine and compose on your machine. This is the CLI only option for those who do not want / need the docker desktop client. This includes instructions for the three distros listed above as well as many others.

4.2 Clone / Download the Docker Config.​

The foundry-cloudflared repo contains the docker-compose.yml necessary to run this. You can either clone it or if you are unfamiliar with git, download the repo as a zip by clicking the Code dropdown button.

4.3 Populate Settings Files.​

you will not need to change the docker-compose.yml file itself, unless you want to override the default volume. You WILL need to create a directory and 3 files.

.env​

Create a file called .env in the directory with the docker-compose.yml file. Use your favorite / any text editor to add the following to it:

VERSION=

where the value is the version number you would like to pin to. For example, for version 11.307, you would create

EXAMPLE

VERSION=11.307

This will keep the docker container at the version specified. To update in the future, you simply need to stop the docker compose setup, update this file, and start it again. It will update on boot.

./env.d/foundry​

Our next two files need to be put in a directory called env.d so you will want to create that at the project root now. Then create a file in the env.d directory called foundry and populate it with the following:

FOUNDRY_PASSWORD=           
FOUNDRY_USERNAME=
FOUNDRY_ADMIN_KEY=
CONTAINER_PRESERVE_CONFIG=true

where

  • FOUNDRY_PASSWORD - your password for https://foundryvtt.com/.
  • FOUNDRY_USERNAME - your username for https://foundryvtt.com
  • FOUNDRY_ADMIN_KEY - set your admin password here for the server. You can reset it here in the furture as well.

./env.d/cloudflared​

Last create another file in env.d called cloudflared and add the following:

TUNNEL_TOKEN=

where

  • TUNNEL_TOKEN - the token for your cloudflare tunnel. If you didn't save it somewhere safe earlier you can get it by logging into cloudflare and clicking edit for the tunnel. You don't need to edit anything, just grab the token value from the code snippet.

4.4 (Optional) Copy Foundry Data​

If you are just going to start fresh you can skip this step. If you have a bunch of foudry data locally which you would like to copy over, you can do the following:

  • create a folder foundry-data at the root of the project. If you skipped this step and ran the setup, you will already have this directory.
  • Copy your Data and/or Config directories from your local foundry directory into foundry-data. You should be good to go.
  • If you would like to backup your server, you can just create a copy of the foundry-data directory at any time and keep it somewhere safe.

4.5 Run it.​

To run it, from the root of the directory run 

docker compose up

in the command line. I am not sure how to run this from docker desktop directory as I set it up using docker-engine on linux. I believe you will need to have docker desktop running to have this running. Google instructions for this and reach out and let us know how it went!

to shutdown the servers, run 

docker compose down
caution

USE AT YOUR OWN RISK!!

These guides are presented as is with no waranty, expectation of security, or anything like that. These are simply guides for how someone who has contributed to this github projected has set something up. They do not come with security audits, stats, dashboards, metrics, or ANY promises of being up to date or safe and secure to begin with.

Troubleshooting​

Permission Denied Running `docker compose up'​

This is expected as by default only root can run docker commands. This note should get you around it.

note

If you try to run docker compose up on linux and get permission denied, there are two remedies.

  1. run sudo docker compose up - by default your user is not added to the docker group and cannot start / stop containers. Running as root remedies this.

  2. Add your user to the docker group. This is easy and there are instructions in Docker's Linux post-installation steps for Docker Engine.