Installation - YAMS - Yet Another Media Server

Dependencies

YAMS only needs a few things to get started:

Debian 12 (recommended) or Ubuntu 24.04 running on bare metal, a VM, or certain container types. If your OS isn’t ready yet, check out these guides:
- https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-11 (this tutorial is for Debian 11, but it should be the same).
- https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-22-04 (this tutorial is for Ubuntu 22.04, but is should be the same).
Your OS needs to be properly configured. That means:
- You have a user that is not root (because we’re responsible adults 😎)
- You can run sudo apt update and sudo apt upgrade without errors
- If you’re using Ubuntu, make sure you are NOT using the snap version of docker! The snap version runs in a sandbox and can’t access what it needs. You can check by running which docker. If you see:
```
$ which docker
/snap/bin/docker
```
You won’t be able to install YAMS. ⚠️
Proxmox LXC Users: YAMS can be installed within an unprivileged Proxmox LXC container, but this requires specific configuration on the Proxmox host before you run the YAMS installation script inside the container. Please follow the steps in our Proxmox LXC Prerequisites guide before proceeding with the installation steps below.

Don’t worry if you don’t have docker and docker-compose installed - the script can handle that for you on Debian and Ubuntu!

macOS Users

If you’re looking to install YAMS on macOS, you’re in luck! A community-maintained fork is available, specifically tailored for macOS.

Please visit zavan/yams on GitLab to access the fork and follow their installation instructions.

Disclaimer: This is a community-maintained project and is not officially supported by the YAMS team. For any issues or questions related to the macOS fork, please use the fork’s issue tracker.

Prerequisites

Before we dive in, make sure you have:

Git installed: You’ll need this to clone the YAMS repository. Check if it’s installed with:
```
git --version
```
If you don’t have it yet, it’s easy to install:
```
# For Debian/Ubuntu
sudo apt update
sudo apt install git
```
An installation location: The script defaults to /opt/yams but hey, you do you! Just make sure your user can write to wherever you choose.
A media folder: This is where all your stuff will live. For example, if you pick /srv/media, the script will create:
- /srv/media/tvshows: For your TV shows
- /srv/media/movies: For your movies
- /srv/media/music: For your tunes
- /srv/media/books: For your books
- /srv/media/downloads: For your downloads
- /srv/media/blackhole: For your torrent blackhole
A regular user to run and own the media files: Don’t use root (I mean, I can’t stop you, but come on! 😅)
A VPN service (optional but STRONGLY recommended): Choose one from this list. I always recommend ProtonVPN because it’s super easy to set up!

Pre-Installation Setup

1. Setup your install location

The /opt/yams location is recommended, but you can be a rebel and use whatever you like if your user has permissions:

sudo mkdir -p /opt/yams
sudo chown -R $USER:$USER /opt/yams

2. Setup your media directory

If your media directory doesn’t exist yet, you’ll need to create it and set the correct permissions. For example, if you’re using /srv/media:

sudo mkdir -p /srv/media
sudo chown -R $USER:$USER /srv/media

Important notes:

Make sure your user has full read/write permissions to this directory
If you’re using an external drive or NFS/SMB mount, mount it first, then set permissions
The installer will create subdirectories (tvshows, movies, music, etc.) automatically
Don’t use root as the owner, use your regular user account!

3. If you already have docker installed…

Make sure you can run docker without sudo! Try this:

docker run hello-world

If it fails, you might need to add your user to the docker group. Follow Docker’s post-installation steps or check our Common docker permission errors page.

Installation Steps

4. Get YAMS on your system

First, let’s grab a fresh copy of YAMS and put it in a temporary location (we like to keep things tidy!):

git clone --depth=1 https://gitlab.com/rogs/yams.git /tmp/yams
cd /tmp/yams

5. Start the installer

bash install.sh

You’ll see this welcome screen:

====================================================
                 ___           ___           ___
     ___        /  /\         /__/\         /  /\
    /__/|      /  /::\       |  |::\       /  /:/_
   |  |:|     /  /:/\:\      |  |:|:\     /  /:/ /\
   |  |:|    /  /:/~/::\   __|__|:|\:\   /  /:/ /::\
 __|__|:|   /__/:/ /:/\:\ /__/::::| \:\ /__/:/ /:/\:\
