Recommended Linux Installation Guide (2024)

¶ Objective

This guide provides easy to follow steps for installing and using Foundry as a headless server in a linux environment. It is written to account for a number of linux common linux distributions and installation scenarios.

At the end of this guide you will have:

• Foundry server running 24/7 behind a reverse proxy providing HTTPS, including automatic restarts
• A domain name pointing to the server
• (Optional) Cyberduck, a file transfer program, configured to manage user data of the Foundry server
• (Optional) A swapfile set up to help in low-RAM (2GB) instances.

¶ Important Information and Requirements

This guide assumes that you have already installed linux, and have at least a basic understanding of linux and how to use a commanbd line.

The following is required to complete this guide:

1. An existing server with a modern linux distribution installed with a minimum of 2GB of RAM, for example:
   a. A linux PC on your home network.
   b. A linux virtual machine on any host.
   c. A linux virtual private server or dedicated server in the cloud.
2. A basic understanding of using a terminal that includes the ssh utility, such as:
   a. Powershell in Windows.
   b. Terminal in Linux or MacOS.
3. Valid domain name, such as:
   a. A purchased domain name from a registrar like Namecheap or gandi.net.
   b. A free subdomain from a free domain name service like Duck DNS.

The Foundry minimum requirements are 2GB RAM with 4GB recommended. Note that if you have other applications/services/etc that are using RAM in addition to Foundry, please consider more than 2GB. Essentially any CPU with at least one core should work.

¶ Preferred Linux Distribution

This guide includes instructions for a number of linux distributions, as described below. If you do not have a strong reason for another distribution, we recommend Ubuntu 22.04.

This guide supports the following distributions:

1. Debian 11 based, such as (but not limited to):
   a. Debian
   b. Ubuntu
   c. 64 bit Raspberry Pi OS
2. CentOS 8 based, such as (but not limited to):
   a. CentOS
   b. Red Hat Linux
   c. Fedora

Any distrition that uses the apt or dnf package managers should be compatible with this guide. Any differentiation in instructions for the distributions will be clearly indicated where necessary.

¶ Distributions to Avoid

• Amazon Linux 2
  This AWS-specific distribution does not support Node 18+, and also includes a number of changes and customizations that are specific to AWS and are out of scope of a simple Foundry hosting setup.

• NixOS or similar containerized / declarative distributions
  These distributions may work to host Foundry, but the instructions below will not work. They require specialized setup.

• Legacy or 32-bit Raspberry Pi OS/Raspbian
  Current 64-bit Raspberry Pi OS works and is recommended, but older or 32-bit versions have limited support for newer Node versions or could bump into limitations down the line.

This guide requires 64 bit Debian 11 or CentOS 8 based distributions or higher. Using lower versions may not function properly. 32 bit OSs will have issues with RAM and NodeJS heap size.

¶ Getting Help

If you get stuck on a particular step, please first ensure that all commands in black text quotes entered exactly as they appear. If multiple commands are included in the black text quotes, copy and paste each line individually and ensure it completes before moving on to the next line.

Troubleshooting assistance for this guide can be found on the official Foundry Discord. Copy the link from the specific step number (ie: C5) you are having difficulty with and then post in the #install-and-connection channel on the Foundry Discord.

¶ Objective

At the end of this section, you will have a non-root user setup to run Foundry as well as the necessary software to run Foundry managed behind a reverse proxy.

This section assumes that you are connected via terminal to your linux server. This can be either throught direct local access to a terminal or through ssh.

How to connect to your server is out of scope for this guide. You should have terminal access if you installed linux on a local pc, or if you are using a cloud VPS/VM provider then review their documentation for how to get ssh or terminal access to your instance.

¶ User Setup

We must use a non-root user that is part of the sudoers group to properly continue and manage Foundry.

If you are certain that you have a non-root user that has access to sudo then you may skip the next steps and continue to System Setup.

B1. Firstly, check your terminal to determine which user you are logged in as. Your terminal should look like:

<user>@<servername>:_ 

B2. The <user> field will show you which user you are connected as. If it shows root then we need to create a new user and add them to sudoers. If the user is NOT root then you can skip and continue to step B5.

Any references of <user> in the rest of the guide should be replaced with foundry in this case.

B3. Click the heading for your linux distribution to expand the commands to create a new user. We will create a user named foundry and add them to sudoers. Choose a strong password for the user that you will remember.

You can leave all other fields blank or fill with whatever info you'd like.

adduser foundryusermod -aG sudo foundry

adduser foundrypasswd foundryusermod -aG wheel foundry

B4. Assume the new user by:

su - foundry

You should now see the terminal look like:

