Calagopus

Appearance

Migrating from Pelican (Standalone) ​

This guide is for Pelican installs that run directly on the host - no Docker, no containers. If you're using Docker, head to the Dockerized guide instead.

The plan: install Calagopus alongside your existing Pelican, point the importer at Pelican's .env file, let it read everything from Pelican's database, and write equivalent records into Calagopus's fresh database. Your users log in with the same credentials afterwards.

A reminder of what doesn't migrate: API keys. See the intro for the full reasoning - the short version is that the hashes aren't compatible and the API isn't either, so old keys wouldn't work even if we did import them.

Prerequisites ​

Before you start, you'll want:

  • Your Pelican .env file accessible (you'll point the importer at it)
  • Calagopus Panel installed but not yet configured - we need to land on the Out-of-Box Experience (OOBE) screen and stop there
  • Access to the database Pelican is using (MySQL, MariaDB, or SQLite3)

Install Calagopus First ​

If you haven't installed Calagopus yet, follow the installation guide to get it running. Once you reach the OOBE screen, stop. Don't click through it. Don't create the admin user. Just leave it on that screen and come back here.

Don't click through the OOBE

The importer needs an empty Calagopus database to write into. The OOBE creates initial records (admin user, default settings) that would conflict with what the importer wants to do.

Calagopus Panel OOBE

I already clicked through - how do I undo it?

You'll need to drop and recreate the database. Pick the matching tab for how Calagopus is installed:

Head to the directory with your Calagopus compose file and stop the stack:

bash
docker compose down

Delete the Postgres data directory:

bash
# This wipes the Calagopus database. Don't run this if you have data you care about.
rm -r postgres

Start Calagopus back up:

bash
docker compose up -d

Supported Pelican Databases ​

The importer can read from any of these database backends:

  • mysql
  • mariadb
  • sqlite
  • sqlite3

The connection details come from Pelican's .env file - you don't need to type them in separately, just point the importer at the file with --environment and it figures the rest out.

MySQL or MariaDB ​

Your Pelican .env should have entries like:

sh
APP_URL=https://panel.example.com
APP_KEY=base64:...
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=pelican
DB_USERNAME=pelican
DB_PASSWORD=secret

Nothing special to do here - the importer reads these directly.

SQLite3 ​

Your Pelican .env should have entries like:

sh
APP_URL=https://panel.example.com
APP_KEY=base64:...
DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite

If DB_DATABASE is a relative path (the default), the importer resolves it relative to the location of the .env file you pass. So as long as your Pelican install hasn't been moved around, you don't need to do anything.

Choose Your Calagopus Install Method ​

The exact import command depends on how Calagopus itself is installed. Pick the matching tab and follow along:

Copy Pelican's .env file into the Calagopus container. Assuming Pelican is at /var/www/pelican:

bash
docker compose cp /var/www/pelican/.env web:/.env

If Pelican is using SQLite3, also copy the database file in:

bash
docker compose cp /var/www/pelican/database/database.sqlite web:/database.sqlite

Then run the importer:

bash
docker compose exec web calagopus-panel import pelican --environment /.env

The import will chew through users, servers, nodes, allocations, eggs, and so on. How long it takes depends on how much data Pelican has - small installs finish in seconds, large ones can take a few minutes. Progress is logged to stdout.

If the import errors out

Treat the database as poisoned. Partial imports leave Calagopus in an inconsistent state. Drop the Postgres data (the steps in the OOBE warning callout above), let Calagopus recreate it empty, and re-run the import.

When the import finishes, restart the stack:

bash
docker compose down
docker compose up -d

Log in with your existing Pelican credentials.

What's Next ​

Don't forget the node side. Calagopus uses Wings as its node agent, but it needs to be pointed at the new panel rather than the old one. See Wings - Updating for the swap.

After that, regenerate any API keys your external scripts were using. The old Pelican keys won't work and the API itself is different anyway, so you're rewriting those scripts regardless.