Setting Up Lavalink v4 on a Server From Scratch

This guide sets up a Lavalink v4 node on a Linux server from nothing: Java, the Lavalink JAR, a working configuration, the YouTube source plugin, a systemd service so it runs 24/7, and a quick test. It assumes an Ubuntu or Debian server with SSH access — for example a Kerit Cloud self-managed Lavalink plan, which comes with Ubuntu 22.04 and Java 17 already installed.

Step 1: Check Java

Lavalink v4 requires Java 17 or newer.

java -version

If Java isn’t installed (or is older than 17):

sudo apt update
sudo apt install -y openjdk-17-jre-headless

Java 21 also works well and has improvements to garbage collection for larger heaps. Either is fine for most nodes.

Step 2: Create a user and folder

Don’t run Lavalink as root. Create a dedicated user and directory:

sudo useradd -r -m -d /opt/lavalink -s /usr/sbin/nologin lavalink
sudo -u lavalink mkdir -p /opt/lavalink/plugins
cd /opt/lavalink

Step 3: Download Lavalink

Download the latest v4 release JAR from the official Lavalink GitHub releases page (lavalink-devs/Lavalink):

sudo -u lavalink curl -L -o /opt/lavalink/Lavalink.jar \
  https://github.com/lavalink-devs/Lavalink/releases/latest/download/Lavalink.jar

Step 4: Write application.yml

Create /opt/lavalink/application.yml. This is a minimal, working v4 configuration with the YouTube plugin enabled:

server:
  port: 2333
  address: 0.0.0.0

lavalink:
  plugins:
    - dependency: "dev.lavalink.youtube:youtube-plugin:VERSION"   # latest release
      snapshot: false
  server:
    password: "change-this-to-a-long-random-password"
    sources:
      youtube: false        # disabled in core; the plugin provides YouTube
      bandcamp: true
      soundcloud: true
      twitch: true
      vimeo: true
      http: true
      local: false
    bufferDurationMs: 400
    frameBufferDurationMs: 5000
    opusEncodingQuality: 10
    resamplingQuality: LOW
    trackStuckThresholdMs: 10000
    useSeekGhosting: true
    youtubePlaylistLoadLimit: 6
    playerUpdateInterval: 5

plugins:
  youtube:
    enabled: true
    allowSearch: true
    allowDirectVideoIds: true
    allowDirectPlaylistIds: true

metrics:
  prometheus:
    enabled: false
    endpoint: /metrics

logging:
  level:
    root: INFO
    lavalink: INFO

Replace VERSION with the latest release of the YouTube plugin from its GitHub page (lavalink-devs/youtube-source), and set a strong password — anyone who knows it can use your node. Every option is explained in Lavalink application.yml explained line by line.

Why is YouTube disabled under sources? In v4, the built-in YouTube source is deprecated; the dedicated plugin replaces it and is updated much more often. See the YouTube source plugin.

Step 5: Run it once in the foreground

Start Lavalink manually to check the configuration:

sudo -u lavalink java -Xmx400M -jar /opt/lavalink/Lavalink.jar

On first start, Lavalink downloads plugins listed under lavalink.plugins into the plugins folder. Watch the log for:

Lavalink is ready to accept connections.

If you see a YAML error, check indentation — YAML is whitespace-sensitive and tabs aren’t allowed. Press Ctrl+C to stop.

Step 6: Run it as a systemd service

A systemd service starts Lavalink at boot and restarts it if it crashes. Create /etc/systemd/system/lavalink.service:

[Unit]
Description=Lavalink audio node
After=network-online.target
Wants=network-online.target

[Service]
User=lavalink
WorkingDirectory=/opt/lavalink
ExecStart=/usr/bin/java -Xmx400M -jar /opt/lavalink/Lavalink.jar
Restart=on-failure
RestartSec=5
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now lavalink
sudo systemctl status lavalink
journalctl -u lavalink -f        # follow the logs

SuccessExitStatus=143 tells systemd that the exit code Java returns on SIGTERM is a normal stop, not a failure.

Sizing the heap

-Xmx sets the maximum Java heap. Leave room for the rest of the JVM and the operating system:

More in JVM tuning for Lavalink.

Step 7: Firewall

Only your bot needs to reach port 2333. If your bot runs elsewhere, allow its IP and block everyone else:

sudo ufw allow OpenSSH
sudo ufw allow from YOUR_BOT_SERVER_IP to any port 2333 proto tcp
sudo ufw enable

If you can’t restrict by IP (for example, your bot’s IP changes), leave the port open but rely on a long random password. Never use a default password like youshallnotpass on a public server — scanners look for exactly that.

Step 8: Test the node

From your own machine or the bot’s server, check that Lavalink answers:

curl -H "Authorization: your-password" http://YOUR_NODE_IP:2333/version
curl -H "Authorization: your-password" "http://YOUR_NODE_IP:2333/v4/loadtracks?identifier=ytsearch:lofi"

The first returns the Lavalink version; the second returns JSON with search results. If both work, your node is ready.

Step 9: Connect your bot

In your bot, configure the Lavalink client with:

• Host: your server’s IP or hostname
• Port: 2333
• Password: the one in application.yml
• Secure: false (plain WebSocket), unless you’ve put a TLS proxy in front

Library-specific guides: discord.js with Shoukaku and discord.py with Wavelink.

Keeping it healthy

• Update regularly. New Lavalink and plugin releases fix bugs and source breakages — especially the YouTube plugin. Download the new JAR or bump plugin versions, then sudo systemctl restart lavalink.
• Watch the logs for track exceptions and warnings: journalctl -u lavalink --since "1 hour ago".
• Monitor. Enable the Prometheus endpoint and graph players, memory and CPU — see monitoring Lavalink with Prometheus and Grafana.
• Prefer Docker? See running Lavalink in Docker.

If you’d rather skip all of this, managed Lavalink delivers a configured node with credentials in minutes.

Summary

Install Java 17+, create a dedicated user, download Lavalink.jar, write an application.yml with a strong password and the YouTube plugin enabled, and test it in the foreground. Then run it under systemd with a sensibly sized heap, restrict port 2333 to your bot where possible, verify with curl, and connect your bot with the host, port and password. Keep Lavalink and its plugins updated, and the node will run for months.