+++
title = 'Set Up a Local FoundryVTT'
date = 2024-07-29T09:00:00Z
draft = false
summary="To start learning Foundry VTT 'inside and out' we create a local development server."
categories = ['Technical', 'Game Master', 'FoundryVTT']
prev = ['/post/do-you-want-to-play-a-game/']
+++

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](https://forge-vtt.com/)---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](https://foundryvtt.com/article/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](https://foundryvtt.com/article/installation/). 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.

```bash
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.

```json
{
  "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](https://foundryvtt.com/article/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`.

```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.

```bash
mkdir data
```

And now the magic.

```bash
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](http://localhost) and see a fresh Foundry installation. You should see end `End User License Agreement`.

![End User License Agreement](EULA.png)

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.

![Administrator Access Required](AdminAccess.png)

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

![Intial Setup Screen](initialsetup.png)


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

```bash
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.

```bash
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](https://discord.com/channels/1226222567292145786/1267486648011329576) and be sure to refer to this post's link ({{< permalink >}})