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 - A separate account causes less issues in the long term.
4. Use a separate Steam account from the one you use to play games - This prevents any issues with conflicting logins etc.

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

Here is a small refresher of Docker in general.

Basic commands

• docker pull <image> - Downloads the image locally
• docker run <parameters> <image> - Creates and starts a container with the specified image (doing CTRL+C or closing the prompt will stop it by default), some common parameters are:
  • -p <sourcePort>:<desinationPort> - Opens a port from within the container to your machine (specify 127.0.0.1: before the port specification to only open it locally)
  • -d - Detaches from the image, AKA runs it in the background
  • -e SOMETHING=value - Sets an environment variable, in this case sets the env variable SOMETHING to the value value.
  • -v /path/local:/path/inside - Binds a local path into the container, usually used to pass files or persist data such as databases
• docker container list --all - Lists all created containers
• docker container <stop/start/rm> <container name/ID> - Will stop, start or remove the specified container

Compose

Compose is a tool provided by Docker that makes it trivial to deploy software following a defined configuration file written in YAML. A compose file is usually named docker-compose.yml and a sample one looks like this:

version: '3.8'

services:
  hello-world:
    image: hello-world

Compose has some common commands to know:

• docker compose up <service(s) (optional)> - Will start all the services or the ones specified, from the configuration file (doing CTRL+C or closing the prompt will close the service)
  • To run all the services in the background, you will need to append the -d argument, for instance: docker compose up -d
• docker compose logs <service(s) (optional)> - Will display the logs of all the services or specified ones
  • You can also see the logs in real time by adding the argument -f, for instance docker compose logs -f (you will need to do CTRL+C to break out of this)
• docker compose stop <service> - Will stop the container created for the service, for instance docker compose stop hello-world
• docker compose down - Will stop all the services specified in the configuration and destroy their containers
• docker compose pull - Will check if any service has a newer image available and if so, will download it
  • After running this, you will still need to do docker compose up so containers are re-created with the latest version downloaded

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: <nowiki>resonite-headless | World running...<nowiki>.

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