> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Host a Lavalink Server for Your Music Bot

> Lavalink server hosting for Discord music bots: a v4 application.yml with the YouTube plugin, port 80, a strong password and how your bot connects.

export const RecommendedPlan = ({lang, plan, tier, cpu, appType, min}) => {
  const t = {
    'en': {
      q: <>Which plan should you choose for {appType}?</>,
      rec: p => <>We recommend the {p} plan: its <b>{tier} GB</b> of RAM and <b>{cpu} vCPU</b> handle most projects of this kind, with headroom for traffic spikes.</>,
      min: m => <> Lighter projects also run on the {m} plan.</>,
      pro: p => <> For larger projects, the {p} plan adds more RAM and CPU.</>
    },
    'pt-br': {
      q: <>Qual plano escolher para {appType}?</>,
      rec: p => <>Recomendamos o plano {p}: seus <b>{tier} GB</b> de RAM e <b>{cpu} vCPU</b> atendem a maioria dos projetos desse tipo, com folga para picos de tráfego.</>,
      min: m => <> Projetos mais leves também rodam no plano {m}.</>,
      pro: p => <> Para projetos maiores, o plano {p} oferece mais RAM e CPU.</>
    },
    'es': {
      q: <>¿Qué plan elegir para {appType}?</>,
      rec: p => <>Te recomendamos el plan {p}: sus <b>{tier} GB</b> de RAM y <b>{cpu} vCPU</b> cubren la mayoría de los proyectos de este tipo, con margen para picos de tráfico.</>,
      min: m => <> Los proyectos más ligeros también funcionan en el plan {m}.</>,
      pro: p => <> Para proyectos más grandes, el plan {p} ofrece más RAM y CPU.</>
    },
    'fr': {
      q: <>Quel plan choisir pour héberger {appType} ?</>,
      rec: p => <>Nous recommandons le plan {p} : ses <b>{tier} Go</b> de RAM et <b>{cpu} vCPU</b> suffisent pour la plupart des projets de ce type, avec une marge pour les pics de trafic.</>,
      min: m => <> Les projets plus légers fonctionnent aussi avec le plan {m}.</>,
      pro: p => <> Pour les projets plus importants, le plan {p} offre davantage de RAM et de CPU.</>
    },
    'de': {
      q: <>Welcher Plan eignet sich für {appType}?</>,
      rec: p => <>Wir empfehlen den {p}-Plan: <b>{tier} GB</b> RAM und <b>{cpu} vCPU</b> reichen für die meisten Projekte dieser Art, mit Reserven für Lastspitzen.</>,
      min: m => <> Kleinere Projekte laufen auch mit dem {m}-Plan.</>,
      pro: p => <> Für größere Projekte bietet der {p}-Plan mehr RAM und CPU.</>
    },
    'it': {
      q: <>Quale piano scegliere per {appType}?</>,
      rec: p => <>Ti consigliamo il piano {p}: i suoi <b>{tier}GB</b> di RAM e <b>{cpu}vCPU</b> bastano per la maggior parte dei progetti di questo tipo, con margine per i picchi di traffico.</>,
      min: m => <> I progetti più leggeri funzionano anche con il piano {m}.</>,
      pro: p => <> Per progetti più grandi, il piano {p} offre più RAM e CPU.</>
    },
    'ja': {
      q: <>{appType}にはどのプランを選べばよいですか？</>,
      rec: p => <>{p}プランをおすすめします。<b>{tier}GB</b>のRAMと<b>{cpu}vCPU</b>があれば、この種のプロジェクトの多くをトラフィックのピークにも余裕を持って動かせます。</>,
      min: m => <>軽量なプロジェクトは{m}プランでも動作します。</>,
      pro: p => <>より大規模なプロジェクトには、RAMとCPUが増える{p}プランをご検討ください。</>
    },
    'zh': {
      q: <>托管{appType}应该选择哪个套餐？</>,
      rec: p => <>我们推荐 {p} 套餐：<b>{tier}GB</b> RAM 和 <b>{cpu}vCPU</b> 足以运行大多数此类项目，并能从容应对流量高峰。</>,
      min: m => <>较轻量的项目也可以在 {m} 套餐上运行。</>,
      pro: p => <>对于更大的项目，{p} 套餐提供更多 RAM 和 CPU。</>
    }
  };
  const siteLang = t[lang] ? lang : 'en';
  const c = t[siteLang];
  const pay = (name, query) => <a href={`https://squarecloud.app/${siteLang}/pay?${query}`}>{name}</a>;
  const isPro = plan.toLowerCase() === 'pro';
  return <Note>
      <b>{c.q}</b><br />
      {c.rec(pay(plan, `plan=${plan.toLowerCase()}&tier=${tier}`))}
      {min ? c.min(pay(min, `plan=${min.toLowerCase()}`)) : null}
      {isPro ? null : c.pro(pay('Pro', 'plan=pro'))}
    </Note>;
};