foundry@<servername>:_

¶ System Setup

We will now install the necessary software to run and manage Foundry behind a reverse proxy. This includes:

• nodejs, required to run Foundry itself
• caddy, the webserver that will be used as a reverse proxy
• pm2, the process manager that will keep Foundry running
• unzip, the utility used to decompress the Foundry installation zip archive
• nano, the text editor used to edit configuration files

To continue, you must be using a non-root user with sudo access. If that is not the case, please review the steps in User Setup.

B5. First, let's update the system to make sure we have everything as up-to-date as possible. This may take a few minutes.

sudo apt updatesudo apt upgrade -y

sudo dnf update -y

You may be asked for a password the first time you use a sudo command. This is normal. Enter the password for the user.

See Also

Application Configuration | Foundry Virtual Tabletop

If after entering the correct password, you receive an error: <user> is not in the sudoers file or similar, then you must login as root and complete ther User Setup.

B6. Add the nodejs 20 repository to the system package manager:

sudo apt install -y ca-certificates curl gnupgsudo mkdir -p /etc/apt/keyringscurl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpgecho "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

sudo yum install https://rpm.nodesource.com/pub_20.x/nodistro/repo/nodesource-release-nodistro-1.noarch.rpm -ysudo yum install nodejs -y --setopt=nodesource-nodejs.module_hotfixes=1

B7. Add the caddy repository to the system package manager:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-httpscurl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpgcurl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

sudo dnf install 'dnf-command(copr)'sudo dnf copr enable @caddy/caddy -y

B8. Install nodejs, caddy, unzip, and nano:

sudo apt updatesudo apt install nodejs caddy unzip nano -y

sudo dnf install nodejs caddy unzip nano -y

B9. Check that nodejs and npm are installed and the correct versions:

node --versionnpm --version

Node should return a version of 18 or greater. The npm version doesn't matter, but should return something.

B10. Install pm2:

sudo npm install pm2 -g

B11. Add pm2 to startup as the current user. Be sure to carefully read the blue notice and follow all instructions given:

pm2 startup

REQUIRED STEP
You will need to carefully review the output of the pm2 startup command. It will include a specific instruction on how to enable pm2 startup on your particular distribution. Copy and paste this command exactly.

¶ Objective

At the end of this section you will have a functional installation of Foundry using HTTPS and Caddy as a reverse proxy. Foundry will be set to restart any time the server is restarted, managed by pm2.

¶ Download, Install, and Test Foundry

C1. Login to FoundryVTT and navigate to the Purchased Licenses page.

C2. Select the recommended version and Linux/NodeJS in the downloads options. Click on the Timed URL button to copy a download url.

Be sure to click the Timed URL and not the :download:Download button to copy and authenticated temporary download link. This link will expire in 5 minutes, after which it will need to be copied again from the gear.

C3. Run the following commands, pasting the download url where you see <download url>. In most terminals, you can right click to paste the copied url.

mkdir ~/foundrywget --output-document ~/foundry/foundryvtt.zip "<download url>"

Make sure to include the quote symbols before and after the <download url> or the file may not download properly.

C4. Once downloaded, extract Foundry and cleanup the zip file:

unzip ~/foundry/foundryvtt.zip -d ~/foundry/rm ~/foundry/foundryvtt.zip

If you get an error when unzipping Foundry, please ensure you've downloaded the Linux/NodeJS version and if not, repeat step C2.

C5. Create the User Data folder for Foundry to store data:

mkdir -p ~/foundryuserdata

C6. Test that Foundry runs successfully by running the following command. Replace the <user> portion with the name of the user currently being used.

cd ~node foundry/resources/app/main.js --dataPath=/home/<user>/foundryuserdata

C7. You should see these info lines at the end of the output, indicating that Foundry is successfully running.

If you do not see the above output ending with Server started and listening on port 30000, review step C6 to ensure you replaced <user> with the current user.

C8. Test the connection to Foundry by opening http://<IP address>:30000 in a new browser tab, where <IP address> is the either the external IP address of your cloud server or server internal IP address in your home network.

If you are setting up a server on your local network, use the local/internal IP address of the server. If you are setting up a server in the cloud, use the public IP address of the server.

You should see a Foundry screen asking for a license key at this point. If you do not see a Foundry screen at this point likely the your linux distribution or cloud provider has a firewall enabled that is blocking port 30000, or an incorrect IP address was used. Check the IP address carefully and otherwise review the documentation for your linux distribution or cloud provider for how to open port 30000 in the firewall.

C9. In the terminal window, press ctrl-c to stop the Foundry test. You should see the last few lines as below, and a blinking cursor at <user>@<server>:~$.

