# Getting Started

Chloridpanel is designed to run on your own web server(Not Strato/Hostinger/your alternative web hosts, you need either a VPS or a Dedicated machine). You will need to have root access to your server in order to run and use this panel.

You are expected to understand how to read documentation to use this Panel. We have spent many hours detailing how to install or upgrade our software; take some time and read rather than copy and pasting and then complaining when things do not work. This panel does not exist as a drag-and-drop service to run your servers. It is a highly complex system requiring multiple dependencies and administrators willing to spend some time learning how to use it. If you expect to be able to install this with no understanding of basic linux system administration you should stop and turn around now.

# Picking a Server OS

Chloridpanel runs on a wide range of operating systems, so pick whichever you are most comfortable using.

WARNING

Chloridpanel does not support most OpenVZ systems due to incompatibilities with Docker. If you are planning on running this software on an OpenVZ based system you will — most likely — not be successful, you will not recieve any support from us.

Operating System Version Supported Notes
Ubuntu 22.04 ✅ Requires additional repositories for PHP
24.04 ✅ MariaDB can be installed without the repo setup script.
26.04 ✅
RHEL / Rocky Linux / AlmaLinux 8 ✅ Extra repos are required.
9 ✅
Debian 11 ✅ Debian Dependencies
12 ✅ Debian Dependencies
13 ✅ Debian Dependencies

# Dependencies

  • PHP 8.2-8.4 or 8.5 (recommended) with the following extensions: cli, openssl, gd, mysql, PDO, mbstring, tokenizer, bcmath, xml or dom, curl, zip, and fpm if you are planning to use NGINX.
  • MySQL 5.7.22 and higher (MySQL 8 recommended) or MariaDB 10.2 and higher(recommended over MySQL).
  • Redis (redis-server)
  • A webserver (Apache, NGINX, Caddy, etc.)
  • curl
  • tar
  • unzip
  • git
  • composer v2

# Example Dependency Installation

The commands below are simply an example of how you might install these dependencies. Please consult with your operating system's package manager to determine the correct packages to install.

    # Installing Composer

    Composer is a dependency manager for PHP that allows us to ship everything you'll need code wise to operate the Panel. You'll need composer installed before continuing in this process.

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

    # Download 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. Below is an example of how to perform this operation.

    mkdir -p /var/www/chloridpanel
cd /var/www/chloridpanel

    Once you have created a new directory for the Panel and moved into it you'll need to download the Panel files. This is as simple as using curl to download our pre-packaged content. Once it is downloaded you'll need to unpack the archive and then set the correct permissions on the storage/ and bootstrap/cache/ directories. These directories allow us to store files as well as keep a speedy cache available to reduce load times.

    curl -Lo panel.tar.gz https://github.com/chloridpanel/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/

    # Installation

    Now that all the files have been downloaded we need to configure some core aspects of the Panel.

    Database Configuration

    You will need a database setup and a user with the correct permissions created for that database before continuing any further. See below to create a user and database for your Chloridpanel panel quickly. To find more detailed information please have a look at Setting up MySQL.

    # If using MariaDB (v11.0.0+) (This is the default when installing Chloridpanel by following the documentation.)
mariadb -u root -p

# If using MySQL
mysql -u root -p

    
# Remember to change 'yourPassword' below to be a unique password
CREATE USER 'chloridpanel'@'127.0.0.1' IDENTIFIED BY 'yourPassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'chloridpanel'@'127.0.0.1' WITH GRANT OPTION;
exit

    First we will copy over our default environment settings file, install core dependencies, and then generate a new application encryption key.

    cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader

# Only run the command below if you are installing this Panel for
# the first time and do not have any Chloridpanel data in the database, otherwise, you'd not get your data back if you didn't backup your key.
php artisan key:generate --force

    DANGER

    Back up your encryption key (APP_KEY in the .env file). It 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 with database backups.

    To grab your APP_KEY, open a terminal and run the following in your panel directory:

    grep APP_KEY /var/www/chloridpanel/.env

    You should see something like:

    APP_KEY=base64:YOUR_LONG_RANDOM_STRING

    Copy that entire line and save it somewhere secure:

    • A password manager
    • An encrypted file on your local machine
    • A secure USB drive
    • A trusted cloud vault

    Do not keep it only on the server. If you lose this key, your encrypted data is permanently unrecoverable.

    # Environment Configuration

    Chloridpanel's 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.

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

# To use PHP's internal mail sending (not recommended), select "mail". To use a
# custom SMTP server, select "smtp".
php artisan p:environment:mail

    # Database Setup

    Now we need to setup all the base data for the Panel in the database you created earlier. The command below may take some time to run depending on your machine. Please DO NOT exit the process until it is completed! This command will setup the database tables and then add all the Nests & Eggs that power Chloridpanel.

    php artisan migrate --seed --force

    # Add The First 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. At this time passwords must meet the following requirements: 8 characters, mixed case, at least one number.

    php artisan p:user:make

    # Set 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.

    # If using NGINX, Apache or Caddy (not on RHEL / Rocky Linux / AlmaLinux)
chown -R www-data:www-data /var/www/chloridpanel/*

# If using NGINX on RHEL / Rocky Linux / AlmaLinux
chown -R nginx:nginx /var/www/chloridpanel/*

# If using Apache on RHEL / Rocky Linux / AlmaLinux
chown -R apache:apache /var/www/chloridpanel/*

    # Queue Listeners

    We make use of queues to make the application faster and handle sending emails and other actions in the background. You will need to setup the queue worker for these actions to be processed.

    # Crontab Configuration

    The first thing we need to do is create a new cronjob that runs every minute to process specific Chloridpanel tasks, such as session cleanup and sending scheduled tasks to daemons. You'll want to open your crontab using sudo crontab -e and then paste the line below.

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

    # Create Queue Worker

    Next you need to create a new systemd worker to keep our queue process running in the background. This queue is responsible for sending emails and handling many other background tasks for Chloridpanel.

    Create a file called chlorid.service in /etc/systemd/system with the contents below.

    # Chloridpanel Queue Worker File
# ----------------------------------

[Unit]
Description=Chloridpanel Queue Worker
After=redis-server.service

[Service]
# On some systems the user and group might be different.
# Some systems use `apache` or `nginx` as the user and group.
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/chloridpanel/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s

[Install]
WantedBy=multi-user.target

    Redis on RHEL / Rocky Linux / AlmaLinux

    If you are using RHEL, Rocky Linux, or AlmaLinux, you will need to replace redis-server.service with redis.service at the After= line in order to ensure redis starts before the queue worker.

    TIP

    If you are not using redis for anything you should remove the After= line, otherwise you will encounter errors when the service starts.

    If you are using redis for your system, you will want to make sure to enable that it will start on boot. You can do that by running the following command:

    sudo systemctl enable --now redis-server

    Finally, enable the service and set it to boot on machine start.

    sudo systemctl enable --now chlorid.service

    # Next Step: Webserver Configuration

    Help us improve this page. (opens new window)