System Configuration

Configure core system settings including site information, email, Pterodactyl integration, payment, security, theme, and plugin settings.

Overview

PteroCA provides two ways to manage system configuration:

1. CLI Configuration Wizard - Interactive command-line tool for initial setup

2. Admin Panel Settings - Web interface for ongoing configuration management

The CLI wizard (pteroca:system:configure) is designed for first-time installation and covers essential settings. After installation, you can manage all settings through the Admin Panel's Settings menu, which provides access to all 51 configuration options across 7 categories.

Configuration Categories

PteroCA organizes settings into seven categories, each accessible through the Admin Panel:

General Settings

Configure core site settings including URL, title, locale, server lifecycle, and integrations.

• Settings: Site URL, title, locale, telemetry, server deletion, PHPMyAdmin

• CLI Coverage: Site URL, title, locale

• Admin Panel: Settings → General

View General Settings Documentation

Theme Settings

Customize the appearance of your PteroCA panel including branding, colors, dark mode, and MOTD.

• Settings: Logo, favicon, theme selection, colors, dark mode, MOTD

• CLI Coverage: None (Admin Panel only)

• Admin Panel: Settings → Appearance

View Theme Settings Documentation

Security Settings

Configure security features including email verification, CAPTCHA, and Terms of Service.

• Settings: Email verification, Google reCAPTCHA, Terms of Service

• CLI Coverage: None (Admin Panel only)

• Admin Panel: Settings → Security

View Security Settings Documentation

Payment Settings

Set up payment processing with Stripe and configure currencies.

• Settings: Stripe API keys, payment methods, currency configuration

• CLI Coverage: Stripe key, currencies

• Admin Panel: Settings → Payment Gateways

View Payment Settings Documentation

Email Settings

Configure SMTP settings for sending system emails, notifications, and renewal reminders.

• Settings: SMTP server, port, credentials, sender address, renewal notifications

• CLI Coverage: SMTP settings (5 settings)

• Admin Panel: Settings → Email

View Email Settings Documentation

Pterodactyl Settings

Configure integration with Pterodactyl panel including API, SSO, and server management.

• Settings: Pterodactyl URL, API key, SSO, server logs, use as client panel

• CLI Coverage: URL, API key

• Admin Panel: Settings → Pterodactyl

View Pterodactyl Settings Documentation

Plugin Settings

Manage configuration settings for installed plugins.

• Settings: Dynamic (varies by installed plugins)

• CLI Coverage: None (Admin Panel only)

• Admin Panel: Settings → Plugins

View Plugin Settings Documentation

Configuration Methods

CLI Configuration Wizard

The CLI wizard is an interactive command-line tool for initial system setup.

When to use:

• First-time installation

• Automated deployments

• Bulk reconfiguration

• When Admin Panel is not accessible

Command:

cd /var/www/pteroca
php bin/console pteroca:system:configure

Coverage: The wizard covers 13 essential settings across site, email, Pterodactyl, payment, and user creation.

Note: The old command name app:configure-system is deprecated but still works until v1.0.0.

Admin Panel Settings

The Admin Panel provides a comprehensive web interface for managing all settings.

When to use:

• After initial installation

• Day-to-day configuration changes

• Settings not covered by CLI wizard

• When you need visual feedback

Access:

1. Log in to the Admin Panel

2. Navigate to Settings in the main menu

3. Select the category you want to configure

4. Update values and click Save

Comparison

Feature	CLI Wizard	Admin Panel
Settings Coverage	13 essential settings	All 51 settings
Use Case	Initial setup	Ongoing management
Interface	Command line	Web interface
Automation	Easy to script	Manual
Visual Feedback	Limited	Full UI with validation
Field Types	Text input only	All types (color picker, image upload, etc.)
Testing	Limited	Built-in test features (SMTP test, etc.)

Prerequisites

Before configuring your PteroCA system:

• Database: Database must be configured and migrations run (Database Setup)

• Pterodactyl API Key: Created with all read & write permissions (API Configuration)

