PanelAlpha Engine

• Lost API Token
• Installation Issues During PanelAlpha Engine Setup
• Cannot Connect PanelAlpha to Engine
• Docker Containers Not Starting Properly
• Performance Issues with PanelAlpha Engine
• Missing www Alias for Instances Hosted on Engine
• Restoring MySQL Database Dump
• WP CLI Usage
• Orphaned vhost Configs After Account Deletion
• General Troubleshooting Steps

Lost API Token

Problem: I have lost my PanelAlpha Engine API token and need to regenerate it.

Solution: Log in to your engine server via SSH as the root user and run the following command:

docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml exec core php artisan api-token:create tokenname

Installation Issues During PanelAlpha Engine Setup

Problem: Errors occur during PanelAlpha Engine installation. The installer (installer.sh) performs preflight checks before deploying containers and aborts with specific messages when a requirement is not met. Common log entries include:

• Please run as root! — the installer was not invoked as the root user (exit code 101).
• Unsupported operating system. Supported systems: Debian GNU/Linux 12/13, Ubuntu 22.04/24.04. Detected system: <OS> <VER> — the server runs an OS outside the supported list.
• Unable to determine the hostname of your system!. Please consult the documentation for your system. — the system hostname could not be resolved.
• The license key is invalid. <MSG> — the supplied license key was rejected by the licensing service.
• Invalid license status: <status>. — the license exists but is not in an active state.
• Error has been occurred. <MESSAGE> — a network-level failure occurred while downloading the engine package.
• Error has been occurred. Cannot find package. It should be in path: /opt/panelalpha/tmp/engine/app.zip — the package download did not produce the expected file at /opt/panelalpha/tmp/engine/app.zip.
• <BASH_COMMAND> command failed with exit code <N> — a downstream command (for example docker compose up or a database migration) failed. This commonly wraps port conflicts such as bind: address already in use on ports 80, 443, 2011 (and 53), 21, 30000–30009, and 2222.
• Waiting for initdb to complete... (repeated) — the installer is waiting for the database to accept connections; the loop exits once the connection test returns "Test successful".

Note on logs: The installer does not write a dedicated log file — all output goes to stdout/stderr. To capture it, run the installer with output redirected, for example:

bash installer.sh 2>&1 | tee installer.log

Logs for the updater (separate from the installer) are written to /opt/panelalpha/log/engine-updates/<RUN_ID>/.

Solution:

• Verify your server meets all requirements listed in the PanelAlpha Engine documentation, including a supported OS and root access.
• Check that ports 80, 443, 2011, 21, 30000–30009, and 2222 are open and not already bound (also free port 53 if a local resolver is running).
• Make sure your license key is valid, active, and properly formatted.
• Confirm the server hostname resolves (hostname -f) before starting the installer.
• If the package download fails, verify outbound network connectivity to the PanelAlpha distribution endpoint.

Cannot Connect PanelAlpha to Engine

Problem: Having trouble connecting PanelAlpha to your Engine server.

Solution:

• Verify the API token is correctly entered in the server configuration.
• Ensure PanelAlpha can reach the engine server on port 2011.
• Check that SSL verification settings match your server configuration.

Docker Containers Not Starting Properly

Problem: Docker containers are failing to start on the Engine server.

Solution:

• Verify the Docker service is running on your server.
• Use docker logs to check for error messages in container logs.
• Ensure sufficient disk space is available for containers.

Performance Issues with PanelAlpha Engine

Problem: Experiencing slow performance or resource-related issues. Check docker stats; investigate when CPU > 90% or RAM > 90% is sustained.

Solution:

• Monitor CPU, RAM, and disk usage on your engine server.
• Verify Docker container resource limits are appropriate for your workload.
• Check Redis configuration and ensure caching is properly configured if enabled.

Missing www Alias for Instances Hosted on Engine

Problem: Instances hosted on PanelAlpha Engine may be missing a www domain alias, causing services to be unreachable at addresses like www.example.com.

