Headless Server Software/Docker

Thanks

This guide was made possible by Shadow Panther's Headless Image.

Prerequisites

1. Basic familiarity with:
   • Command Line Systems
   • Configuration files including JSON familiarity
   • Docker & Docker Compose
2. A Patreon linked Resonite account that has access to the Headless Beta Code
   • You only need ONE account to get the code.
3. A spare Steam account

Recommendations

Before you get started here are some recommendations:

1. Use a non-windows machine
   • While this setup works for Windows, Docker on windows can break depending on your CPU, Operating System setup and even sometimes the motherboard. For less issues, stay off windows.
2. Use a separate machine
   • It is not recommended to run a headless on the same machine that you run Resonite on. This could lead to performance issues for both clients if you run them both at the same time.
3. Use a separate Resonite account. Whether these are positives or negatives for you can vary.
   • Separate login credentials
   • Dedicated storage instead of sharing with your own
   • Separate settings/banlist/allowed hosts, avoids potentially overriding each other
   • Headless doesn't currently support 2FA for logins Issue #253 so it will need to be disabled
4. Use a separate Steam account from the one you use to play games
   • Separate login credentials especially if in a shared environment or using scripts to download updates
   • Can more safely leave steam guard off if your setup doesn't stay logged in (ie docker)
   • Avoids issues with conflicting logins

Install Docker & Docker Compose

1. Visit Docker's Get Docker page
2. Follow instructions for your operating system
3. Ensure you also have Docker Compose. Depending on your setup, this may be included already but if not there's a Docker documentation page which has the details.

Test Docker Setup

To verify that docker is setup on your machine and working correctly:

1. Open a terminal window
2. Enter docker run hello-world
   • If all goes well, you'll see a pleasant message from Docker telling you that everything worked.
3. Run docker compose version to verify that you also have Docker Compose, you should see the Docker Compose version printed.

Docker Refresher

We have a separate page if you'd like information about Docker in general.

Get the Files

For this setup we'll be using some sample files that are available on a GitHub Repository. So if you're familiar with git, you can probably leave off here and follow the directions there.

But if you're not familiar with git, don't worry. You don't even need git, just keep reading right here on the wiki.

1. Download the files as a zip
   • This zip comes directly from GitHub
2. Extract the zip file
3. You should now have a folder called "Headless"

Specifying some credentials

Next, we'll need to gather some credentials and place them in a file within the "Headless" folder.

So be prepared with your:

• Patreon Headless Code
• Username and Password to a spare Steam account
  • The Steam account does not need to own any games
  • The Steam account does not need to be a Resonite Patreon
  • We recommend using a separate Steam account from the one you use to play Resonite.
  • We recommend turning off Steam Guard to prevent issues when signing on. That can be done on Steam's Website.

With those prepared:

1. Inside the "Headless" folder, create a new file called .env.
2. Add a line: RES_HEADLESS_CODE=<Headless Code> where <Headless Code> is replaced by the Patreon Headless Code.
3. Add a line: RES_STEAM_LOGIN=<Steam Username> <Steam Password> where <Steam Username> and <Steam Password>
4. Save the file

Running a Headless

This is the last step, everything should be ready!

1. Open a Terminal window in the Headless folder
   • On Windows, this can be done by:
     1. holding shift and pressing right click in some empty space within the Headless folder in Windows Explorer
     2. selecting "Open PowerShell window here"
   • On Linux, for common distributions such as Ubuntu you can right click in the folder browser and select "Terminal" or "Open Terminal".
     • Editors Note: It's been awhile since i've been in Linux from the point of view as a new user, if someone can edit that in it would help. But keep in mind "New User" ProbablePrime (talk) 09:07, 13 March 2024 (UTC)'
2. In the Terminal window enter docker compose up

After this a huge amount of items should appear in the terminal, this might be overwhelming but just wait, after awhile(any where from 3 to 10 minutes) you should see: resonite-headless | World running....

This means your headless is running.

Joining your Headless

Inside Resonite on your regular account:

1. Open the world browser
2. Select the "Headless Sessions" item on the left
3. Type "Testing" into the search bar
4. You should see your headless' session
5. Click it
6. Click Join

Limitations and where to go

Due to the simplicity of this guide, you'll probably notice a few things you'll want to change or correct, due to that here's a few links to get you started:

• Your world is just a simple grid world and you want it to be a custom world
  • Replace the contents of "Config.json" with one of the example configuration files.
• Your Headless has a weird name
  • This name is based on an internal part of the Docker runtime.
  • To override it, simply add a Resonite user's username and password to one of our example configuration files.
  • Or take a look at our configuration guide
  • The Resonite account does not need to:
    • Be a Patreon
    • We Recommend using a separate Resonite account from the one you use on Resonite regularily.
• You want Builder permissions in your Headless
  • Take a look at our configuration guide
• Your question isn't answered?
  • Take a look at our configuration guide
  • Ask on our Discord.

See Also

• Setup a Headless - How to setup a headless for the first time
• Managing Worlds - Guidance on world management with a headless.
• Configuration File - Learn about Headless Configuration Files
• Commands - Learn about Headless Commands