Hosting Atlas

T

tygrdotdev •

6 min read

hero image

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

  1. Head on over to the Hetzner Cloud Console and create your account if you haven't already.

  2. Create a new project.

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

image

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

  2. Set your server name.

image

  1. Click "Create & Buy now".

Congrats! You now have a server ready for setup.

Installing Docker

  1. Log in to your server using SSH:
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.

  1. Once you've successfully authenticated, update the system packages.
apt update ; apt upgrade -y
  1. 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
  1. 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:

image

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

  1. 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.]+')
  1. 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

  1. Create a new temporary directory:
mkdir lazydocker-temp
  1. Extract the tarball to that directory:
tar xf lazydocker.tar.gz -C lazydocker-temp
  1. Move the binary to /usr/local/bin:
sudo mv lazydocker-temp/lazydocker /usr/local/bin
  1. Check if install was successful:
lazydocker --version
  1. 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.

image

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.

  1. 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
  1. 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/tygrdotdev/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/tygrdotdev/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.

  1. Open your docker-compose.yml file in your edit of choice:
nano docker-compose.yml
  1. If you haven't already, create a Discord bot using this guide, and create a new Spotify app using this guide.

  2. 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/tygrdotdev/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/tygrdotdev/atlas:latest
  container_name: atlas
  restart: unless-stopped
  environment:
  - DISCORD_TOKEN=MTI0OTg5NjE4Mzk5NzAwOTk2MA.GUm1QY.IcF_NuSglw1FjBRG9rRZleD4PjTOM8AhqLWipz
  - SPOTIFY_CLIENT_ID=91a9197af2c340e08f0fc2bd7368411e
  - SPOTIFY_CLIENT_SECRET=63e4af02f2c44e0ea704e99cd4af764c
  1. 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!