Setup Guide

This guide takes you from a fresh copy of Kora to a running instance.

Hosting Options

Self-Hosting (Local Machine)

Best for development, testing, or environments that do not require 24/7 uptime. Running Kora on your local machine (Windows, macOS, or Linux) is free and allows for quick configuration changes and debugging.

VPS / VDS / Dedicated Server

Best for production deployments requiring full system control, dedicated resources, and 24/7 uptime. Providers like DigitalOcean, Hetzner, Linode, and Contabo offer virtual private servers where you can run Kora using process managers like PM2 or systemd. This option requires basic familiarity with Linux command-line administration.

Pterodactyl Game & Bot Panels

The most convenient and automated hosting method. Pterodactyl panels provide a web interface with integrated console access, browser-based file management, automatic crash recovery, and simple startup controls without requiring server management experience.

Requirements & Dependencies

Kora installs its own dependencies with npm install, and it automatically installs the right database driver for you the first time it connects, so there are no extra build tools to set up.

First Run

The first time you start Kora, it creates your configuration file at config/config.json and then stops, asking you to accept the license:

Please read & agree to the LICENSE.md to continue using Kora.

That's expected. Open config/config.json and fill in the settings below, then start Kora again.

Configuration

1. Get your license

Every instance needs a license key from Zero Development. It's what lets Kora start up and unlocks add‑ons like the dashboard. To get your key, open a ticket in the 「🎫」open-a-ticket channel of the Zero Development Discord. Then, in config/config.json, under LICENSE:

• Set AGREE_TO_LICENSE.MD to true to accept the license.
• Paste your key into LICENSE_KEY.

2. Choose your runtime

Under KORA, set ENVIRONMENT to match how you're running Kora:

• NODEJS: the standard choice.
• BUN: only if you're running Kora with Bun.

3. Set up your database

Kora stores everything in a SQL database. Create an empty database on your PostgreSQL, MySQL, or MariaDB server, then fill in the DATABASE section:

• TYPE: POSTGRES, MYSQL, or MARIADB.
• HOST / PORT: where your database server is.
• USER / PASSWORD: the login Kora should use.
• DATABASE: the name of the database you created.

4. Set your API port and URL

Under KORA, PORT is the port Kora listens on (default 3000). Change it if that port is already in use on your host. It must be free and different from the dashboard's port; Kora refuses to start if the port is already taken.

URL is the public URL of your Kora server (e.g. https://api.yoursite.com). It is the address your customers' integrations call, so they reach your server instead of localhost; see the Core API Reference. Leave it empty during local setup.

5. Branding (optional)

Under DASHBOARD.CUSTOMIZE you can personalize how Kora appears in the dashboard:

• BRAND_NAME: your product or company name.
• ICON: a URL to your logo.
• ACCENT_COLOR: a hex color (e.g. #4DABF7) for buttons, links, and highlights.
• THEME: the dashboard color scheme: dark, light, or auto.
• RADIUS: how rounded the dashboard's corners are (xs through xl).
• FONT: a font family for the dashboard (leave empty for the default).
• CUSTOM_CSS: extra CSS for fine‑grained styling (leave empty for none).

After everything is filled in, your config/config.json should look something like this:

{
    "LICENSE": {
        "AGREE_TO_LICENSE.MD": true,
        "LICENSE_KEY": "XXXXX-XXXXX-XXXXX-XXXXX"
    },
    "KORA": {
        "PORT": 3000,
        "URL": "",
        "ENVIRONMENT": "NODEJS",
        "AUTO_UPDATE": true,
        "TRUST_PROXY": "",
        "CONSOLE": {
            "SECONDS": false,
            "12_HOURS": true,
            "DEBUG": false,
            "CLI": true
        },
        "API_KEY": [
            { "NAME": "Default", "VALUE": "keep-this-secret" }
        ],
        "RATELIMIT": {
            "COOLDOWN": "60s",
            "TIMEFRAME": "5s",
            "REQUESTS": "50"
        }
    },
    "AUTHENTICATION": {
        "DISCORD_ID": "",
        "DISCORD_SECRET": "",
        "GOOGLE_ID": "",
        "GOOGLE_SECRET": "",
        "GITHUB_ID": "",
        "GITHUB_SECRET": "",
        "EMAIL_PASSWORD": true,
        "AUTH_SECRET": "auto-generated-for-you",
        "ADMINS": []
    },
    "DASHBOARD": {
        "ENABLE": false,
        "DEV_MODE": false,
        "PORT": 3001,
        "URL": "http://localhost:3001",
        "CUSTOMIZE": {
            "BRAND_NAME": "Kora",
            "ICON": "https://example.com/icon.png",
            "ACCENT_COLOR": "#4DABF7",
            "THEME": "dark",
            "RADIUS": "md",
            "FONT": "",
            "CUSTOM_CSS": ""
        }
    },
    "SMTP": {
        "HOST": "",
        "PORT": "587",
        "SECURE": false,
        "USER": "",
        "PASSWORD": "",
        "FROM": ""
    },
    "DATABASE": {
        "TYPE": "POSTGRES",
        "HOST": "localhost",
        "PORT": "5432",
        "USER": "admin",
        "PASSWORD": "password",
        "DATABASE": "Kora",
        "MIGRATE": true
    }
}

Start it up

With your config saved, start Kora again (npm start, or start the server in your panel). This time it will validate your license, connect to your database, and come online. A successful start ends with a banner like:

     Kora v1.0.3.0 has finished booting! (took 1.42s)

Finalizing

• Start Kora once so it creates your config file.
• Fill in your settings in config/config.json (license, database, port, runtime).
• Restart Kora.
• You're online! 🎉