• SMTP Credentials: If using email features

• Stripe Credentials: If accepting payments

• Web Server: Properly configured (Web Server Setup)

Quick Start

First-Time Setup (CLI Wizard)

1. Ensure prerequisites are met

2. Run the configuration wizard:

   php bin/console pteroca:system:configure

3. Follow the interactive prompts

4. Verify settings in Admin Panel

5. Configure additional settings not covered by CLI wizard

Updating Existing Configuration

Via Admin Panel:

1. Navigate to Settings → [Category]

2. Update the value

3. Click Save

Via CLI:

# Re-run configuration wizard
php bin/console pteroca:system:configure

Post-Configuration Checklist

After initial configuration, verify your setup:

• Admin Panel Access - Log in and verify you can access all sections

• Email Delivery - Send a test email (Settings → Email → Test SMTP Connection)

• Pterodactyl Connection - Verify API connection is working

• Payment Processing - Test a payment transaction (use Stripe test mode)

• Security Settings - Configure CAPTCHA and email verification as needed

• Theme Customization - Customize colors and branding

• Create User Roles - Set up custom roles for your team (Access Control)

Common Workflows

Fresh Installation

1. Run CLI wizard for initial setup:

   php bin/console pteroca:system:configure

2. Configure security settings via Admin Panel (CAPTCHA, email verification)

3. Customize theme and branding

4. Set up additional payment methods if needed

5. Configure plugin settings

6. Create user roles and permissions

Rebranding Your Panel

1. Navigate to Settings → General

2. Update site title

3. Navigate to Settings → Appearance

4. Upload new logo and favicon

5. Customize theme colors

6. Navigate to Settings → Security

7. Update Terms of Service if needed

Switching Email Providers

1. Navigate to Settings → Email

2. Update SMTP server, port, and credentials

3. Update sender address

4. Click "Test SMTP Connection" to verify

5. Save changes

Enabling SSO with Pterodactyl

1. Configure Pterodactyl addon (Pterodactyl Addon Installation)

2. Navigate to Settings → Pterodactyl

3. Enable SSO

4. Generate and save SSO secret key

5. Test SSO login flow

Configuration File Locations

Settings are stored in two locations:

Environment Variables (.env)

• App environment (APP_ENV: dev, prod)

• Debug mode (APP_DEBUG)

• CloudFlare settings (if applicable)

• Other environment-specific variables

Database (setting table)

• All system settings (51 total)

• Site URL, title, and locale

• Email (SMTP) configuration

• Pterodactyl URL and API key

• Payment settings (Stripe)

• Security settings

• Theme and appearance

• Plugin configurations

Note: Settings configured via CLI wizard or Admin Panel are stored in the database with a 24-hour cache for performance.

Troubleshooting

For category-specific troubleshooting, see the dedicated documentation pages:

• General Settings Troubleshooting

• Email Settings Troubleshooting

• Pterodactyl Settings Troubleshooting

• Payment Settings Troubleshooting

• Security Settings Troubleshooting

• Theme Settings Troubleshooting

General Issues

CLI Command Fails to Run

Error: Command not found or permission denied

Solutions:

# Make console executable
chmod +x bin/console

# Run with explicit PHP
php bin/console pteroca:system:configure

Database Connection Error

Error: Cannot connect to database

Solutions:

1. Verify database is configured: Database Setup

2. Check .env file has correct DATABASE_URL

3. Test database connection:

   php bin/console doctrine:query:sql "SELECT 1"

Settings Not Saving

Error: Changes don't persist after save

Solutions:

1. Check file permissions on cache directory

2. Clear application cache:

   php bin/console cache:clear

3. Verify database connectivity

4. Check browser console for JavaScript errors

Related Documentation

• Access Control - User roles and permissions

• Pterodactyl Integration - Complete Pterodactyl setup guide

• CLI Commands - All available commands

Additional Resources

• Plugin Development - Learn how plugins can add custom settings

• Theme Development - Customize your panel's appearance

• Security Best Practices - Secure your installation