In the dynamic world of web hosting, managing subdomains effectively is key to maintaining organized, secure, and efficient websites. DirectAdmin, a widely-used control panel, simplifies tasks like domain and subdomain management, making it a go-to choice for hosting providers like Server, which offers robust hosting, domain, and server solutions.
Whether you’re restructuring a project, isolating applications, or aiming for zero-downtime deployments, changing a subdomain’s DocumentRoot—the directory where the web server looks for files to serve is a common task. This guide provides an in-depth, step-by-step process for updating the DocumentRoot of a subdomain in DirectAdmin, covering prerequisites, planning, three reliable methods (GUI, symlink, and custom vhost), and essential post-change tasks like testing and maintenance.
Using the example subdomain sub.example.com under the user username, we’ll assume an Apache-based setup with an optional Nginx reverse proxy, though the principles apply to other stacks like OpenLiteSpeed with minor tweaks. This comprehensive tutorial ensures you can execute the change confidently, anticipate potential pitfalls, and maintain a robust hosting environment.
Prerequisites and Environment Check: Building a Solid Foundation
Before diving into changes, you must understand your server environment to avoid missteps that could cause downtime or security issues. Log in to DirectAdmin and note your skin and version. The Evolution skin, standard in modern installations, offers intuitive subdomain management options.
Older skins, like Enhanced, may lack features like a direct “Change Document Root” toggle, affecting your method choice. Your access level—Admin, Reseller, or User—also determines your options. Admins can access advanced tools like Custom HTTPD Configurations, while Users may rely on GUI methods or need hosting provider assistance.
Identify your web server stack, as it impacts configuration:
- Apache only: Common for DirectAdmin, where changes target Apache virtual host files.
- Nginx reverse proxy (nginx+apache): Nginx handles incoming requests and proxies to Apache, requiring updates to both.
- Nginx Unit or OpenLiteSpeed: These use different configuration files or admin panels, but the logic is similar.
Check your stack via SSH with httpd -v for Apache or nginx -v for Nginx, or via DirectAdmin’s CustomBuild section (Admin level).
For our example, the subdomain sub.example.com under user username has a default Apache DocumentRoot at /home/username/domains/example.com/public_html/sub/. Some setups use /home/username/domains/sub.example.com/public_html/ if the subdomain is standalone. Verify this in Subdomain Management or by checking /usr/local/directadmin/data/users/username/httpd.conf.
Always back up the domain’s directory before proceeding:
tar -czf /home/username/backup_example_com_$(date +%F).tar.gz /home/username/domains/example.com/
This creates a compressed archive for quick restoration. If you lack SSH access (common in shared hosting), use DirectAdmin’s File Manager or request a backup from your provider. This step ensures you’re prepared for any issues and aligns with best practices for server management.
Planning the New DocumentRoot: Strategic Path Selection
Choosing the new DocumentRoot is a critical decision that affects security, organization, and maintainability. The default path, /home/username/domains/example.com/public_html/sub/, nests the subdomain within the main domain’s structure, which can become cluttered as projects grow. Consider two primary options:
- Option A: Within the Main Domain – /home/username/domains/example.com/public_html_apps/sub. This keeps files under the main domain, ideal for related applications like blogs or APIs that share resources (e.g., databases or scripts). It simplifies backups but risks cross-contamination if not secured properly.
- Option B: Isolated Structure – /home/username/domains/sub.example.com/public_html.
- This mimics a standalone domain, offering better isolation for independent applications like e-commerce platforms, enhancing security by limiting shared access.
Keep the path within /home/username/ to avoid permission issues or PHP open_basedir restrictions, which limit script access to safe directories. Paths outside this (e.g., /var/www/) often cause ownership or security errors. Evaluate your project’s needs: Does the subdomain need isolation? Will it share resources with the main domain? For instance, a WordPress multisite might prefer Option A, while a standalone Laravel app benefits from Option B. Document your choice in a project runbook to ensure consistency and streamline future maintenance.
Creating the New Directory: Setting Up the Structure
Create the new DocumentRoot directory with proper permissions. For Option A:
mkdir -p /home/username/domains/example.com/public_html_apps/sub
chown -R username:username /home/username/domains/example.com/public_html_apps/sub
chmod -R 755 /home/username/domains/example.com/public_html_apps/sub
The mkdir -p command creates parent directories if needed, chown sets ownership to the DirectAdmin user, and chmod 755 ensures directories are readable and executable by the web server while restricting writes to the owner. For Option B, adjust the path (e.g., /home/username/domains/sub.example.com/public_html). Verify ownership with ls -l to ensure no files are owned by root or other users, which could block access.
Moving or Deploying Site Files: Seamless Migration
Transfer existing files to the new DocumentRoot using rsync:
rsync -aH –delete /home/username/domains/example.com/public_html/sub/ \
/home/username/domains/example.com/public_html_apps/sub/
The -aH flags preserve file attributes and hard links, while –delete removes outdated files from the destination. Omit –delete for a cautious approach. For new deployments, upload files via FTP, Git, or other methods to the new path. Verify the transfer with ls -l to confirm files are present and correctly owned.
Method A: Using the DirectAdmin GUI (Simplest Approach)
If available, the GUI is the easiest method. Navigate to:
- User Level → Account Manager → Subdomain Management → sub.example.com
Find the “Document Root” or “Change Path” field (common in Evolution). Enter the new path (e.g., /home/username/domains/example.com/public_html_apps/sub) and save. DirectAdmin updates the virtual host and reloads the web server automatically. This method suits users without SSH access or those seeking simplicity. If the option is missing (e.g., in older skins), use Method B or C.
Method B: Symlink for Zero-Downtime Transition
For zero-downtime changes, use a symlink to redirect the default DocumentRoot:
mv /home/username/domains/example.com/public_html/sub /home/username/backup_sub_old_$(date +%F)
ln -s /home/username/domains/example.com/public_html_apps/sub \
/home/username/domains/example.com/public_html/sub
This backs up the original directory and links the old path to the new one. The web server serves the new directory without configuration changes, minimizing disruption. Ensure PHP’s open_basedir includes the new path (see Section 9) and verify that symlinks are allowed, as some security settings block them.
Method C: Custom Apache Virtual Host Override (Advanced)
For precise control, override the Apache virtual host:
- Admin Level → Custom HTTPD Configurations → sub.example.com
Add:
DocumentRoot “/home/username/domains/example.com/public_html_apps/sub”
<Directory “/home/username/domains/example.com/public_html_apps/sub”>
Options FollowSymLinks
AllowOverride All
Require all granted
</Directory>
Save and rebuild configurations:
cd /usr/local/directadmin/custombuild
./build rewrite_confs
Test the configuration with apachectl configtest to catch syntax errors. This method requires Admin access but offers fine-grained control.
Handling Nginx Reverse Proxy Configurations
For Nginx+Apache setups, update both layers. Set the Apache DocumentRoot via Method A or C. For Nginx, check:
- Admin Level → Custom HTTPD/Nginx Configurations → sub.example.com
Ensure the root or try_files directives match the new path. Rebuild and reload:
cd /usr/local/directadmin/custombuild
./build rewrite_confs
service nginx reload
service httpd reload
Mismatched configurations can cause 404 errors, so verify both layers align.
Updating PHP-FPM and open_basedir Settings
Update PHP’s open_basedir to include the new path:
- PHP Settings → Domain PHP Settings
Add /home/username/domains/example.com/public_html_apps/sub to the list. Alternatively, set:
php_admin_value[open_basedir] = /home/username/:/tmp/:/usr/local/lib/php/:/home/username/domains/example.com/public_html_apps/sub
Reload PHP-FPM:
systemctl reload php-fpm
Verify the service name (e.g., php81-php-fpm) to avoid errors. This prevents open_basedir restriction errors.
Fixing File Ownership and Permissions
Re-apply permissions:
chown -R username:username /home/username/domains/example.com/public_html_apps/sub
find /home/username/domains/example.com/public_html_apps/sub -type d -exec chmod 755 {} \;
find /home/username/domains/example.com/public_html_apps/sub -type f -exec chmod 644 {} \;
Avoid 777 permissions; use 775 for writeable directories (e.g., uploads) with consistent group ownership.
Preserving /.well-known for SSL/ACME Challenges
Ensure /.well-known/acme-challenge/ remains accessible for Let’s Encrypt. Method B (symlink) typically works automatically. For Method C, verify no Alias or rewrite rules block this path. Test renewals:
certbot renew –dry-run
Verifying .htaccess and Rewrite Rules
Copy the .htaccess file:
cp /home/username/backup_sub_old_$(date +%F)/.htaccess \
/home/username/domains/example.com/public_html_apps/sub/
Review rewrite rules for CMS-specific paths (e.g., WordPress, Laravel). For Nginx, convert .htaccess rules to location blocks.
Restarting Services and Clearing Caches
Apply changes:
systemctl restart httpd
systemctl reload nginx # if applicable
Clear application, PHP OPcache, and CDN caches. Verify PHP:
php -v
Testing and Rollback Plan
Test the subdomain:
- Visit http://sub.example.com and https://sub.example.com.
- Add a test file (e.g., health.html) to confirm the correct directory.
- Check headers:
curl -I https://sub.example.com
- Monitor logs:
- Apache: /var/log/httpd/domains/sub.example.com.error.log
- Nginx: /var/log/nginx/domains/sub.example.com.error.log
- PHP-FPM: /var/log/php-fpm/error.log
Rollback:
- GUI: Revert the path.
- Symlink: Remove the symlink and restore the backup.
- Vhost: Delete the override and run ./build rewrite_confs.
Updating Backups and Monitoring
Include the new DocumentRoot in backups and update monitoring tools. Document the change in your runbook, noting the method used.
Additional Considerations
Why Change the DocumentRoot?
- Isolation: Prevents app interference.
- Security: Limits cross-site access.
- Deployment: Supports zero-downtime strategies.
- Organization: Simplifies backups and CI/CD.
Zero-Downtime Deployment
Use a release structure:
/home/username/apps/subsite/
releases/
2025-09-05_1200/
2025-09-05_1400/
current -> releases/2025-09-05_1400
Update with:
ln –sfn /home/username/apps/subsite/releases/2025-09-05_1500 \
/home/username/apps/subsite/current
Security Best Practices
- Include new paths in open_basedir.
- Avoid 777 permissions.
- Ensure consistent ownership.
- Check SELinux/AppArmor settings.
Troubleshooting
- 403 Forbidden: Verify permissions and Require all granted.
- 404 Not Found: Check vhost paths and rewrites.
- 500 Internal Server Error: Inspect .htaccess or PHP extensions.
- ACME Failures: Ensure /.well-known is accessible.
A) How DirectAdmin Organizes Subdomain Paths by Default
DirectAdmin structures subdomain paths in two primary configurations, each offering distinct advantages and trade-offs for management, security, and backups. The most common is the parent domain tree, where a subdomain like sub.example.com is mapped to /home/username/domains/example.com/public_html/sub/. This places the subdomain’s files within the main domain’s public_html directory, facilitating resource sharing (e.g., databases or scripts) and streamlining backups under a single tree. It’s ideal for integrated projects, such as a blog or support portal tied to the main site, as it keeps related assets together. However, this can clutter the public_html directory, especially for complex sites, and increases the risk of cross-project interference if permissions or scripts are not tightly managed.
Alternatively, DirectAdmin may configure subdomains as separate directories, such as /home/username/domains/sub.example.com/public_html/, treating them like standalone domains. This approach enhances isolation, minimizing accidental interactions between the subdomain and main domain, and simplifies per-subdomain permissions and targeted backups. The trade-off is that sharing resources with the parent domain requires additional configuration, and backup scripts must account for multiple paths. When selecting a new DocumentRoot, keep it within /home/username/ to avoid permission issues or PHP open_basedir conflicts. For distinct applications hosted on a robust Server, the isolated directory structure is often the safer choice, offering cleaner separation and easier maintenance.
B) When Should You Change a Subdomain’s DocumentRoot?
Changing a subdomain’s DocumentRoot is a strategic decision driven by specific needs that enhance site organization, security, or deployment efficiency. Application isolation is a key motivator: separating a forum, admin panel, or e-commerce platform from the main codebase prevents unintended interactions, such as script conflicts or security vulnerabilities affecting multiple sites. Large or complex codebases, like those for frameworks such as Laravel or Magento, can overwhelm the main domain’s public_html directory. Relocating these to a dedicated path, like /home/username/domains/example.com/public_html_apps/sub, keeps the file structure organized and maintainable.
Zero-downtime deployments in CI/CD pipelines also benefit from DocumentRoot changes. By pointing the virtual host to a stable path or symlink (e.g., current linking to versioned releases), you can switch between versions seamlessly, ensuring uninterrupted user access. Similarly, migrations or major upgrades—such as transitioning to a new CMS or framework version—require a new DocumentRoot to test and deploy without affecting the live site. Finally, security and compliance needs may necessitate isolating sensitive workloads with path-specific hardening. If you’re restructuring infrastructure or adjusting services like Hosting or Domain configurations, a well-planned DocumentRoot simplifies these transitions, aligning with modern hosting practices.
C) Security Considerations (open_basedir, Permissions, Symlinks)
Security is critical when relocating a subdomain’s DocumentRoot, as missteps can expose vulnerabilities or disrupt functionality. Follow the least-privilege principle: set directories to 755 (read/execute for all, write for owner) and files to 644 (read for all, write for owner). Avoid 777 permissions, which allow world-writable access and pose significant risks. For applications requiring write access (e.g., upload or cache directories), use 775 for specific folders and ensure the group aligns with the web server or PHP-FPM user.
PHP’s open_basedir restricts script access to specified directories. After changing the DocumentRoot, update open_basedir to include the new physical path (e.g., /home/username/domains/example.com/public_html_apps/sub). For symlinked DocumentRoots, ensure the target path is included, as PHP resolves symlinks to their actual location. Some server configurations or security modules (e.g., mod_security) may block symlink following, so verify compatibility to prevent access errors. File ownership must remain consistent, with all files owned by the DirectAdmin user (username:username). Correct any root:root files, often introduced during manual uploads, using chown -R username:username. Finally, keep .htaccess or Nginx rules minimal and auditable, re-testing access controls in the new location to maintain a secure environment, especially when managing sensitive workloads on a Server.
D) Apache vs Nginx Reverse Proxy in DirectAdmin
The process for changing a DocumentRoot varies by web server stack, and understanding these differences prevents configuration mismatches. In an Apache-only setup, the DocumentRoot is defined in the virtual host configuration (e.g., /usr/local/directadmin/data/users/username/httpd.conf), and .htaccess files handle rewrites and access rules. You can update the DocumentRoot via DirectAdmin’s GUI (if available) or a custom vhost override, followed by rebuilding configurations with:
Reload Apache to apply changes (systemctl reload httpd). This ensures the new path is served correctly without disrupting other domains.
In an Nginx reverse proxy (nginx+apache) setup, Nginx handles incoming requests and proxies them to Apache, requiring synchronization between both layers. Update Apache’s DocumentRoot via the GUI or vhost override, and ensure Nginx’s configuration (e.g., /etc/nginx/domains/sub.example.com.conf) has a matching root or try_files directive pointing to the new path. After edits, rebuild and reload both services:
DirectAdmin’s CustomBuild tool ensures consistency across both layers, preventing issues like 404 errors or broken rewrites due to mismatched paths. This alignment is crucial for seamless operation in complex hosting environments like those provided by Hosting.
E) Impact on SSL/TLS & Let’s Encrypt Challenges
Relocating a subdomain’s DocumentRoot can impact SSL/TLS certificate renewals, particularly for Let’s Encrypt, which uses HTTP-01 challenges to validate domain ownership via the /.well-known/acme-challenge/ path. This path must remain accessible in the new DocumentRoot to avoid renewal failures. The symlink method typically preserves URL paths, allowing challenges to resolve to the new directory automatically. However, for GUI or custom vhost methods, ensure no Alias, rewrite rules, or .htaccess directives block or redirect /.well-known/acme-challenge/. If a CMS (e.g., WordPress) rewrites all requests to index.php, add an explicit exception for the ACME path.
To verify, run a dry-run renewal during a low-traffic period:
This simulates the renewal process, catching issues like blocked paths or misconfigured DocumentRoots. Addressing these early prevents certificate expirations, ensuring secure connections for users accessing your subdomain on a reliable Server.
F) Deployment Patterns That Make DocRoot Changes Easier
Modern deployment strategies streamline DocumentRoot changes and enable zero-downtime updates, particularly for CI/CD pipelines. A highly effective pattern is the symlink-based release structure, where the DocumentRoot points to a current symlink linked to versioned release directories:
To deploy a new version, upload files to a new release directory (e.g., releases/2025-09-05_1500), run migrations or tests, then update the symlink atomically:
The -sfn flags ensure an instant switch with no downtime, and previous releases remain available for quick rollback. Configure the DocumentRoot to point to current via the GUI, symlink method, or vhost override. This approach minimizes disruption, simplifies backups (targeting releases/ and shared writeable directories), and reduces errors during deployments. It’s particularly effective for scalable hosting environments, such as those managed through Hosting, ensuring smooth updates and reliable performance
Summary
Changing a subdomain’s DocumentRoot in DirectAdmin can be done via the GUI, symlinks, or custom vhosts. Each method requires careful planning, permission updates, and testing to ensure a smooth transition. Update PHP settings, preserve SSL functionality, and maintain backups to safeguard your environment.
Leave a Reply