Automatic Installation

Guide to installing PteroCA using an automated Bash script that downloads and configures all required components.

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

To facilitate a seamless installation experience, we've developed an automated Bash installer that streamlines the entire setup process. It automatically detects your operating system, installs all required dependencies, configures your environment, and deploys the PteroCA panel with minimal user input.

Additionally, the installer now offers optional Pterodactyl Panel installation — fully automated, including default node creation, API key generation, and automatic integration with PteroCA. This allows you to set up a complete, production-ready environment in a single run.

🎥 Video Guide

---

1. Execute the installer

💡 Now supports all-in-one setup! The installer can now automatically install PteroCA and (optionally) the Pterodactyl Panel in a single run. It will also fully configure Pterodactyl automatically – including creating the default node, generating the API key, and importing both into PteroCA for instant integration.

⚙️ PteroCA Plugin for Pterodactyl

If you’re using your own existing Pterodactyl instance, make sure the PteroCA Plugin is installed. Without it, certain PteroCA integration features will not be available. 📖 Follow this guide or watch the video tutorial to install the plugin manually.

🧩 If you’re installing Pterodactyl via our autoinstaller, the plugin is installed automatically - no manual action required.

bash -c "$(wget -qO- https://pteroca.com/installer.sh)"

Requirements & Supported OS

Operating System: Ensure your server is running a supported OS:

• Ubuntu 24.04 (Noble)

• Ubuntu 22.04 (Jammy)

• Debian 13 (Trixie)

• Debian 12 (Bookworm)

• Debian 11 (Bullseye)

• Rocky Linux 10

• Rocky Linux 9

• Rocky Linux 8

• AlmaLinux 10

• AlmaLinux 9

• AlmaLinux 8

• CentOS Stream 10

• CentOS Stream 9

Root Access: The installation must be executed with root privileges.

Recommended for fresh systems: This installer works best on clean servers without existing web services or custom configurations. If you have existing services, consider using Manual Installation to avoid potential conflicts.

1.1 Using Installer with Custom Parameters

If you prefer to run the installer manually or automate deployments (e.g. with Ansible, CI/CD, or VPS provisioning scripts), the Bash script supports advanced flags that allow full control over the installation process.

CLI Parameters Reference

Required Parameters (when using --yes non-interactive mode)

• -p, --php-version <VERSION> – PHP version to install (8.2, 8.3, 8.4)

• -d, --domain <DOMAIN> – Your panel's domain (e.g., panel.example.com) [optional - if empty, uses port 80]

• -m, --config-method <METHOD> – Configuration method: web or cli

General Flags

• --yes, -y – Enables non-interactive mode (no questions asked)

• --ssl – Forces SSL certificate generation (domain must be live)

• --no-ssl – Skips SSL (no HTTPS setup)

• --staging – Uses staging Let's Encrypt certificates (for testing)

• --disable-telemetry - Disables telemetry data collection during and after installation

Pterodactyl Installation Parameters

• --install-pterodactyl – Installs Pterodactyl Panel alongside PteroCA

• --pterodactyl-subdomain <SUBDOMAIN> – Subdomain for Pterodactyl (e.g., panel.example.com)

  • If not provided, Pterodactyl will use port 8000

• --pterodactyl-admin-email <EMAIL> – Pterodactyl administrator email

• --pterodactyl-admin-username <USERNAME> – Pterodactyl administrator username

• --pterodactyl-admin-password <PASSWORD> – Pterodactyl administrator password

Usage Examples

1. Basic PteroCA Installation (PteroCA only)

bash installer.sh --yes \
  --php-version 8.3 \
  --domain pteroca.example.com \
  --config-method web \
  --ssl

2. PteroCA Installation without Domain (localhost)

bash installer.sh --yes \
  --php-version 8.3 \
  --domain "" \
  --config-method web \
  --no-ssl

3. PteroCA + Pterodactyl (with Pterodactyl subdomain)

bash installer.sh --yes \
  --php-version 8.3 \
  --domain pteroca.example.com \
  --config-method web \
  --ssl \
  --install-pterodactyl \
  --pterodactyl-subdomain panel.example.com \
  --pterodactyl-admin-email [email protected] \
  --pterodactyl-admin-username admin \
  --pterodactyl-admin-password SecurePass123

4. PteroCA + Pterodactyl (Pterodactyl on port 8000)

bash installer.sh --yes \
  --php-version 8.3 \
  --domain pteroca.example.com \
  --config-method web \
  --ssl \
  --install-pterodactyl \
  --pterodactyl-admin-email [email protected] \
  --pterodactyl-admin-username admin \
  --pterodactyl-admin-password SecurePass123

5. Test Installation with Staging Certificates

