Introduction

This guide will walk you through the process of hosting Atlas using Docker Compose on a VPS (virtual private server). A basic understanding of Linux and Docker is recommended but not required.

Creating your Discord Bot

If you haven't already created a Discord bot, please use this guide to set one up.

Setting up a VPS with Hetzner

When it comes to servers and hosting, I recommend using a service called Hetzner.
Using my referral link, you can get €⁠20 in cloud credits which should give you a few months free.

Using my referral link helps to support me and my work. A massive thank you to anyone who has used it, it helps out a ton :)

This section of the guide will assume you're using Hetzner as your provider of choice, if you're using a different service, or are using your own hardware make sure your hardware meets the following requirements:

Debian based OS
2 CPU cores
4GB of RAM

You can skip here to continue.

Creating the server

Head on over to the Hetzner Cloud Console and create your account if you haven't already.
Create a new project.
Add a new server to your project.

In this guide, I'll be using the Nuremberg location with a Debian 12 image.

For the best performance and price, I recommend the server type CAX11 as it provides an ARM based architecture, with 2 vCores and 4GB of RAM.

Add your SSH key if you have one, if not, Hetzner will email your server's root password on creation.
Set your server name.

Click "Create & Buy now".

Congrats! You now have a server ready for setup.

Installing Docker

ssh root@<SERVER_IP>

If the prompt asks for a password, it's because you didn't add an SSH key to your server. Check your emails from Hetzner for your server password.

Once you've successfully authenticated, update the system packages.

apt update ; apt upgrade -y

Afterwards, run these commands to install the latest version of the Docker Engine:

# Add the Docker GPG key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update sources / packages
sudo apt update

# Install Docker Engine with BuildX and Compose plugins
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Optionally, you can verify if Docker installed successfully by running the hello-world image:

sudo docker run hello-world

If you see the following message, Docker Engine has been successfully installed:

Installing Lazydocker (Optional)

Lazydocker is an extremely useful, user-friendly TUI (Terminal User Interface) that makes it easy to manage Docker containers.

This step is optional, but highly recommended!

Download the latest version

Get the latest version of Lazydocker and assign the version tag to a variable:

LAZYDOCKER_VERSION=$(curl -s "https://api.github.com/repos/jesseduffield/lazydocker/releases/latest" | grep -Po '"tag_name": "v\K[0-9.]+')

If you're using an arm based architecture, or followed the Hetzner guide, use the following command to install the arm64 binary:

curl -Lo lazydocker.tar.gz "https://github.com/jesseduffield/lazydocker/releases/latest/download/lazydocker_${LAZYDOCKER_VERSION}_Linux_arm64.tar.gz"

...or if you're using an x86_64 architecture, use this command to install the x86_64 binary:

curl -Lo lazydocker.tar.gz "https://github.com/jesseduffield/lazydocker/releases/latest/download/lazydocker_${LAZYDOCKER_VERSION}_Linux_x86_64.tar.gz"

Installation

Create a new temporary directory:

mkdir lazydocker-temp

Extract the tarball to that directory:

tar xf lazydocker.tar.gz -C lazydocker-temp

Move the binary to /usr/local/bin:

sudo mv lazydocker-temp/lazydocker /usr/local/bin

Check if install was successful:

lazydocker --version

Clean up the archive and temporary directory:

rm -rf lazydocker.tar.gz lazydocker-temp

Success! You can now run lazydocker at anytime to get a dashboard of your Docker containers.

Setting up Docker Compose

Docker Compose is a powerful plugin for Docker, it allows defining and running multi-container applications using a single .y(a)ml file.

In this guide, the /root directory is where our docker-compose.yml file and Docker container data will be stored.

Verify if you have the Docker Compose plugin installed using the following command:

docker compose version

If you get an error, install the plugin using APT and run previous command again:
apt install docker-compose-plugin

Atlas requires two services to be defined in the compose config, one for a Lavalink node, and another for the bot itself.

Download from repo

Run the commands below to download the populated config from the Atlas repo:

