Medusa/Configuration

Configuration

What lives in config.json and what lives on the dashboard.

Medusa keeps very little in files. config.json holds what it needs before it can reach the database. Everything else is saved in the database and changed on the dashboard.

config.json

Medusa creates config.json in its folder on the first start, and the setup wizard fills in the database for you.

config.json

{
    "AUTHENTICATION": {
        "SECRET": "generated-on-first-start"
    },
    "DATABASE": {
        "TYPE": "POSTGRES",
        "HOST": "localhost",
        "PORT": "5432",
        "USER": "medusa",
        "PASSWORD": "your-password",
        "DATABASE": "medusa"
    },
    "SERVER": {
        "DASHBOARD": { "PORT": 3000, "URL": null, "DEVELOPER": false },
        "API": { "PORT": 3001, "URL": null, "LOGS": true }
    }
}

AUTHENTICATION

Key	Default	What it does
`SECRET`	Random	Signs dashboard sessions and internal API requests. Generated on the first start. Changing it signs everyone out.

DATABASE

Key	Default	What it does
`TYPE`	`POSTGRES`	`POSTGRES`, `MYSQL` or `MARIADB`.
`HOST`	Empty	Database server address.
`PORT`	`5432`	Database port. MySQL and MariaDB usually use `3306`.
`USER`	Empty	Database user.
`PASSWORD`	Empty	Database password.
`DATABASE`	Empty	Database name. Medusa creates its own tables.

Medusa installs the right database driver itself the first time it connects.

SERVER

Key	Default	What it does
`DASHBOARD.PORT`	`3000`	Port the dashboard listens on.
`DASHBOARD.URL`	`null`	Public dashboard address, such as `https://medusa.example.com`. Leave `null` on your own computer.
`DASHBOARD.DEVELOPER`	`false`	Serves the dashboard through Vite with hot reloading. For development only.
`API.PORT`	`3001`	Port the API listens on.
`API.URL`	`null`	Public API address, used for sign-in callbacks, webhooks and the appeal page.
`API.LOGS`	`true`	Kept for older installs. Currently unused.

URL takes a full address or a bare hostname, which is treated as HTTPS. Leave off any path or trailing slash. The URLs and ports can also be changed under Settings > Server URLs.

Older installs had LICENSING, SETUP_USER and Discord app keys in config.json. Medusa moves the license key and Discord app credentials into the database on start, and the dashboard owner now comes from the license. The old keys can be deleted.

Dashboard Settings

Everything else is on the dashboard and applies without a restart.

Where	What
Settings	License key, bot token, primary and authorized server IDs, Discord app credentials, language, console, updates, appearance, branding, login screen, placeholders, server URLs, API keys and allowed IPs.
Bot	Presence, profile and additional bots.
Modules	Turn modules on or off.
Configs	Each module's settings.
Commands	Rename, turn off or add text prefixes to commands.
Lang	Change any message or embed in any language.
Logging	Log channels for each module's events.
Permissions	Ranks and what they can use. See Core.

Settings > Configuration Transfer exports all of this to a file and imports it into another Medusa install. Secrets are left out of the export, and channels and roles are matched by name on import.

PreviousDashboard NextOverview