/__/::::\   \  \:\/:/__\/ \  \:\~~\__\/ \  \:\/:/~/:/
   ~\~~\:\   \  \::/       \  \:\        \  \::/ /:/
     \  \:\   \  \:\        \  \:\        \__\/ /:/
      \__\/    \  \:\        \  \:\         /__/:/
                \__\/         \__\/         \__\/
====================================================
Welcome to YAMS (Yet Another Media Server)
Installation process should be really quick
We just need you to answer some questions
====================================================

6. Docker Installation (if needed)

The installer will first check for Docker:

Checking prerequisites...
⚠️ Docker not found! ⚠️
Do you want YAMS to install docker and docker-compose? IT ONLY WORKS ON DEBIAN AND UBUNTU! [y/N]: y

If you don’t have Docker installed:
- Type y and press Enter to let YAMS handle the Docker installation
- The script will install both Docker and Docker Compose
- This only works on Debian and Ubuntu!
If you already have Docker:
- You’ll see “docker exists ✅” instead
- The installer will move to the next step

7. Choose Installation Location

Where do you want to install the docker-compose file? [/opt/yams]:

Press Enter to use the default /opt/yams (recommended) or type a different path if you want to install somewhere else
Make sure your user has write permissions to this location!
Important: You must use an absolute path (e.g., /mnt/yams). Docker does not expand ~ to your home directory, so avoid using something like ~/yams

8. Select User

What's the user that is going to own the media server files? [your_current_user]:

Press Enter to use your current user (recommended) or type a different username
Remember: Don’t use root!
The user must exist and have sudo privileges

9. Set Media Directory

Please, input your media directory [/srv/media]:

Press Enter to use the default /srv/media or type the path where you want your media stored. This path can also be a SMB/NFS mount in your host OS
This can be an external drive or different partition
Important: You must use an absolute path (e.g., /mnt/media). Docker does not expand ~ to your home directory, so avoid using something like ~/media
Make sure this directory exists and your user has permissions! See step 2 above if you haven’t created it yet

Then confirm your choice:

Are you sure your media directory is "/srv/media"? [y/N]:

Type y and press Enter if the path is correct
Type n or press Enter to go back and change it

10. Choose Media Service

Time to choose your media service.
Your media service is responsible for serving your files to your network.
Supported media services:
- jellyfin (recommended, easier)
- emby
- plex (advanced, always online)

Choose your media service [jellyfin]:

Pick your streaming service:

Press Enter for Jellyfin (recommended for beginners)
Type emby for Emby
Type plex for Plex

Each service has its strengths:

Jellyfin: Free, open-source, easy to set up
Emby: Similar to Jellyfin but with premium features
Plex: Most polished, but requires online account and is more complex to configure. Be aware of these new limitations if you don’t have a Plex Pass

11. VPN Configuration

Time to set up the VPN.
Supported VPN providers: https://yams.media/advanced/vpn

Configure VPN? (Y/n) [Default = y]:

If you want to use a VPN (strongly recommended):

Press Enter or type y to configure VPN

Enter your VPN provider:

VPN service? (with spaces) [protonvpn]:

Press Enter for ProtonVPN (recommended)
Or type your VPN provider’s name

The installer will show you where to find the setup documentation:

Please check protonvpn's documentation for specific configuration:
https://github.com/qdm12/gluetun-wiki/blob/main/setup/providers/protonvpn.md

Make sure to check this documentation - it will help you avoid common setup issues!

If you are using ProtonVPN:

DO NOT USE YOUR PROTON ACCOUNT USERNAME AND PASSWORD. REFER TO THE DOCUMENTATION ABOVE TO OBTAIN THE CORRECT VPN USERNAME AND PASSWORD.

Don’t say you weren’t warned.

The installer will then ask:

Are you using a free ProtonVPN account? (y/N) [Default = n]:

If you type y and press Enter:

⚠️ ProtonVPN Free Tier Users: If you plan to use a free ProtonVPN account, please be aware that port forwarding is not supported. See our ProtonVPN Free Tier guide here: https://yams.media/advanced/vpn/#protonvpn-free-tier for more details.

The installer will automatically configure Gluetun for the free tier (setting FREE_ONLY=on and disabling port forwarding). You will not need to make manual changes to docker-compose.yaml or .env for this.