wget https://raw.githubusercontent.com/tygrxqt/atlas/canary/docker-compose.yml
nano docker-compose.yml

Manual

...or you can create the file yourself...

touch docker-compose.yml
nano docker-compose.yml

...and copy and paste these values inside:

services:
  lavalink:
    image: ghcr.io/lavalink-devs/lavalink:4
    container_name: lavalink
    restart: unless-stopped
    expose:
      - 2333
    environment:
      - _JAVA_OPTIONS=-Xmx4G
    volumes:
      - ./lavalink/application.yml:/opt/Lavalink/application.yml
      - ./lavalink/plugins/:/opt/Lavalink/plugins/

  atlas:
    image: ghcr.io/tygrxqt/atlas:latest
    container_name: atlas
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - DISCORD_TOKEN=
      - PREFIX=?
      - SPOTIFY_CLIENT_ID=
      - SPOTIFY_CLIENT_SECRET=
      - LAVALINK_NAME=localhost
      - LAVALINK_HOST=lavalink
      - LAVALINK_PORT=2333
      - LAVALINK_PASSWORD=youshallnotpass
      - LAVALINK_SECURE=false
    depends_on:
      - lavalink

Update the environmental variables

So far, we have setup a VPS, installed the Docker engine, the Docker Compose plugin, and setup our services. We're almost there, next we have to configure Atlas with the correct environmental variables.

Open your docker-compose.yml file in your edit of choice:

nano docker-compose.yml

If you haven't already, create a Discord bot using this guide, and create a new Spotify app using this guide.
Make sure you have the values from both of those guides and plug them into your docker-compose.yml configuration like so:

services:
  lavalink:
    image: ghcr.io/lavalink-devs/lavalink:4
    container_name: lavalink
    restart: unless-stopped
    expose:
      - 2333
    environment:
      - _JAVA_OPTIONS=-Xmx4G
    volumes:
      - ./lavalink/application.yml:/opt/Lavalink/application.yml
      - ./lavalink/plugins/:/opt/Lavalink/plugins/

  atlas:
    image: ghcr.io/tygrxqt/atlas:latest
    container_name: atlas
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - DISCORD_TOKEN=<DISCORD_BOT_TOKEN>
                    # ^^^^^^^^^^^^^^^^^^^ This is where your Discord Bot token goes
      - PREFIX=>
      - SPOTIFY_CLIENT_ID=<SPOTIFY_CLIENT_ID>
                        # ^^^^^^^^^^^^^^^^^^^ - Place your Spotify Client ID here.
      - SPOTIFY_CLIENT_SECRET=<SPOTIFY_CLIENT_SECRET>
                            # ^^^^^^^^^^^^^^^^^^^^^^^ - Place your Spotify Client Secret here.
      - LAVALINK_NAME=localhost
      - LAVALINK_HOST=lavalink
      - LAVALINK_PORT=2333
      - LAVALINK_PASSWORD=youshallnotpass
      - LAVALINK_SECURE=false
    depends_on:
      - lavalink

You should end up with something along the lines of this:

atlas:
  image: ghcr.io/tygrxqt/atlas:latest
  container_name: atlas
  restart: unless-stopped
  environment:
  - DISCORD_TOKEN=MTI0OTg5NjE4Mzk5NzAwOTk2MA.GUm1QY.IcF_NuSglw1FjBRG9rRZleD4PjTOM8AhqLWipz
  - SPOTIFY_CLIENT_ID=91a9197af2c340e08f0fc2bd7368411e
  - SPOTIFY_CLIENT_SECRET=63e4af02f2c44e0ea704e99cd4af764c

Save your file and run the following commands to start your containers:

docker compose up -d ; lazydocker

Finishing up

After the command above has been ran, your containers should have been created and started and then lazydocker should have been started.
You should see a screen similar to this:

Heading back to Discord, you can see that Atlas is now online.

You can confirm the bot is working correctly using the >ping command:

Conclusion

Now that atlas has been set up, you can find all the commands Atlas offers by using the >cmds command.

GLHF!

Hosting Atlas