Calagopus

Appearance

Setting up your Development Environment ​

This guide walks through setting up a development environment for creating extensions for the Calagopus Panel.

Prerequisites ​

Before you begin, ensure you have the following installed on your machine:

  • Node.js (version 24 or higher)
  • pnpm (version 11 or higher)
  • Rust (latest stable version)
  • A code editor (e.g., Visual Studio Code)
  • Git (any reasonable version)
  • A PostgreSQL server (version 16 or higher) for the database
  • A Redis server (version 7 or higher) for caching

Installing the Panel Locally ​

Step 1: Clone the Repository ​

Clone the Calagopus Panel repository:

bash
git clone https://github.com/calagopus/panel.git calagopus-panel
cd calagopus-panel

Step 2: Install Dependencies ​

Install the dependencies with pnpm:

bash
# Frontend dependencies
cd frontend
pnpm install
cd ..

# Database dependencies (technically optional)
cd database
pnpm install
cd ..

Step 3: Set Up Environment Variables ​

Copy the .env.example file to .env and modify it as needed:

bash
cp .env.example .env

Configure PostgreSQL/Redis and your app encryption keys in the .env file.

Step 4: Build the Project ​

Run the following from the root directory:

bash
# build frontend, required to build the backend
cd frontend
pnpm build
cd ..

# migrate database
SQLX_OFFLINE=true cargo run -p database-migrator -- migrate

# build & run backend
SQLX_OFFLINE=true cargo run

Step 5: Running the Development Server ​

With a working backend, run the frontend development server:

bash
cd frontend
pnpm dev

# start dev server on port 8081
# pnpm dev --port 8081

# backend is on port 9999
# BACKEND_PORT=9999 pnpm dev

By default, the frontend is available at http://localhost:5173; the dev server proxies API requests to the backend at http://localhost:8000. If your backend uses a different port, set the BACKEND_PORT environment variable.

Updating the Development Environment ​

Pull the latest changes from the main repository:

bash
rm Cargo.lock frontend/pnpm-lock.yaml # remove lockfiles to avoid git conflicts
git pull # if there are additional conflicts, resolve them here

Then rebuild the project:

bash
# build frontend, required to build the backend
cd frontend
pnpm install # install any new dependencies
pnpm build
cd ..

# migrate database
SQLX_OFFLINE=true cargo run -p database-migrator -- migrate

# build & run backend
SQLX_OFFLINE=true cargo run