C10. We will now set Foundry to be managed by pm2 so that Foundry will always be running, even in the case where the instance has been restarted. To do so, run the following command. Be sure to replace <user> with the name of the actual user. There are two replacements:

pm2 start --name foundry /home/<user>/foundry/resources/app/main.js -- --dataPath=/home/<user>/foundryuserdata

C11. Double check pm2 has launched Foundry correctly:

pm2 list

If the status column does not show online then review step C10 above before continuing.

C12. Save the current pm2 configuration so that it can manage and restart Foundry as necessary:

pm2 save

¶ Set up the Caddy Reverse Proxy

This section assumes that you have a valid domain name with an A record pointing to your <public IP address>. If you do not have a domain name. you can use a service like Duck DNS (see guide if you are hosting on a home network) to get a free domain and point it to <public IP address>. Having a domain name is required for this section.

C13. Run the following command to begin editing the Caddyfile:

sudo nano /etc/caddy/Caddyfile

C14. Follow the steps below according to your relevant setup:

# This replaces the existing content in /etc/caddy/Caddyfile# A CONFIG SECTION FOR YOUR HOSTNAMEyour.hostname.com { # PROXY ALL REQUEST TO PORT 30000 reverse_proxy localhost:30000 encode zstd gzip}# Refer to the Caddy docs for more information:# https://caddyserver.com/docs/caddyfile

# This replaces the existing content in /etc/caddy/Caddyfile# A CONFIG SECTION FOR YOUR IP AND HOSTNAME{ default_sni your.internal.ip.address}your.internal.ip.address { # PROXY ALL REQUEST TO PORT 30000 tls internal reverse_proxy localhost:30000 encode zstd gzip}your.hostname.com { # PROXY ALL REQUEST TO PORT 30000 reverse_proxy localhost:30000 encode zstd gzip}# Refer to the Caddy docs for more information:# https://caddyserver.com/docs/caddyfile

C16. Press ctrl-x then y and enter to save your changes.

C17. Restart Caddy to pick up the new settings by:

sudo service caddy restart

Caddy handles all forwarding to HTTPS as well as the encryption certificates. No further configuration is needed to get those working.

C18. Tell Foundry that we are running behind a reverse proxy by changing the options.json file. Open the file for editing by:

nano ~/foundryuserdata/Config/options.json

C19. Find the proxySSL and proxyPort parameters, and change them as below. Leave all other options as they are. The hostname parameter will tell Foundry to use a hostname in the Internet Invite Link. Replace <your.domain.name> with your actual domain name.

..."proxyPort": 443,..."proxySSL": true,..."hostname": "<your.domain.name>",...

Make sure your hostname is in quotes as above, and be sure not to delete any commas or other JSON elements while editing this file. Change ONLY the values afer the :

C20. Press ctrl-x then y and enter to save your changes.

C21. Restart Foundry to pick up the changes to configuration:

pm2 restart foundry

C22. Test your site by opening a new browser tab to http://your.domain.name or http://server.internal.IP.address. If everything is working, you will see Foundry load and the site will have the encrypted lock icon. It is now ready for use and no further configuration is needed.

Sometimes DNS records can take a few minutes and up to a couple hours to be recognized across the internet. If you receive an error along the lines of server IP address could not be found or having trouble finding that site then the DNS records may just need more time. Wait a few minutes and try again.

If the connection is refused, you may need to open ports 80 and 443 in your OS firewall and then either your provider's network security settings (if cloud hosted) or through port forwarding on your router (if hosting at home).

If you are hosting on your home network, you must use an external device to test the connection to the domain name. You can only test the connection to the internal IP address from within the network.

This concludes the portion of the guide that sets Foundry up and running. You may now continue using Foundry this way without issue going forward.

¶ Objective

At the end of this optional section, you will be able to directly access the files in your userdata directory with Cyberduck. This is useful for moving, deleting, or bulk uploading assets for Foundry.

¶ Install and Setup Cyberduck

D1. Download and install Cyberduck for your platform from the Cyberduck website.

D2. Once installed, open Cyberduck and click Open Connection:

D3. In the Open Connection window, click the dropdown menu and select SFTP (SSH File Transfer Protocol)

D4. Enter the following information in the corresponding fields, replacing any values in <> with the values as earlier in the guide:

• Server: <your.domain.name> or <server internal IP address> if hosting in a home network
• Username: <user>
• Password: <password> (Leave blank if your existing user needs an ssh private key file to connect)
• SSH Private Key: Click Browse and select your SSH Private Key file. You may need to change the file type to All Files. Leave blank if using a password only.

