• Categories:
• Technical
• Game Master
• FoundryVTT

I am a great believer in learning how things work ‘inside’ in order to better deal with them day-to-day. Could we just use Foundry? Sure, but I want to understand the details so I can figure out what to do when things go wrong.

If you don’t want to dive into the details, that’s fine, the Game Master track will avoid all the techno-babble. However, I would still advise you to install a local copy of Foundry to learn with because:

1. The only cost is a Foundry license (which you can use with online sevices like The Forge—more on this later).
2. Having a local server means you do not need an internet service all the time (you still need it to download and install modules, etc.)
3. Using a local server (separate from the one you play on with others) for learning, development, or experimentation means less worry about screwing things up just before that big game night.
4. Thanks to Foundry’s license terms you can use the same license key for your “play” server (on The Forge, for example) and on your local development server (see Foundry FAQ).

   It is acceptable to run two (or more) instances of Foundry Virtual Tabletop using a single license if only one of those is accessible for player use by clients who are not the software license owner.

We could just install Foundry locally, but instead we will do something a little more complicated.

Docker

We are going to use a technology call containerisation. You don’t need to worry about all the technical details, just understand that this will allow us to run one or more copies of Foundry (possibly at different versions, which will be useful when we test upgrades).

The first step is to install a program called ‘Docker’ (again, don’t worry about all the technical details, for our purposes this is just ’the system that runs Foundry’). For instructions on downloading and installing Docker I suggest a quick search on YouTube. I won’t cover it here as this post is not a Docker tutorial.

Note If you need only one simple installation then Foundry provide installation instructions. Most of the technical posts on this site apply to any Foundry installation and I will note when a post relies heavily on a Docker installation.

I prefer using Docker because:

1. It takes away some of the complexity of setting up Foundry (at the cost of setting up Docker)
2. It keeps my Foundry installs isolated from all the other things going on in my computer.

Foundry

Now the neat part. First we create a directory to hold our Foundry setup. I’m on MacOS so these instructions are for that platform, you will need to adjust the paths for your situation.

cd ~
mkdir foundryvtt
cd foundryvtt

In this directory we create two files. The first vttsecrets.json will contain our secrets; specifically our logon credentials for foundryvtt.com (so we can download FoundryVTT) and the license we want to use.

{
  "foundry_admin_key": "supersecret",
  "foundry_password": "5jSb&MQdnFNdc#akj",
  "foundry_username": "myfoundry",
  "foundry_license_key": "YNTD-MF2Q-W94E-FMLL-A4UT-XUTZ"
}

Obviously you need to replace these values. foundry_admin_key is the password that will be set in your Foundry instance (the one you will use to access the Foundry Administration screen). foundry_username and foundry_password are the username and password you use to accees https://foundryvtt.com (where you purchase your Foundry Licence—see Foundry FAQ). Finally, foundry_license_key it the license you want to use for this installation (you find this under your https://foundryvtt.com account).

The second file is the one that will create and run your Foundry server, name it docker-compose.yaml.

secrets:
  config_json:
    file: /Users/myaccount/foundryvtt/vttsecrets.json

services:
  foundryvtt:
    image: felddy/foundryvtt:11
    volumes:
      - /Users/myaccount/foundryvtt/data:/data:rw
    ports:
      - 80:30000
    environment:
      - CONTAINER_PRESERVE_CONFIG=true
    secrets:
      - source: config_json
        target: config.json
    restart: unless-stopped

The paths (starting /Users/myaccount will need to be changed to match the paths to your installation).

Note that this setup will install the latest v11 installation of Foundry. If you want to use another version change the end of the image: line, e.g. for the latest v12 use image: felddy/foundryvtt:12. If you want to always start with the latest release version of Foundry use image: felddy/foundryvtt:release. For a complete list of all available Foundry images check https://hub.docker.com/r/felddy/foundryvtt/tags.

Also, we need to create the directory to hold our Foundry data.

mkdir data

And now the magic.

docker compose up -d

If all goes well then after a few seconds you will be able to open your browser and visit http://localhost and see a fresh Foundry installation. You should see end End User License Agreement.

Check the I agree to these terms box (bottom right) and then click the Agree button.

You will now see the Administrator Access Required screen.

Enter the foundry_admin_key password you provided in the vttsecrets.json file. You should now be on the initial setup screen.

Looking in your foundryvtt/data directory you should now see a set of data created by Foundry.

ls /Users/myaccount/foundryvtt/data
Config  container_cache  Data  Logs

The container_cache is created and maintained by the Docker image and is not a Foundry directory.

Config contains Foundry configuration files.

Logs contains Foundry log files (useful fo debuging and diagnosing problems, we won’t often refer to these).

Data this is the one we will most often refer to, it contains all of the data used by Foundry. If we look in that directory now we see.

ls /Users/myaccount/foundryvtt/data/Data
modules  systems  worlds

These three directories correspond to the Add-on Modules, Game Systems, and Game Worlds we see on the Foundry setup screen. We will be digging around these directories a lot (especially modules).

Before wrapping up this session, let’s complete the setup screens. In your browser, either Allow Sharing or Decline Sharing (either is fine, whether you share usage data or not is a personal choice and does not limit your use of Foundry).

Next you will be invited to tour the Foundry backup functionality. Feel free to follow along (using the tiny arrow in the bottom right) or ship it (close with the x at the top right).

With that we are ready to start setting up Foundry.

For help with this post please use the Discord channel and be sure to refer to this post’s link (https://mondarth.com/post/setup-a-local-foundryvtt/ )