Manual Installation

Step-by-step instructions for manually installing PteroCA, including server setup, dependencies, and panel deployment.

Please note, this project is currently in an early version (0.x.x) and may contain bugs. Use it at your own risk.

It is beneficial to have some prior knowledge of Linux and MariaDB before starting this installation, as this will help ensure a smoother setup process.

To manually install PteroCA, follow the instructions below.

---

1. System requirements

To install and run PteroCA.com, you'll need to have the following dependencies installed on your system:

PHP and Extensions

• PHP 8.2 or higher

• Required PHP extensions: cli, ctype, iconv, mysql, pdo, mbstring, tokenizer, bcmath, xml, curl, zip, intl, fpm (if using NGINX)

Database

• MySQL 5.7.22 or higher (MySQL 8 recommended) OR

• MariaDB 10.2 or higher

Additional Tools

• Git (optional)

• Tar & Unzip

• Composer v2 (Dependency Manager for PHP)

• Curl

---

Example Dependency Installation

Below is an example of how you might install the required dependencies on a Debian or Ubuntu-based system. These commands assume you're using PHP 8.2 and installing MariaDB and NGINX:

# Add "add-apt-repository" command
apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg

# Add additional repositories for PHP and MariaDB (for Debian 11 and Ubuntu 22.04)
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash

# Update repositories list
apt update

# Add universe repository if you are on Ubuntu 18.04
apt-add-repository universe

# Install Dependencies
apt -y install php8.2 php8.2-{cli,ctype,iconv,mysql,pdo,mbstring,tokenizer,bcmath,xml,intl,fpm,curl,zip} mariadb-server nginx tar unzip git

---

Composer

If you already have Composer installed, you can skip this step!

Composer is a powerful dependency manager for PHP. It allows us to handle and install all the necessary libraries and packages that your project needs. Before proceeding, make sure you have Composer installed on your server.

To install Composer globally, run the following command:

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

This will install Composer globally on your machine, making it accessible from anywhere by running the composer command.

Once installed, verify it by running:

composer -v

This should print the installed Composer version.

---

2. Download files

There are two ways to obtain the PteroCA source code manually:

Option A - Download from Git

This installation way is recommended for Developers.

The first step to getting PteroCA.com running is to set up the directory where the panel will be installed. You will then clone the repository directly from our GitHub and install required composer dependencies.

Here’s an example of how to create a directory for the panel and navigate into it:

# Create a directory for PteroCA and move into it
mkdir -p /var/www/pteroca && cd /var/www/pteroca

# Clone the PteroCA repository into the newly created directory
git clone https://github.com/PteroCA-Org/panel.git ./

# Install composer dependecies
composer install --no-dev --optimize-autoloader

This command will create a new folder at /var/www/pteroca, clone the PteroCA codebase, and place all the necessary files into this directory.

Once the repository is cloned, you're ready to proceed with the setup process.

---

Option B - Download from GitHub Release

If you don't want to install Git, you can manually download the latest stable version from GitHub Releases:

1. Visit https://github.com/PteroCA-Org/panel/releases

2. Download the latest .zip or .tar.gz archive under Assets

3. Upload it to your server (e.g. via SFTP or SCP)

4. Extract the archive into your web directory:

   mkdir -p /var/www/pteroca && cd /var/www/pteroca
   tar -xzf /path/to/pteroca-release.tar.gz --strip-components=1
   # or if using zip:
   unzip /path/to/pteroca-release.zip -d .

5. Install Composer dependencies:

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

---

3. Set permissions

The final step in the installation process is to set the correct permissions on project files. This ensures that the web server can properly read and write to the necessary directories, such as logs, cache, and file uploads.

You should restrict web server ownership only to the directories that require write access, such as var/ and public/uploads/. This helps to avoid exposing sensitive files to unnecessary access.

# NGINX or Apache on Ubuntu/Debian (or similar):
chown -R www-data:www-data /var/www/pteroca/var/ /var/www/pteroca/public/uploads/

# NGINX on CentOS:
chown -R nginx:nginx /var/www/pteroca/var/ /var/www/pteroca/public/uploads/

# Apache on CentOS:
chown -R apache:apache /var/www/pteroca/var/ /var/www/pteroca/public/uploads/

This ensures that only the directories requiring write access (var/ and public/uploads/) are owned by the web server user, while the rest of the project remains protected.

Now, set the correct permissions for these directories, allowing the web server to write to them.

chmod -R 775 /var/www/pteroca/var/ /var/www/pteroca/public/uploads/

This ensures that the web server user can read, write, and execute in these directories, while other users can only read and execute.

---

4. Crontab configuration

To ensure that critical tasks, such as billing users hourly or suspending unpaid servers, are processed correctly, you need to set up a cron job that runs every minute. This cron job will automatically execute the necessary commands for maintaining your Dashboard.

Open Crontab

Run the following command to edit your crontab configuration:

crontab -e

If prompted to select a text editor, choose your preferred option (typically option 1).

Add the cron job

Scroll to an empty line without a # at the beginning, then add the following entry:

# Recommended (v0.6+)
* * * * * php /var/www/pteroca/bin/console pteroca:cron:schedule >> /dev/null 2>&1

# Deprecated (still works until v1.0.0)
# * * * * * php /var/www/pteroca/bin/console app:cron-job-schedule >> /dev/null 2>&1

Important: Use pteroca:cron:schedule for new installations. The old command name app:cron-job-schedule is deprecated and will be removed in v1.0.0.

Save the changes in your editor and close it. The cron job is now active and will run automatically every minute.

---

Post-Installation Steps

After completing the installation, follow these steps to get PteroCA up and running:

1. Database Setup

Configure your database connection and create the required tables.

👉 Database Setup Guide

2. Environment Configuration

Set up your .env file with essential configuration like APP_SECRET and database credentials.

👉 Web Server Configuration (includes environment setup)

3. Initial Configuration

Choose one of the following methods to configure your PteroCA panel:

Option A: Web Wizard (Recommended)

Access the web-based configuration wizard:

• Navigate to https://your-domain.com/first-configuration

• Follow the guided setup process

• Configure site settings, email, and Pterodactyl integration

Option B: CLI Wizard

Configure via command line:

php bin/console pteroca:system:configure

This interactive wizard will guide you through all necessary configuration steps.

👉 System Configuration Guide for detailed settings information

4. Install PteroCA Plugin for Pterodactyl

Required for full integration

The PteroCA Plugin must be installed in your Pterodactyl panel to enable features like:

• Server console access

• Real-time statistics

• Server variable management

• SSO authentication

👉 Install PteroCA Plugin for Pterodactyl

5. Configure Allowed Origins (Console Access)

For the server console to work properly, you need to configure allowed_origins in your Pterodactyl Wings configuration.

This allows PteroCA to communicate with Pterodactyl Wings for console access and real-time server management.

👉 Configure Allowed Origins

You can configure allowed origins at any time - it doesn't need to be done immediately during installation.

6. Additional Configuration (Optional)

Fine-tune your panel settings through the Admin Panel:

• General Settings - Site title, logo, locale

• Email Settings - SMTP configuration for notifications

• Payment Settings - Stripe integration for payments

• Pterodactyl Settings - API connection and SSO setup

👉 View all configuration options