Subdomain Management --- Complete Guide

[admin]

Subdomain Management — Complete Guide​

This guide covers creating, managing, and configuring subdomains in Panelica. Subdomains let you host separate websites or applications under your main domain — like blog.example.com, shop.example.com, or staging.example.com.

Accessing Subdomain Management​

Go to Subdomains in the main navigation. You'll see a two-panel layout:

• Left Panel — Your domain list with subdomain counts
• Right Panel — Subdomain table and management for the selected domain

Click any domain on the left to view and manage its subdomains on the right.

---

Creating a Subdomain​

Step 1: Select the parent domain from the left panel.

Step 2: Click the Add Subdomain button (top-right of the right panel).

Step 3: Fill in the form:

Field	Required	Description
Subdomain Name	Yes	The prefix (e.g., type blog to create blog.example.com). Alphanumeric and hyphens only, 1-63 characters.
Document Root	No	Relative path within the subdomain directory. Defaults to public_html if left empty.
Redirect URL	No	If set, all traffic to this subdomain redirects (301) to the specified URL. Leave empty for a normal subdomain.
SSL / HTTPS	No	Enable SSL for this subdomain. Inherits parent domain's SSL setting by default.

Step 4: Click Create.

---

What Happens When You Create a Subdomain​

Panelica runs an 11-step provisioning process automatically:

1. Validates the subdomain name (format and uniqueness)
2. Checks your plan quota — each plan has a maximum number of subdomains
3. Creates the database record
4. Creates the directory structure:
   

   /home/{username}/{domain}/subdomains/{subdomain}/
   ├── public_html/       ← Your web files go here
   │   ├── index.html     ← Default welcome page
   │   └── assets/        ← Branding logos/icons
   ├── logs/              ← Access and error logs
   │   ├── access.log
   │   └── error.log
   ├── tmp/               ← Temporary files
   │   └── sessions/      ← PHP sessions
   └── ssl/               ← SSL certificate (if enabled)
       ├── cert.pem
       └── key.pem

5. Sets file ownership to your system user
6. Generates Nginx configuration with PHP-FPM, SSL, and logging
7. Generates Apache configuration (if using Nginx+Apache mode)
8. Issues an SSL certificate (if SSL enabled — first self-signed, then attempts Let's Encrypt)
9. Creates a DNS A record pointing the subdomain to your server's IP
10. Syncs with Cloudflare (if Cloudflare integration is configured)
11. Reloads web server — your subdomain is live immediately

---

Subdomain Table​

The subdomain table shows all subdomains for the selected domain:

Column	Description
Subdomain	Full subdomain name (e.g., blog.example.com)
PHP Version	PHP version badge (e.g., "PHP 8.4") or "N/A" if inherited
SSL	Enabled (green, shows provider) or Disabled (gray)
Document Root	File path (truncated if long)
Status	Active (green) or Suspended (yellow)
Actions	Edit, Visit, Copy Name, Delete

The table footer shows total subdomain count plus the number with active SSL.

---

Editing a Subdomain​

Click the Edit button on any subdomain row. You can change:

Field	Description
Document Root	Change the web-accessible directory path
PHP Version	Override the parent domain's PHP version (select from 8.1, 8.2, 8.3, 8.4) or choose "Inherit from parent domain"
SSL / HTTPS	Toggle SSL on or off. Toggling on auto-generates a certificate.
Redirect URL	Set or remove a redirect destination

After saving, Panelica regenerates the web server configuration and reloads services automatically.

---

What Subdomains Inherit from the Parent Domain​

Setting	Inherited?	Overridable?
PHP Version	Yes	Yes — via Edit modal
Web Server Mode (Nginx / Nginx+Apache)	Yes	No
HSTS Headers	Yes	No
PHP-FPM Pool	Yes	No (uses parent's pool)
Error Pages	Yes	No

---

Redirect Mode​

If you set a Redirect URL on a subdomain, all traffic is permanently redirected (HTTP 301) to that URL. This is useful for:

• Pointing www.example.com to example.com
• Redirecting old subdomains to new locations
• Sending traffic to an external service

When redirect mode is active:

• No PHP execution occurs
• No files are served
• SSL renewal still works (ACME challenge path is excluded from redirect)

---

Suspending a Subdomain​

Suspended subdomains show a "503 Service Unavailable" page to all visitors. The subdomain's files remain intact — suspension is reversible.

Use suspension when you need to temporarily take a subdomain offline without deleting it.

---

Deleting a Subdomain​

Click the Delete button on any subdomain row. A confirmation dialog lists the consequences:

• All subdomain files will be permanently deleted
• SSL certificates will be removed
• Nginx and Apache configurations will be removed
• DNS A record will be removed

This action cannot be undone. Make sure you have backups of any important files before deleting.

---

Plan Limits​

Each service plan defines a maximum number of subdomains per user. You can see your limit on the plan details when creating users or in the plan configuration.

• -1 means unlimited subdomains
• A specific number (e.g., 5) limits you to that many across all domains

If you've reached your limit, the "Add Subdomain" button will show an error. Contact your administrator to upgrade your plan.

---

DNS Considerations​

When you create a subdomain, Panelica automatically:

1. Creates an A record in the BIND DNS zone for the parent domain
2. Attempts to sync the record to Cloudflare (if integration is configured for that domain)

If you're using external DNS (not Panelica's built-in BIND), you need to manually add an A record for the subdomain pointing to your server's IP address.

Example: To create blog.example.com, add this DNS record at your DNS provider:

Type: A
Name: blog
Value: YOUR_SERVER_IP
TTL: 3600

---

SSL for Subdomains​

When SSL is enabled for a subdomain:

1. A self-signed certificate is generated immediately (so HTTPS works right away)
2. Panelica then attempts to issue a Let's Encrypt certificate automatically
3. If Let's Encrypt succeeds, the self-signed cert is replaced
4. If it fails (e.g., DNS not propagated yet), the self-signed cert remains — you can retry later from the SSL Management page

---

Troubleshooting​

Problem: Subdomain shows 404 Not Found

• Check that the document root directory exists and contains an index.html or index.php file
• Verify the document root path in the subdomain edit modal

Problem: Subdomain not accessible at all

• Check DNS: dig blog.example.com +short — should return your server IP
• If using external DNS, manually add the A record
• Wait for DNS propagation (up to 48 hours)

Problem: "Subdomain limit reached" error

• Your service plan has a maximum subdomain quota
• Contact your administrator to upgrade your plan

Problem: SSL certificate fails for subdomain

• Ensure the subdomain's DNS A record points to your server
• Port 80 must be open for Let's Encrypt HTTP validation
• Try issuing the certificate again from the SSL Management page

---

Related Guides​

• First Steps After Setup — Creating your first domain
• Troubleshooting — Domain and DNS issue resolution

---

Questions? Ask in General Discussion.

 

[admin]

Related Topics​

• Domains & DNS --- Feature Overview
• SSL/HTTPS Certificate Management --- Complete Guide
• URL Redirects
• PHP & Server Configuration