Skip to main content

Getting Started

Pelican Panel is designed to run on your webserver.

You are expected to read through our documentation. We have spent a lot of time curating these docs for the community, so please take some time to read through them before asking for help on the forums!

danger

You should have some basic familiarity with Linux before you proceed!

warning

Pelican is currently in Beta! Some things might change / break between beta versions!

Picking an Operating System (OS)​

Pelican runs on a wide range of operating systems, so pick whichever you are most comfortable using. Note: Other OS's, not listed below, might still work.

warning

OpenVZ, unless specifically configured, will not work with Pelican.

Operating SystemVersionSupportedNotes
Ubuntu20.04⚠️︎No SQLite Support, Ubuntu 20.04 EoL is April 2025, not recommended
22.04✅︎
24.04✅︎Documentation written assuming Ubuntu 24.04 as the base OS.
Rocky Linux9✅︎
Debian11⚠️No SQLite Support
12✅︎

SQLite support depends on libsqlite3-0_3.35+ being on the host system. Ubuntu 20.04 & Debian 11 do not meet this requirement.

Dependencies​

warning

The ondrej/php repository is required to install the latest versions of PHP and its required extensions.

It can be added with the following command alongside PHP and the extensions.

sudo add-apt-repository ppa:ondrej/php
sudo apt -y install php8.3-fpm php8.3-{gd,mysql,mbstring,bcmath,xml,curl,zip,intl,sqlite3}
  • PHP 8.3 (recommended) or 8.2 with the following extensions: gd, mysql, mbstring, bcmath, xml, curl, zip, intl, sqlite3 and fpm
  • MySQL 8 (mysql-server) or MariaDB 10.3+
  • A webserver (Apache, NGINX, Caddy, etc.)
  • curl
  • tar
  • composer v2

Installing Composer​

Composer is a dependency manager for PHP, You'll need composer installed before continuing in this guide.

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Create Directories & Downloading Files​

The first step in this process is to create the folder where the panel will live and then move ourselves into that newly created folder.

mkdir -p /var/www/pelican
cd /var/www/pelican

Once you have created a new directory to use and moved into it you'll need to download the Panel files. This is as simple as using curl to download the latest release.

curl -L https://github.com/pelican-dev/panel/releases/latest/download/panel.tar.gz | sudo tar -xzv

Once the archive gets downloaded and unpacked you'll need to set the correct permissions on the storage/ and bootstrap/cache/ directories.

chmod -R 755 storage/* bootstrap/cache/

Installation​

Next we will set up the default environment settings file, dependencies, and then generate a new application encryption key.

sudo composer install --no-dev --optimize-autoloader

Environment Configuration​

The core environment is easily configured using a few different CLI commands built into the app. This step will cover setting up things such as sessions, caching, database credentials, and email sending.

Running php artisan p:environment:setup will, if it does not exist, auto create the required .env file and generate a APP_KEY.

info

Make sure to read the MySQL guide first if you want to use MySQL instead of SQLite!

php artisan p:environment:setup
php artisan p:environment:database

Setting up Mail - Optional​

If you'd like to set up the panel to send emails for newly created servers to users & password resets. Use this command.

php artisan p:environment:mail
warning

Back up your encryption key (APP_KEY in the .env file). This is used as an encryption key for all data that needs to be stored securely (e.g. api keys). Store it somewhere safe - not just on your server. If you lose it all encrypted data is irrecoverable -- even if you have database backups.

Database Initialization​

Now we need to set up database for the Panel that you created before. The command below may take some time to run depending on your machine. Please DO NOT exit the process until it is completed!

php artisan migrate --seed --force

Creating User​

You'll then need to create an administrative user so that you can log into the panel. To do so, run the command below.

Passwords must meet the following requirements: 8 characters, mixed case, at least one number.

php artisan p:user:make

Crontab Configuration​

We need to create a new cronjob that runs every minute to process specific tasks, such as session cleanup and scheduled tasks. You'll want to open your crontab.

sudo crontab -e -u www-data

And then paste the line below.

* * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1

Setting Permissions​

The last step in the installation process is to set the correct permissions on the Panel files so that the webserver can use them correctly.

chown -R www-data:www-data /var/www/pelican