D5. Click Connect

D6. Double click on the foundryuserdata directory, then the Data directory.

D7. Click the Bookmark menu, then New Bookmark. Close the window that pops up.

You now have a bookmarked connection in Cyberduck to the location of your Foundry userdata directory. Simply launch Cyberduck and double click the bookmark to connect and manage your files.

¶ Objective

The minimum RAM requirement for hosting Foundry is 2GB (4GB recommended), however some systems or modules may use more than the minimum RAM. If your linux host has 2GB of RAM you can create a swapfile to prevent out-of-memory errors when using heavier modules, systems, or large compendiums.

¶ Create and Enable Swapfile

The instructions below are compatible with the preferred linux distributions.

All commands below are assumed to be entered by a non-root sudoer user, such as the foundry user created in B1 to B4.

E1. Create a file to be used as swap:

sudo fallocate -l 2G /swapfile

This will create a 2GB swapfile which is a recommended size for hosts with 2GB of RAM. You can increase this size as you'd like, but it is not recommended to create a smaller swapfile.

E2. Change the permissions to prevent regular users from accessing the swapfile:

sudo chmod 600 /swapfile

E3. Mark the swapfile as a linux swap area:

sudo mkswap /swapfile

E4. Ensure that the swapfile is enabled permanently by editing the /etc/fstab file.

sudo nano /etc/fstab

E5. Paste the following line at the end of the fstab file while making sure the rest of fstab file is not modified. Press ctrl-x and then y, and then enter to save the changes to the file.

/swapfile swap swap defaults 0 0

E6. Enable the swapfile specified in fstab:

sudo swapon -a

E7. Verify the swapfile exists and is enabled:

sudo swapon --show

You should see an output like this:

NAME TYPE SIZE USED PRIO/swapfile file 2G 0B -1

You now have a swapfile enabled and should be protected against out-of-memory errors.

¶ Objective

As Foundry VTT is updated, the minimum requirements for NodeJS are also updated. If you've received a message stating that you must update NodeJS and you have used this guide (or similar guides, such as the Oracle Always Free guide, that use pm2 and the nodesource repo) then this section will describe how to update NodeJS to the latest version.

This section supports updating on Debian/Ubuntu-based linux distributions. Please substitute the appropriate package manager (like dnf) if apt is not available.

¶ Updating NodeJS

This section assumes that you have set Foundry VTT to be managed by pm2 and have installed NodeJS through their repo as this guide describes. Please copy and paste the instructions carefully.

F1. Stop any managed pm2 processes.

pm2 stop all

F2. Remove the current pm2 from startup to allow for the upgrade.

pm2 unstartup

F3. Add the new NodeJS version repository and update the installed version of NodeJS.

sudo apt install -y ca-certificates curl gnupgsudo mkdir -p /etc/apt/keyringscurl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpgecho "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.listsudo apt updatesudo apt upgrade

F4. Set pm2 to use the upgraded version of NodeJS and set it to run on start again.

npm rebuild -g pm2pm2 startup

F5. pm2 will list a command to run after the pm2 startup was run. Copy and paste that into the commandline and run it to ensure pm2 will launch on startup.

F6. Restart any previously running pm2 managed processes.

pm2 start all

F7. Check that Foundry is online. The output should show a green online indicator beside the Foundry process.

pm2 list

F8. Save the current pm2 configuration.

pm2 save

You've now successfully updated NodeJS and should be good to go!

¶ Objective

This will guide you through the steps needed to clear a current installation, and download the install a fresh version of Foundry - either an update or the same version. Your userdata will not be touched or affected at all.

¶ Archiving Current Install and New Install

Assuming that you have Foundry installed in ~/foundry and your userdata in a separate location (likely ~/foundryuserdata) and is managed by pm2.

G1. Once you have connected and navigated to your home directory ~, stop Foundry using pm2.

pm2 stop foundry

G2. Create a backup/archive of the current installation by moving the folder to a new location. You may need to name the destination folder something like foundry-archive-2023-06-02 in the case of multiple updates.

mv foundry foundry-archive

G3. Create the installation directory and download desired Foundry version using wget. You must use the Timed URL, and the Linux version. Be sure to wrap the URL with quotes below.

mkdir ~/foundrywget --output-document ~/foundry/foundryvtt.zip "<download url>"

G4. Once downloaded, extract Foundry and cleanup the zip file:

unzip ~/foundry/foundryvtt.zip -d ~/foundry/rm ~/foundry/foundryvtt.zip

G5. Restart Foundry using pm2.

pm2 start foundry

You should now have the new version of Foundry running and accessible as before!