bash installer.sh --yes \
  --php-version 8.3 \
  --domain test.example.com \
  --config-method web \
  --ssl \
  --staging \
  --install-pterodactyl \
  --pterodactyl-admin-email [email protected] \
  --pterodactyl-admin-username admin \
  --pterodactyl-admin-password TestPass123

Important Notes

• Required in non-interactive mode (--yes):

  • --php-version

  • --domain (can be empty "" for localhost)

  • --config-method

• Pterodactyl Installation:

  • If you don't provide --pterodactyl-subdomain, Pterodactyl will be accessible on port 8000

  • Admin parameters (--pterodactyl-admin-*) are optional - if not provided, they will be auto-generated

• SSL:

  • --ssl requires a live domain pointing to your server

  • --staging is useful for testing (avoids Let's Encrypt rate limits)

  • Without --ssl or --no-ssl, the script will ask interactively

• Domains:

  • PteroCA and Pterodactyl cannot use the same domain

  • Valid configuration example:

    • PteroCA: pteroca.example.com

    • Pterodactyl: panel.example.com or port 8000

---

2. Automatic Installation Process

🧩 Optional Pterodactyl Installation During the setup, the script may ask whether you want to install Pterodactyl Panel alongside PteroCA. If you choose y (yes), the installer will automatically handle the entire Pterodactyl setup — including all dependencies, configuration, node creation, and API key generation — and then import those details into PteroCA. The process closely mirrors the PteroCA installation flow, so you can follow the same steps confidently.

The script will guide you through the PteroCA installation process, allowing you to choose between two configuration methods:

• Web Wizard – A user-friendly web-based setup wizard that simplifies the configuration process.

• CLI Wizard – A fully interactive command-line setup for users who prefer a terminal-based approach.

Both methods will prompt you to enter essential details, including PHP version selection, domain configuration, Pterodactyl API credentials, and admin account credentials for PteroCA.

Example installation process workflow with Web Wizard

1. Run the installer:

root@test:~# bash -c "$(wget -qO- https://pteroca.com/installer.sh)"

Starting PteroCA installation... 
Detected OS: ubuntu 22.04 (jammy)

Available PHP versions:
1. PHP 8.2
2. PHP 8.3
3. PHP 8.4 

Select PHP version [1-3]: 1 
Selected PHP version: 8.2

Basic Configuration 
Enter your domain (e.g., panel.example.com): test.pteroca.com

Adding PHP repository... [...]
Adding MariaDB repository... [...]
Updating package manager... [...]
Installing dependencies... [...]
Installing Composer... [...]
Configuring services... [...]
Running mysql_secure_installation... [...]
Setting up database... [...]
Setting up PteroCA application... [...]
Cloning PteroCA repository... [...]
Installing Composer dependencies... [...]
Creating environment configuration... [...]
Verifying database connection... [...]
Executing PteroCA Database Migrations... [...]
Configuring PHP-FPM... [...]
Looking for PHP-FPM configuration... [...]
Configuring NGINX... [...]
Setting up SSL certificate... [...]
Setting up CRON jobs... [...]
Configuring PteroCA application... [...]

Select the initial configuration method:
1) Web Wizard (recommended)
2) CLI
Enter your choice [1-2]: 1

Web Wizard selected. Please complete the configuration via the web interface.
Open your browser and navigate to: https://test.pteroca.com/first-configuration}
 
Performing final checks...

PteroCA installation completed successfully!

Installation Summary:
Domain: test.pteroca.com
PHP Version: 8.2
OS: ubuntu 22.04
Panel URL: https://test.pteroca.com

Database Credentials:
Database Name: pteroca
Database User: pteroca
Database Password: [database password]
Database Host: localhost
MySQL Root Password: [mysql root password]

Credential Files:
MySQL Root Password: /root/.pteroca_mysql
Environment File: /var/www/pteroca/.env

Next Steps: Complete the Initial Configuration
The installation is complete, but you still need to configure your PteroCA instance.
To finalize the setup, please visit the Web Wizard and follow the instructions:
Open your browser and go to: https://test.pteroca.com/first-configuration


Important:
1. Save these credentials in a secure location
2. Configure your firewall to allow ports 80 and 443 (if needed)

Thank you for installing PteroCA!

1. Navigate to [yourdomain]/first-configuration in your browser. Select your preferred language and click "Start" to begin the setup process.

   

   Welcome page of web wizard
2. Follow the guided steps to complete the configuration, providing details such as site settings, Pterodactyl API credentials, email configuration, and the credentials for the first admin account. If you encounter any issues filling in the required information, refer to the System Configuration guide for assistance.

3. Configure Pterodactyl and install PteroCA Plugin for Pterodactyl

Example installation process workflow with CLI wizard

