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
- 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.
- 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 thearm64
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/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.
- 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/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
- 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!