Overview of Deploying aaPanel on Server¶

Prerequisites and Basic Requirements¶

• A fresh Ubuntu 20.04 LTS or newer server with root or sudo‑enabled user access.
• Docker and Docker Compose installed and running.
• An available public domain if you want HTTPS through Certbot; otherwise the installation can proceed with HTTP only.
• Open ports 80 and 443 must be reachable from the Internet so that Let’s Encrypt can issue certificates.
• The machine should have enough free space for aaPanel, the Docker image, and the Let’s Encrypt data volume (the image pulls the certbot client and the Nginx web server).

File and Directory Structure¶

Access Rights and Security¶

• The aaPanel binary (/usr/bin/bt) and its systemd unit are owned by root and are executable only by root.
• The Docker image jonasal/nginx-certbot runs with the default user inside the container (usually root). It uses host networking, so all traffic on ports 80/443 goes straight to the container without NAT.
• Nginx configuration files in /data/nginx/user_conf.d/ are owned by root with mode 0644, ensuring that only root can edit them.
• The certbot data volume (nginx_secrets) is owned by root and only accessible inside the container, protecting private keys from the host.
• The aaPanel admin panel runs on port 3000 internally. The reverse proxy forwards traffic from 443 to 127.0.0.1:3000 and strips the SSL verification (proxy_ssl_verify off) because the backend uses self‑signed certificates.

Databases¶

The deployment does not create or configure any database server. If aaPanel later requires MySQL/MariaDB, you can install it separately; the control panel will handle the database setup through its UI.

Docker Containers and Their Deployment¶

The Nginx/Certbot container is defined in compose.yml:

volumes:
  nginx_secrets:
    external: true
services:
  nginx:
    image: jonasal/nginx-certbot:latest
    restart: unless-stopped
    environment:
      - [email protected]
    env_file:
      - /data/nginx/nginx-certbot.env
    network_mode: host
    volumes:
      - nginx_secrets:/etc/letsencrypt
      - /data/nginx/user_conf.d:/etc/nginx/user_conf.d

Deployment steps performed by the playbook:

1. Render the Jinja2 template into /root/nginx/compose.yml.
2. Run docker compose up -d inside /root/nginx to start the container.
3. Validate the Nginx configuration by executing docker exec nginx-nginx-1 nginx -t.
4. For a custom domain, the playbook first writes a lightweight HTTP‑only config that answers the ACME challenge.
5. Certbot is invoked inside the container using the webroot method to request the certificate.
6. After the certificate is obtained, the playbook rewrites the config to add an HTTPS server block and reloads Nginx.

Proxy Servers¶

Nginx is the sole reverse proxy used to expose aaPanel to the Internet:

• HTTP (80):
• Handles the Let’s Encrypt challenge under /.well-known/acme-challenge/.

• Redirects any request for the admin path or / to the same URL but with HTTPS (return 301 $scheme://$http_host...).

• HTTPS (443):

• Uses the certificate stored in /etc/letsencrypt/live/<domain>/.
• Forwards all traffic to the aaPanel backend (proxy_pass https://127.0.0.1:3000).
• Sets standard proxy headers (X‑Forwarded‑*, Host, etc.) and disables SSL verification on the backend.

The configuration file for a custom domain looks like this:

server {
    server_name mydomain.com;
    listen 80;
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }
    location = /aaPanel/ {
        return 301 https://$host/aaPanel/;
    }
    location = / {
        return 301 https://$host/aaPanel/;
    }
    location / {
        proxy_pass https://127.0.0.1:3000;
        proxy_ssl_server_name on;
        proxy_ssl_name mydomain.com:3000;
        proxy_ssl_verify off;
        proxy_set_header Host $http_host:3000;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Port 443;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_redirect off;
    }
}

An HTTPS block is added once the certificate is issued.

Permission Settings¶

• /root/nginx/ and /root/nginx/compose.yml are owned by root with 0755 and 0644 permissions respectively.
• /data/nginx/user_conf.d/ is writable only by root.
• The Docker volume nginx_secrets is owned by root inside the container.
• The aaPanel installation writes configuration files under /www/server/panel/..., all owned by root.
• The service bt runs as root; its logs are stored in /var/log/bt/*.log.

Starting, Stopping, and Updating¶

aaPanel¶

Nginx/Certbot Container¶

These steps are executed automatically by the Ansible playbook during deployment, but you can run them manually if you need to adjust settings or troubleshoot.