Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/thenoname-gurl/EcliPanel/llms.txt

Use this file to discover all available pages before exploring further.

EcliPanel ships as two separate processes — a Bun/Elysia REST API (the backend) and a Next.js application (the frontend) — plus one or more wings-rs nodes that execute server workloads. This guide walks you through installing every component on a fresh Linux host. Complete each section in order; the backend must be running before you register your first wings node, and the frontend must be configured to point at the backend before users can sign in.
EcliPanel is built against wings-rs (calagopus/wings). Do not use the stock Pterodactyl wings-go daemon — most features will not work and the panel will behave incorrectly.

​
Prerequisites

Before you begin, ensure the following are installed on your host:
DependencyPurposeMinimum version
BunBackend runtime and package manager1.x
Node.jsOptional — only needed if you pre-compile with build.sh20 LTS
pnpmFrontend package manager8.x
MariaDBPrimary relational database10.6+
RedisSession cache and queue7.x
ffmpegAudio processing for captchaany
espeakText-to-speech for audio captchaany
ffmpeg and espeak are only required if you enable the audio captcha feature (CAPTCHA_SECRET / CAPTCHA_INVISIBLE_SECRET). You can skip them and add them later.
Install the system packages on Debian/Ubuntu: 
sudo apt update
sudo apt install -y mariadb-server redis-server ffmpeg espeak
Install Bun: 
curl -fsSL https://bun.sh/install | bash
Install pnpm: 
npm install -g pnpm

​
Installation steps

1

Install wings-rs

Follow the installation instructions in the calagopus/wings repository to build and configure the node agent on each server host. Complete the wings configuration first, then return here to finish the panel setup. After the backend and frontend are running you will register each node from the admin panel.
2

Clone the repository

Clone EcliPanel to your preferred path. The examples below use /srv/eclipanel — adjust to match your environment.
git clone https://github.com/thenoname-gurl/EcliPanel.git /srv/eclipanel
cd /srv/eclipanel
3

Set up the backend

Move into the backend directory and install dependencies:
cd /srv/eclipanel/backend
bun install
Copy the example environment file and open it for editing:
cp .env.example .env
nano .env
See the environment variable reference for every available option. At minimum you must set DB_HOST, DB_USER, DB_PASS, DB_NAME, PORT, FRONTEND_URL, PANEL_URL, JWT_SECRET, and NODE_ENCRYPTION_KEY.Generate the required secrets with the built-in helper scripts:
# Generates JWT_SECRET and NODE_ENCRYPTION_KEY and prints them
bun run gen:jwt-secret

# Generate NODE_PQ_ENCRYPTION_SEED separately
bun -e "console.log((await import('crypto')).randomBytes(64).toString('base64'))"
Copy each printed value into the corresponding variable in .env.
Never reuse or hard-code secrets. Treat JWT_SECRET, NODE_ENCRYPTION_KEY, and NODE_PQ_ENCRYPTION_SEED like passwords — store them securely and rotate them if they are ever exposed.
Seed the default role (rootAdmin) into the database:
bun run gen:default-role
4

Set up the frontend

Move into the frontend directory and install dependencies:
cd /srv/eclipanel/frontend
pnpm install
Copy the example environment file and edit it:
cp .env.example .env
nano .env
The frontend .env controls how the Next.js process reaches the backend and Wings nodes at build time and runtime. Set the following variables:
VariableDescription
BACKEND_URLInternal URL the Next.js server uses to proxy API requests, e.g. http://localhost:4000
NEXT_PUBLIC_API_BASEPublic-facing API base URL shown to browsers
NEXT_PUBLIC_WINGS_BASEPublic-facing Wings base URL for WebSocket proxying
Optionally edit lib/panel-config.ts to update branding (panel name, logo path, tagline) and enable or disable feature flags:
nano lib/panel-config.ts
5

Promote your first admin user

Register an account through the panel, then promote it to rootAdmin from the backend directory:
cd /srv/eclipanel/backend
bun run promote -- admin@example.com
You can pass an explicit role as a second argument if needed:
bun run promote -- admin@example.com rootAdmin
6

Start both services

Backend — run directly with Bun (recommended):
cd /srv/eclipanel/backend
./start.sh
The backend starts on the port defined by PORT in .env (default 4000).Frontend — build and start in production mode:
cd /srv/eclipanel/frontend
bun run build
./start.sh --port 3000
The frontend listens on port 3000 by default and proxies /api/* requests to the backend and /wings/* to the Wings node via the rewrites defined in next.config.mjs.

​
Next steps

For a production deployment you should run both services under systemd and expose them behind an Nginx reverse proxy. See Deploy EcliPanel with systemd for unit file installation instructions and a suggested Nginx configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us