If you type n or press Enter (for a paid account): The installer will proceed to the general port forwarding question.

If you are using Mullvad:

Mullvad is removing OpenVPN support on January 15, 2026.
If you plan to use Mullvad, you MUST migrate to WireGuard after installation.
Read more: https://mullvad.net/en/blog/removing-openvpn-15th-january-2026
WireGuard setup instructions: https://yams.media/advanced/wireguard/

Make sure you configure Wireguard after finishing the installation.

Configure port forwarding:

Port forwarding allows for better connectivity in certain applications.
However, not all VPN providers support this feature.
Please check your VPN provider's documentation to see if they support port forwarding.
Enable port forwarding? (y/N) [Default = n]:

Enter your credentials:

VPN username (without spaces):
VPN password:

Special notes:

For ProtonVPN, the installer handles the +pmp suffix for port forwarding automatically if you enabled it in the previous step. Just enter your VPN username.
For Mullvad, it will only ask you for your username, since Mullvad doesn’t need a password.
For other VPN providers, the installer will prompt you about port forwarding before asking for credentials.

If you don’t want to configure VPN now:

Type n and press Enter
You can set it up later, but always use a VPN when downloading torrents!

12. Installation Process

After you’ve answered all the questions, you’ll see:

Copying docker-compose.example.yaml to /opt/yams/docker-compose.yaml...
docker-compose.example.yaml was copied successfuly! ✅

Copying .env.example to /opt/yams/.env...
.env.example was copied successfuly! ✅

Copying docker-compose.custom.yaml to /opt/yams/docker-compose.custom.yaml...
docker-compose.custom.yaml was copied successfuly! ✅
Everything installed correctly! 🎉
Running the server...
This is going to take a while...

The installer will now:

Copy all necessary configuration files
Set up your chosen options
Start downloading and configuring Docker containers

You’ll then see:

We need your sudo password to install the YAMS CLI and configure permissions...

Enter your sudo password to:

Install the YAMS command-line tool
Set proper permissions on your media folders

If everything works, you’ll see these success messages:

YAMS CLI installed successfully ✅
Media directory ownership and permissions set successfully ✅
Install directory ownership and permissions set successfully ✅
Configuration folder "/opt/yams/config" exists ✅
Configuration folder ownership and permissions set successfully ✅

13. Final Success Screen

When everything’s done, you’ll see this awesome ASCII art:

========================================================
     _____          ___           ___           ___
    /  /::\        /  /\         /__/\         /  /\
   /  /:/\:\      /  /::\        \  \:\       /  /:/_
  /  /:/  \:\    /  /:/\:\        \  \:\     /  /:/ /\
 /__/:/ \__\:|  /  /:/  \:\   _____\__\:\   /  /:/ /:/_
 \  \:\ /  /:/ /__/:/ \__\:\ /__/::::::::\ /__/:/ /:/ /\
  \  \:\  /:/  \  \:\ /  /:/ \  \:\~~\~~\/ \  \:\/:/ /:/
   \  \:\/:/    \  \:\  /:/   \  \:\  ~~~   \  \::/ /:/
    \  \::/      \  \:\/:/     \  \:\        \  \:\/:/
     \__\/        \  \::/       \  \:\        \  \::/
                   \__\/         \__\/         \__\/
========================================================

Following this, you’ll get a list of all your service URLs:

Service URLs:
qBittorrent: http://your.ip.address:8081/
SABnzbd: http://your.ip.address:8080/
Radarr: http://your.ip.address:7878/
Sonarr: http://your.ip.address:8989/
Lidarr: http://your.ip.address:8686/
Prowlarr: http://your.ip.address:9696/
Bazarr: http://your.ip.address:6767/
Media Service: http://your.ip.address:8096/
Portainer: http://your.ip.address:9000/

Don’t worry about memorizing these - they’re saved in ~/yams_services.txt for easy reference!

Important Notes:

First Start Time
- Services might take a few minutes to fully start
- Be patient on first launch!
VPN Check If you configured a VPN, verify it’s working:
```
yams check-vpn
```
You should see different IPs for your system and qBittorrent.

What’s Next?

Time to configure your new media server! Head over to Configuration and follow these guides in order:

Need help? We’ve got your back!

Check our Common Issues page
Visit the YAMS Forum
Join our Discord or Matrix chat