# Setup Guide

URL: https://zerodev.ca/docs/medusa/setup

> Install Medusa, run the setup wizard and get your bot online.







Medusa is set up in the browser. You start it once, open the dashboard and a setup wizard walks you through the rest. There is nothing to fill in by hand.

## Before You Start

You need:

* A host that runs **Node.js 22** or newer, or **Bun**.
* An empty **PostgreSQL**, **MySQL** or **MariaDB** database.
* A Discord application with a bot, from the [Discord Developer Portal](https://discord.com/developers/applications).
* Your Medusa license key from the [Zero Development Discord](https://discord.zerodev.ca).

## Hosting

| Option                        | Best for                                                                                     |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| Game panel (Pterodactyl)      | The easiest choice. The panel keeps Medusa running and gives you a console and file manager. |
| Linux VPS or dedicated server | Full control. Use a process manager such as PM2 or systemd.                                  |
| Your own computer             | Testing and development.                                                                     |

[Haven Development](https://havendevelopment.net) hosts Medusa on Pterodactyl. Buying the Setup & Installation add-on on BuiltByBit gets you 15% off your hosting for as long as you keep it.

## Install

<Tabs items="[&#x22;Pterodactyl&#x22;, &#x22;Linux&#x22;, &#x22;Windows&#x22;]">
  <Tab value="Pterodactyl">
    1. Create a server with a Node.js 22 egg.
    2. Upload the Medusa files.
    3. Set the startup command to `node index.js`.
    4. Start the server.
  </Tab>

  <Tab value="Linux">
    1. Open a terminal in the Medusa folder.
    2. Run `npm install`.
    3. Run `node index.js`.

    To keep Medusa running after you close the terminal, use PM2:

    ```bash
    npm install -g pm2
    pm2 start index.js --name Medusa
    ```
  </Tab>

  <Tab value="Windows">
    1. Open PowerShell in the Medusa folder.
    2. Run `npm install`.
    3. Run `node index.js`.
  </Tab>
</Tabs>

On the first start Medusa creates `config.json`, builds the dashboard and serves it on port `3000`. It does not connect to Discord yet.

## Discord Application

Set these up in the [Discord Developer Portal](https://discord.com/developers/applications) before running the wizard.

### Privileged Intents

Every bot Medusa runs needs all three privileged intents.

1. Open your application and go to **Bot**.
2. Under **Privileged Gateway Intents**, turn on **Presence Intent**, **Server Members Intent** and **Message Content Intent**.
3. Click **Save Changes**.

<img alt="Privileged gateway intents" src="__img0" />

<Callout type="warn">
  Medusa will not start a bot with an intent turned off. It prints which ones are missing and stops. The wizard checks the token for you and shows the same steps.
</Callout>

### Sign-in Redirect

Go to **OAuth2** and add your dashboard address followed by `/api/auth/callback/discord` under **Redirects**:

* On your own computer: `http://localhost:3000/api/auth/callback/discord`
* On a domain: `https://medusa.example.com/api/auth/callback/discord`

<img alt="OAuth2 redirect" src="__img1" />

## Setup Wizard

Open `http://localhost:3000`, or your server's address on port `3000`. The wizard has these steps:

| Step        | What you enter                                                                    |
| ----------- | --------------------------------------------------------------------------------- |
| Welcome     | Nothing. If you used Medusa before, import your old configuration here.           |
| Bot         | Bot ID, bot token and your server ID. The token and intents are checked.          |
| License     | Your license key. The person who bought it becomes the dashboard owner.           |
| Database    | Type, host, port, user, password and database name. Click **Test Connection**.    |
| Discord App | Client ID and client secret from the **OAuth2** page. Click **Test Credentials**. |
| Branding    | Dashboard name, icon and accent color.                                            |
| Appearance  | Theme, accent and login layout.                                                   |
| Language    | The language for the bot and dashboard.                                           |
| Extras      | Console and logging options.                                                      |
| Updates     | Automatic updates, modules to exclude and modules to freeze.                      |
| Finish      | Review and click **Finish Setup**.                                                |

Medusa then saves your settings, activates the license, loads modules, connects to Discord and uploads its emojis. The wizard shows each stage with the live console and opens the dashboard when it is done. There is no restart.

The wizard remembers your progress in the browser, so a refresh or restart brings you back to the same step.

<Callout type="info">
  The license owner always has full access. Use the **Permissions** page to give other staff access. See [Core](/docs/medusa/modules/core#ranks).
</Callout>

## Hosting on a Domain

Point a reverse proxy at each port, then set **Dashboard URL** and **API URL** under **Settings > Server URLs**. Pick yours:

<ReverseProxy sites="[{ domain: &#x22;medusa.example.com&#x22;, port: 3000 }, { domain: &#x22;api.medusa.example.com&#x22;, port: 3001 }]" />

<Callout type="warn">
  The dashboard URL, the address in your browser and the redirect in the Developer Portal must all match. If they do not, sign-in fails with `Invalid origin`.
</Callout>

## Signing In

Open the dashboard and click **Continue with Discord**. Staff only see the pages their rank allows.