Solution: Run the following on the Engine server to add missing www aliases:

# Add missing www aliases for all users
docker compose exec core php artisan users:add-missing-www-domain-aliases --all

# Add missing www aliases for a specific user
docker compose exec core php artisan users:add-missing-www-domain-aliases --username=<USERNAME>

After running the command, verify DNS and wait for DNS propagation.

Restoring MySQL Database Dump

Problem: You need to restore a MySQL database dump for a WordPress instance hosted on PanelAlpha Engine.

Warning: Restoring a database dump overwrites the current database. Back up the current state before restoring.

Solution:

1. Get the database connection details from the PanelAlpha Client Area:

   • Navigate to your instance in the Client Area.
   • Go to Advanced settings.
   • Note the hostname, username, and database name.

2. Access the Engine server via SSH and enter the user's container:

   # Replace {username} with the actual username
   docker exec -it {username} bash
   

3. Run the MySQL restore command inside the container:

   mysql -h hostname -u username -p database_name < dump_file.sql
   

   Replace:

   • hostname — with the database hostname from Client Area Advanced settings
   • username — with the database username from Client Area Advanced settings
   • database_name — with the database name from Client Area Advanced settings
   • dump_file.sql — with the path to your SQL dump file

   You will be prompted to enter the database password, which can also be found in the Client Area Advanced settings.

WP CLI Usage

Problem: You need to execute WP CLI commands on WordPress instances hosted on PanelAlpha Engine.

Solution: PanelAlpha Engine supports running WP CLI commands on specific user instances using Docker. Use the following command structure:

docker exec -u www-data username php /opt/wp-cli.phar --path=/home/username/domain.com/public_html COMMAND

Command Components:

• docker exec — Executes a command in a running Docker container
• -u www-data — Runs the command as the www-data user (WordPress file owner)
• username — The container name (same as the instance username)
• php /opt/wp-cli.phar — Executes the WP CLI PHP archive
• --path=/home/username/domain.com/public_html — Specifies the WordPress installation path
• COMMAND — The actual WP CLI command you want to run

Example:

Get WordPress information:

docker exec -u www-data username php /opt/wp-cli.phar --path=/home/username/domain.com/public_html --info

Important Notes:

• Replace username and domain.com with actual values from the instance.
• Commands run as www-data user to maintain proper file permissions.
• The instance container must be running to execute commands.
• All standard WP CLI commands are supported.

Orphaned vhost Configs After Account Deletion

Problem: Nginx, Apache, or LiteSpeed fails to reload after an account was removed outside the normal deletion flow, affecting all sites on the engine.

Deleting an account through the API (DELETE /api/users/{username}) or the artisan command (users:delete {username}) removes the user's webserver vhost configuration files automatically.

If an account was removed manually (for example, by deleting database rows directly), the vhost .conf files may be left behind. Because those configs can reference SSL certificate files that were also removed, the webserver may fail to reload and affect all sites on the engine.

Solution: Run the rebuild command from the engine host:

docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml exec -T core php artisan users:rebuild --all --wipe-vhosts-dir

This wipes the vhosts directory and regenerates configuration files only for accounts that still exist in the database.

General Troubleshooting Steps

Problem: Unable to resolve Engine-related issues with the above solutions.

Solution: Collect diagnostics before escalating:

1. List running containers and their state:

   docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml ps
   

2. Inspect recent core service logs:

   docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml logs core --tail 200
   

3. Check application log files under /opt/panelalpha/shared-hosting/.../logs/ (and the PanelAlpha app logs under /opt/panelalpha/app/.../logs/) for detailed error messages.
4. Double-check all configuration settings in both PanelAlpha and the Engine.
5. Contact our technical support team (opens new window) with the command output, specific error messages, and system details.

For more information about PanelAlpha Engine setup and configuration, refer to the complete PanelAlpha Engine documentation.