export const appType_0 = "a Lavalink server"

## Introduction

To develop and host {appType_0} on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment.

### Prerequisites

* **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email.
* **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs.

<RecommendedPlan appType="Lavalink servers" plan="Standard" tier="4" cpu="4" min="Hobby" lang="en" />

This guide runs on the [Java runtime](/en/articles/getting-started-with-java).

## Get the project

Download `Lavalink.jar` from the [official releases page](https://github.com/lavalink-devs/Lavalink/releases). This guide uses Lavalink v4: pick the latest 4.x release (4.2.0 or newer), and make sure your bot uses a Lavalink client built for v4 that supports DAVE (see [Connect your bot](#connect-your-bot)).

<Info>
  We already have everything ready for deploy in our [lavalink-web releases](https://github.com/squarecloud-education/lavalink-web/releases), with the YouTube plugin set up. Download the `project.zip` and upload it: during the Lavalink deploy, replace the placeholder value of `LAVALINK_SERVER_PASSWORD` in the environment variables with a long random password.
</Info>

## Configure Lavalink

Create an `application.yml` file next to `Lavalink.jar`. The minimal configuration below listens on the port in the `PORT` environment variable (Square Cloud sets it to `80`) and plays YouTube through the official [youtube-source plugin](https://github.com/lavalink-devs/youtube-source), since the YouTube source built into Lavalink is deprecated:

```yaml application.yml theme={"system"}
server:
  port: ${PORT:80} # the PORT variable, or 80 when it isn't set
  address: 0.0.0.0
plugins:
  youtube:
    enabled: true
lavalink:
  plugins:
    # Latest version: https://github.com/lavalink-devs/youtube-source/releases
    - dependency: "dev.lavalink.youtube:youtube-plugin:1.18.2"
      snapshot: false
  server:
    password: "change-me-to-a-long-random-password"
    sources:
      youtube: false # replaced by the youtube-source plugin
```

Lavalink downloads the plugin on its first start. For every other option (other sources, filters, buffers), see the [official example file](https://github.com/lavalink-devs/Lavalink/blob/master/LavalinkServer/application.yml.example).

<Warning>Keep `address: 0.0.0.0` and don't replace the port with a fixed value other than `80`: Square Cloud delivers your subdomain's traffic to port `80` of your application.</Warning>

### Set a strong password

Replace the `password` value with a strong, random password of at least 32 characters. To keep it out of your files, set it in the `LAVALINK_SERVER_PASSWORD` environment variable instead: Lavalink gives [environment variables](https://lavalink.dev/configuration/) precedence over `application.yml`. Add the variable in the upload form's **Advanced configuration** or on your application's **Environment Variables** page in the dashboard, or from the CLI:

```bash theme={"system"}
squarecloud app env set LAVALINK_SERVER_PASSWORD=your_long_random_password
squarecloud app restart
```

See [Environment variables](/en/platform/environment-variables) for the other ways to manage them.

## Configure Square Cloud

Create a `squarecloud.app` file next to `Lavalink.jar`. The `SUBDOMAIN` field publishes your server at `https://<subdomain>.squareweb.app`:

```systemd squarecloud.app theme={"system"}
DISPLAY_NAME=Lavalink
MAIN=Lavalink.jar
MEMORY=1024
VERSION=recommended
SUBDOMAIN=my-lavalink
AUTORESTART=true
```

`MAIN=Lavalink.jar` makes Square Cloud start the server with `java -jar Lavalink.jar`, `MEMORY` is its RAM in MB, and `AUTORESTART=true` starts it again if it crashes (see [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/)).

## What goes in the ZIP

* `Lavalink.jar`
* `application.yml`
* `squarecloud.app`

Put the three files in the same folder and compress them into a `.zip` file to upload from the dashboard.

## Deploy and verify

### Via dashboard

<Steps>
  <Step title="Access the Upload Page">
    Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file.
  </Step>

  <Step title="Configure Your Environment">
    After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\
    If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project.
  </Step>

  <Step title="Deploy Your Project">
    Finally, click on the "Deploy" button to host your project on Square Cloud.\
    After deployment, you can monitor your project's status and logs from the dashboard.

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/dashboard/uploading.gif" alt="Uploading application to Square Cloud" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>

  <Step title="Confirm Your App Is Live">
    Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\
    If you deployed a website or API, open `https://<your-subdomain>.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online.
    <Tip>App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes.</Tip>
  </Step>
</Steps>

### Via CLI

To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application.

<Card title="Configuration file guide" icon="link" href="/en/getting-started/config-file">
  Learn how to create the `squarecloud.app` configuration file that defines your application's environment.
</Card>

<Steps>
  <Step title="Install the CLI">
    Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it:

    <CodeGroup>
      ```bash macOS, Linux, and WSL theme={"system"} theme={"system"}
      curl -fsSL https://cli.squarecloud.app/install | bash
      ```

      ```bash Windows with npm theme={"system"} theme={"system"}
      npm install -g @squarecloud/cli@latest
      ```
    </CodeGroup>
  </Step>

  <Step title="Log In">
    Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication).

    ```bash theme={"system"} theme={"system"}
    squarecloud auth login
    ```
  </Step>

  <Step title="Upload Your Project">
    From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it:

    ```bash theme={"system"} theme={"system"}
    squarecloud upload
    ```

    To upload a zip you created yourself, pass it with `--file`:

    ```bash theme={"system"} theme={"system"}
    squarecloud upload --file <path/to/zip>
    ```
  </Step>

  <Step title="Confirm Your App Is Live">
    Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal:

    ```bash theme={"system"} theme={"system"}
    squarecloud app status
    squarecloud app logs
    ```

    If you deployed a website or API, open `https://<your-subdomain>.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online.
    <Tip>App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes.</Tip>
  </Step>
</Steps>

## Connect your bot

Lavalink listens on port `80` inside Square Cloud, but your bot connects through the public edge, which serves HTTPS on port `443`. Configure the node in your Lavalink client like this (field names vary between libraries):

```javascript theme={"system"}
const node = {
  host: "my-lavalink.squareweb.app", // <subdomain>.squareweb.app
  port: 443,
  password: process.env.LAVALINK_PASSWORD, // the same password as the server
  secure: true,
};
```

<Warning>
  Since March 2026, Discord only lets bots into voice channels with DAVE, its end-to-end encryption for voice. Lavalink supports it from version 4.2.0, and your bot's Lavalink client must support it too: otherwise the bot connects to Lavalink but can't join a voice channel.
</Warning>

## Common errors

### The bot can't connect to Lavalink

Connecting with port `80` or `secure: false` fails: use port `443` and `secure: true`, as shown in [Connect your bot](#connect-your-bot). If the connection closes with code 1006, see [Lavalink connection closed with code 1006](/en/platform/troubleshooting/discord-bot-errors#lavalink-connection-closed-with-code-1006).

## Next steps

<CardGroup cols={3}>
  <Card title="Discord bot" icon="discord" href="/en/tutorials/bots/discord">
    Host the music bot that connects to your Lavalink server.
  </Card>

  <Card title="Discord bot errors" icon="triangle-exclamation" href="/en/platform/troubleshooting/discord-bot-errors">
    Fix invalid tokens, missing intents and Lavalink connection errors.
  </Card>

  <Card title="Java runtime" icon="java" href="/en/articles/getting-started-with-java">
    How Square Cloud runs Java applications.
  </Card>
</CardGroup>

For more about Lavalink, see the [official Lavalink documentation](https://lavalink.dev/).

## Contact us

If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.