Setup Guide

This guide walks you through setting up Medusa from a fresh copy to a running instance with its web dashboard and database connected.

Hosting Options

Haven Development (Official Hosting Partner - Recommended)

Haven Development is Zero Development's official hosting partner. They offer optimized Discord bot and Node.js hosting with:

• Instant automated provisioning with modern Pterodactyl control panel.
• Native Node.js v22+ support with custom port allocations for the Medusa Dashboard and API.
• Enterprise DDoS protection and high-bandwidth network connectivity.
• Built-in web console, file manager, automated backups, and one-click restarts.
• Managed PostgreSQL database add-ons ready for Medusa.

Read our complete Haven Development Hosting Guide for step-by-step setup on Haven.

VPS / Dedicated Server

Best for administrators who prefer full root access to Linux systems (Ubuntu 22.04/24.04 or Debian 12). You can manage Medusa using process managers like PM2 or systemd services alongside a local or remote PostgreSQL cluster.

Self-Hosting (Local Development)

Suitable for testing, local module development, or initial configuration on macOS, Windows, or Linux.

Requirements

• Node.js v22 (LTS) or newer (or Bun). Verify with node -v.
• PostgreSQL 14 or newer.
• A Discord Application with Bot Token from the Discord Developer Portal.
• A valid Medusa License Key from Zero Development.

Step 1: Discord Application Setup

1. Navigate to the Discord Developer Portal and click New Application.
2. Name your application (e.g. Medusa) and save.
3. Open the Bot tab:
   • Click Add Bot (or Reset Token) to generate your Bot Token. Save this securely.
   • Under Privileged Gateway Intents, enable:
     • Presence Intent
     • Server Members Intent
     • Message Content Intent
4. Open the OAuth2 tab:
   • Copy the Client ID.
   • Reset and copy the Client Secret.
   • Under Redirects, add your dashboard callback URL: http://localhost:3000/api/auth/callback/discord (or https://your-domain.com/api/auth/callback/discord in production).
5. Generate an invite link under OAuth2 -> URL Generator:
   • Scopes: bot, applications.commands
   • Bot Permissions: Administrator (or select specific management permissions)
   • Open the generated URL in your browser to invite Medusa to your Discord server.

Step 2: Installation

Step 3: Configure config.json

Open config.json in your Medusa directory and populate the required settings:

{
  "LICENSING": {
    "AGREE_TO_LICENSE.MD": true,
    "LICENSE_KEY": "YOUR_LICENSE_KEY_HERE"
  },
  "AUTHENTICATION": {
    "DISCORD_CLIENT_ID": "123456789012345678",
    "DISCORD_CLIENT_SECRET": "your_discord_client_secret",
    "SECRET": "generate_a_random_32_byte_hex_string"
  },
  "SETUP_USER": "your_personal_discord_user_id",
  "DATABASE": {
    "TYPE": "POSTGRES",
    "HOST": "localhost",
    "PORT": "5432",
    "USER": "admin",
    "PASSWORD": "your_database_password",
    "DATABASE": "Medusa"
  },
  "SERVER": {
    "DASHBOARD": {
      "PORT": 3000,
      "URL": null,
      "DEVELOPER": false
    },
    "API": {
      "PORT": 3001,
      "URL": null,
      "LOGS": true
    }
  }
}

Setting Explanations

• AGREE_TO_LICENSE.MD: Must be set to true to accept the license agreement.
• LICENSE_KEY: Your product key provided by Zero Development upon purchase.
• DISCORD_CLIENT_ID: Your application client ID from Discord Developer Portal.
• DISCORD_CLIENT_SECRET: Your application client secret from Discord Developer Portal.
• SECRET: A secret encryption key used for session security and API tokens.
• SETUP_USER: Your personal Discord User ID (numeric string). This account is granted root administrator access upon first login.
• DATABASE: PostgreSQL connection parameters.
• SERVER.DASHBOARD.PORT: The web port Medusa uses for the dashboard interface (default 3000).
• SERVER.API.PORT: The port Medusa uses for internal REST API communication (default 3001).

Step 4: First Boot

Run node index.js to start Medusa.

On startup, Medusa validates your configuration, verifies your license key, connects to PostgreSQL, establishes the REST API and Dashboard servers, loads all 22 modules, and connects to Discord.

  [ 09-13-2026 ~ 12:00am ] [ SRT ] ███╗   ███╗███████╗██████╗ ██╗   ██╗███████╗ █████╗ 
  [ 09-13-2026 ~ 12:00am ] [ SRT ] ████╗ ████║██╔════╝██╔══██╗██║   ██║██╔════╝██╔══██╗
  [ 09-13-2026 ~ 12:00am ] [ SRT ] ██╔████╔██║█████╗  ██║  ██║██║   ██║███████╗███████║
  [ 09-13-2026 ~ 12:00am ] [ SRT ] ██║╚██╔╝██║██╔══╝  ██║  ██║██║   ██║╚════██║██╔══██║
  [ 09-13-2026 ~ 12:00am ] [ SRT ] ██║ ╚═╝ ██║███████╗██████╔╝╚██████╔╝███████║██║  ██║
  [ 09-13-2026 ~ 12:00am ] [ SRT ] ╚═╝     ╚═╝╚══════╝╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝
  [ 09-13-2026 ~ 12:00am ] [ SRT ] Developed by Zero Development
  [ 09-13-2026 ~ 12:00am ] [ SRT ] Medusa v1.0.0.0 has finished booting!
  
  * Dashboard: http://localhost:3000
  * API: http://localhost:3001
  * Core ✔ Loaded!
  * Moderation ✔ Loaded!
  * Ticket ✔ Loaded!

Open your browser to http://localhost:3000 (or your assigned server IP/port) to access the Medusa web dashboard.