1. Run the installer:

   root@test:~# bash -c "$(wget -qO- https://pteroca.com/installer.sh)"
   
   Starting PteroCA installation... 
   Detected OS: ubuntu 22.04 (jammy)
   
   Available PHP versions:
   1. PHP 8.2
   2. PHP 8.3
   3. PHP 8.4 
   
   Select PHP version [1-3]: 1 
   Selected PHP version: 8.2
   
   Basic Configuration 
   Enter your domain (e.g., panel.example.com): test.pteroca.com
   
   Adding PHP repository... [...]
   Adding MariaDB repository... [...]
   Updating package manager... [...]
   Installing dependencies... [...]
   Installing Composer... [...]
   Configuring services... [...]
   Running mysql_secure_installation... [...]
   Setting up database... [...]
   Setting up PteroCA application... [...]
   Cloning PteroCA repository... [...]
   Installing Composer dependencies... [...]
   Creating environment configuration... [...]
   Verifying database connection... [...]
   Executing PteroCA Database Migrations... [...]
   Configuring PHP-FPM... [...]
   Looking for PHP-FPM configuration... [...]
   Configuring NGINX... [...]
   Setting up SSL certificate... [...]
   Setting up CRON jobs... [...]
   Configuring PteroCA application... [...]
   
   Select the initial configuration method:
   1) Web Wizard (recommended)
   2) CLI
   Enter your choice [1-2]: 2
   
   Do you want to configure system settings? (yes/no) [yes]:
    > yes
    
   Do you want to set site settings? (yes/no) [yes]:
    > yes
    
   Site URL [http://localhost]:
    > https://test.pteroca.com
    
   Do you want to set email settings? (yes/no) [yes]:
    > no
    
   Do you want to configure pterodactyl panel credentials? (yes/no) [yes]:
    > yes
    
   Pterodactyl Panel URL [http://localhost]:
    > https://pterodactylexampleurl.com
   
   Pterodactyl Panel API Key []:
    > mypterodactylapikey
    
   Do you want to configure payment settings? (yes/no) [yes]:
    > no
    
   Do you want to create user? [yes]:
    > yes
    
   User e-mail []:
    > [email protected]
    
   User password []:
    > TestPassword$
    
   Is user admin? (yes/no) [yes]:
    > yes
    
   Performing final checks...
   
   PteroCA installation completed successfully!
   
   Installation Summary:
   Domain: test.pteroca.com
   PHP Version: 8.2
   OS: ubuntu 22.04
   Panel URL: https://test.pteroca.com
   
   Database Credentials:
   Database Name: pteroca
   Database User: pteroca
   Database Password: [database password]
   Database Host: localhost
   MySQL Root Password: [mysql root password]
   
   Credential Files:
   MySQL Root Password: /root/.pteroca_mysql
   Environment File: /var/www/pteroca/.env
   
   Important:
   1. Save these credentials in a secure location
   2. Configure your firewall to allow ports 80 and 443 (if needed)
   
   Thank you for installing PteroCA!

2. Configure Pterodactyl and install PteroCA Plugin for Pterodactyl.

Based on your inputs, the script will:

• Install Dependencies: Set up necessary repositories and install required packages, including Nginx, PHP and MariaDB.

• Configure Services: Set up and secure the database, configure the web server, and ensure all services are running correctly.

• Deploy PteroCA: Download the latest version of PteroCA, configure environment settings, and set appropriate file permissions.

Upon successful installation, the script will provide: Access URL, Admin Credentials and Database Credentials.

If your PteroCA instance is running behind Cloudflare, you need to adjust your configuration to avoid CSRF and host validation issues. Please follow the instructions here: Trusted Proxies & Cloudflare.

More about the PteroCA configuration process during installation can be found in System Configuration.

---

Post-Installation Steps

After completing the installation, configure the following to ensure full functionality:

1. 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

If you installed Pterodactyl using our autoinstaller, the plugin is already installed. Otherwise, follow the installation guide:

👉 Install PteroCA Plugin for Pterodactyl

2. 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.

3. Complete System Configuration

Configure your panel settings through the CLI wizard or 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

---

Getting Help

If you encounter issues during automatic installation:

1. Check the documentation:

   • Review Installation Troubleshooting

   • See Common installation errors

2. Gather information before asking for help:

   • Installation log output (copy the full terminal output)

   • Your operating system: cat /etc/os-release

   • Selected options (PHP version, domain, configuration method)

3. Get support:

   • Discord (fastest): Join our Discord community and share your error

   • GitHub: Open an issue on GitHub with installation logs

---

🎉 Installation Complete!

Enjoying PteroCA? Help us grow by giving us a star on GitHub! ⭐

👉 Star PteroCA on GitHub