Note: This documentation is still in progress, not reviewed properly, and might contain some errors or outdated images. It's intended for the upcoming 4.0.0 release, so configuration settings might be different from previous versions.

Manual Installation

This page describes the manual installation procedure for Poweradmin. While using the installer is recommended for most users, manual installation can be useful for automated deployments or advanced users.

Prerequisites

Verify that your setup meets the application requirements. For detailed requirements, including PHP version, required extensions, and supported databases, see System Requirements.

Installation Steps

1. Prepare the Environment

Unpack the Poweradmin archive in a location accessible via your web server. Ensure unpacked files are readable by the user that your web server/PHP runs as.

2. Create Database User

Create a database user with SELECT, INSERT, UPDATE, DELETE rights on your PowerDNS database:

For MySQL/MariaDB:

CREATE USER 'poweradmin'@'localhost' IDENTIFIED BY 'secure_password';
GRANT SELECT, INSERT, UPDATE, DELETE ON powerdns.* TO 'poweradmin'@'localhost';
FLUSH PRIVILEGES;

For PostgreSQL:

CREATE USER poweradmin WITH PASSWORD 'secure_password';
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO poweradmin;

3. Import Database Structure

Import the Poweradmin database structure:

For MySQL/MariaDB:

mysql -u root -p powerdns < sql/poweradmin-mysql-db-structure.sql

For PostgreSQL:

psql -U postgres -d powerdns -f sql/poweradmin-pgsql-db-structure.sql

For SQLite:

sqlite3 /path/to/your/powerdns.db < sql/poweradmin-sqlite-db-structure.sql

!!! danger "Default Credentials" The default login credentials are:

* Username: `admin`
* Password: `admin`

You **must** change these credentials immediately after your first login for security reasons.

4. Create Configuration File

Create a config/settings.php file using the template below. A full list of configuration options can be found in config/settings.defaults.php.

!!! warning "Password Character Restrictions" When creating passwords for database, LDAP, or SMTP authentication, avoid using the following characters:

* Single quotes (`'`)
* Double quotes (`"`) 
* Backslashes (`\`)
* Line breaks

These characters can cause configuration file generation to fail during installation with cryptic PHP syntax errors.

<?php
/**
 * Poweradmin Custom Settings Configuration File
 */

return [
    /**
     * Database Settings
     */
    'database' => [
        'host' => 'localhost',
        'user' => 'poweradmin', // Database user created in step 2
        'password' => 'secure_password',
        'name' => 'powerdns',  // PowerDNS database name
        'type' => 'mysql',     // Options: 'mysql', 'pgsql', 'sqlite'
        // 'file' => '',       // Only for SQLite, provide full path to database file
    ],

    /**
     * Security Settings
     */
    'security' => [
        'session_key' => 'generate_a_random_string_here', // IMPORTANT: Change this!
    ],

    /**
     * DNS Settings
     */
    'dns' => [
        'hostmaster' => 'hostmaster.example.com',
        'ns1' => 'ns1.example.com',
        'ns2' => 'ns2.example.com',
    ],
];

For detailed configuration options, see Basic Configuration and Database Configuration.

5. Secure the Installation

  • Set appropriate permissions on configuration files
  • Remove the install directory after installation
  • Change the default admin password immediately after first login

Web Server Configuration

Apache Configuration

For a basic Apache configuration (without API support), you can use the following settings:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /path/to/poweradmin

    <Directory /path/to/poweradmin>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>    

    # For DDNS update functionality
    RewriteEngine On
    RewriteRule ^/update(.*)$ /dynamic_update.php [L]
    RewriteRule ^/nic/update(.*)$ /dynamic_update.php [L]
</VirtualHost>

Important: Apache .htaccess File

The .htaccess file in the root directory is essential for the API to work properly.

Version-specific .htaccess files:

Ensure that AllowOverride All is set in your Apache configuration to allow the .htaccess file to function properly.

Nginx Configuration

For Nginx servers, use the complete configuration example provided in the Poweradmin repository.

Version-specific nginx configuration files:

Make sure to adjust the following settings for your environment:

  • server_name - Set to your domain name
  • root - Set to your Poweradmin installation path
  • fastcgi_pass - Adjust PHP-FPM socket/TCP configuration as needed

Caddy Configuration

For Caddy servers, use the comprehensive configuration example provided in the Poweradmin repository. This configuration is actively used in the production Docker image and includes advanced security, API support, and performance optimizations.

Use the caddy.conf.example from the repository.

Make sure to adjust the following settings for your environment:

  • Replace :80 with your domain name for automatic HTTPS
  • root - Set to your Poweradmin installation path
  • php_fastcgi - Adjust PHP-FPM socket/TCP configuration as needed

Post-Installation Steps

  1. Configure web server permissions
  2. Set up proper DNS settings (see DNS Settings)
  3. Configure additional features as needed:

Troubleshooting

For common installation issues and solutions, see Common Issues.