Easy FoundryVTT setup using Docker

FoundryVTT has long been my VTT of choice, beating the outdated Roll20 and clunky desktop app Fantasy Grounds in all departments. I’d invested a fair bit of time and effort into both before discovering Foundry four years ago and haven’t looked back since.

Getting into Foundry is quite cost effective, it has a one off fee of £40 and there are often sales. Once you’ve paid for a licence you have three options for running it:

1. Subscribe to The Forge (or similar services, listed here) to host your games from $3.99 a month. An attractive option if you don’t want to bother with tech set up and are prepared to pay the cost. You do have to upload all assets to the Forge, but that’s no different to Roll20.

2. Self-host using another host such as AWS or Digital Ocean. This requires a fair bit more technical setup and you will incur usage costs.

3. Self-host from your own computer. This can be a good option as you have no ongoing costs, but it can seem daunting to set up, but it’s how I have been running Foundry for the last 4 years (saving ££’s on hosting fees).

In this post I’m going to go through my set-up in the hopes it might help someone else run Foundry like this.

Considerations

You can download a desktop app to run Foundry, all you need to do is open up port 30000 to allow your players to connect to your computer; by default it will run over http (which we know is generally not a good thing as requests are not encrypted), but you can configure it to run over https. You can also run it as a node app if you know what you’re doing, it’s how I was running it for a while.

If I was running the client or node like this, I’d want to use https. While it’s unlikely, if there was a security loophole in the Foundry code it could be exploited to gain access to your computer.

Port Forwarding

By default your web browser has strict controls over which ports can connect to your machine, for example ports 80 for http and 443 for https. For Foundry you need to open port 30000, which you need to do on your router or hub device from your ISP. Foundry has a page explaining how to do it here. You should be setting up Port Forwarding to map requests to your computer to port 30000 to port 30000 on your computer, this is blocked by default, but Port Forwarding should allow it. You could map a different port if you wanted, but be aware that some other services use other ports (for example you could map 29999 to 30000 instead).

Data Folder

You also need to know about the Foundry Data folder. This starts with a default location for Windows and MacOS (and I imagine Linux as well), but you can change it which I’d advise. Moving it also means you can have different data folders for different Foundry versions running their own containers. However, the real benefit of moving the Data folder is you can move it to Cloud backup so that you always have a copy if something went wrong with your set up. I back mine up to Dropbox, but you should be able to use any Cloud service (although I did have some weird sync problems with Google Drive, so I’d avoid that one).

Docker

For the last year or two I’ve used Docker to run Foundry in a container. This isn’t quite the same as a virtual machine, but offers many of the same benefits including ring-fencing the potential damage if someone was got exploit a Foundry loophole. Another advantage of using Docker is you can create different containers for multiple versions of Foundry.

Before we get onto Docker config you need to know about the Foundry Data folder. This starts with a default location for Windows and MacOS (and I imagine Linux as well), but you can change it which I’d advise. Moving it also means you can have different data folders for different Foundry versions running their own containers. However, the real benefit of moving the Data folder is you can move it to Cloud backup so that you always have a copy if something went wrong with your set up. I back mine up to Dropbox, but you should be able to use any Cloud service (although I did have some weird sync problems with Google Drive, so I’d avoid that one).

So once you’ve decided to use Docker and understand where to place your Data folder you can get started on setting things up.

Download Docker

The next step is to download Docker Desktop for your operating system, you can grab it here.

Once installed you’ll need to create a docker-compose.yml file in a folder of your choosing with these contents:

services:
  foundry:
    image: felddy/foundryvtt:12.331
    container_name: foundryvtt-v12-331-container
    hostname: your.hostname 
    volumes:
      - type: bind
        source: /parent/folder/of/data
        target: /data
        bind:
          create_host_path: true
    environment:
      - FOUNDRY_PASSWORD=${FVTT_PASSWD}
      - FOUNDRY_USERNAME=${FVTT_USERNAME}
      - FOUNDRY_ADMIN_KEY=${FVTT_ADMIN_KEY}
      - FOUNDRY_MINIFY_STATIC_FILES=true
      - FOUNDRY_HOSTNAME=your.hostname
      - CONTAINER_CACHE=/data/container_cache
      - TIMEZONE=Europe/London
    ports:
      - target: 30000
        published: 30000
        protocol: tcp

I use a .env file to store the password, username and admin key, but you can embed them direct into the docker-compose.yml file if you prefer.

FOUNDRY_PASSWORD=Your account password for foundryvtt.com
FOUNDRY_USERNAME=Your account username for foundryvtt.com
FOUNDRY_ADMIN_KEY=Your admin password for this foundry instance

This docker-compose.yml file is taken from this code repository, you can find more detail and full config options at https://github.com/felddy/foundryvtt-docker.

Finally turn to the command line. You can access this from your start menu in Windows or use a Terminal app in MacOS and Linux.

Command Line

If you’re not familiar with command line, it’s just another way of issuing commands on your command other than clicking on things with your mouse. Although it may feel a little archaic if you’re not used to it, command line is still heavily used and can be much more powerful than point and click. It is more frequently called a Terminal.

Windows

I haven’t fired up my Windows machine for a while and I’m not going to just for this. Off the top of my head, you go to the start menu, type cmd and click the Command Prompt option. This will pop up the command line Window. This page has more info https://www.lifewire.com/how-to-open-command-prompt-2618089.

MacOS/Linux

Open the Terminal app from Launchpad or type Terminal into Spotlight Search.

Once you’ve opened the command line/terminal enter these commands one at a time, pressing the enter key after each one. You’ll need to know the location of your docker-compose.yml file for the cd command.

cd location/of/docker-compose.yml
docker-compose up -d

cd is the change directory command, so you’re changing to the directory where your docker-compose.yml file was created.

docker-compose up tells docker to follow the instructions in the docker-compose.yml file. The -d switch is for detached mode, so after the container has been built, control returns to the command line.

If you look in Docker Desktop you’ll see your container running in the containers tab.

With that you should be able to browse to http://localhost:30000 to access your new Foundry instance.

Some final bits of advice:

• Test connecting to your local Foundry instance from outside your network by browsing to http://your_ip_address:30000. If that works it means your players will be able to connect when you run Docker.

• Shut your Docker instance down when you’re not using it.

• If you get an error about unzipping a file, it’s likely a file downloaded as part of the container creation process has been corrupted. To resolve that open your container_cache folder and delete the (corrupted) cached zip file. Next time you run docker-compose up -d the zip file will be pulled down and cached again, but hopefully this time it won’t be corrupted!

  

And a caveat with all this. It’s a while since I set this up, so I’ve probably missed something, let me know if that’s the case and I’ll update these instructions.