Configuring a Subdomain with Apache¶

This guide shows you how to set up a subdomain (e.g., wiki.mus.is) to serve your documentation.

1. DNS Configuration¶

Ensure you have created a DNS A record for your subdomain (e.g., wiki.mus.is) pointing to your server’s IP address.

2. Create an Apache Virtual Host File¶

Create only the :80 (HTTP) vhost in /etc/apache2/sites-available/<subdomain>.conf. You do not need to hand-write the :443 block or the HTTP→HTTPS redirect — certbot (step 4) generates a separate <subdomain>-le-ssl.conf with the SSL vhost and adds the redirect for you.

Example for a static site (wiki.mus.is serving a document root):

<VirtualHost *:80>
    ServerName wiki.mus.is
    DocumentRoot /var/www/wiki/site

    <Directory /var/www/wiki/site>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/wiki.mus.is_error.log
    CustomLog ${APACHE_LOG_DIR}/wiki.mus.is_access.log combined
</VirtualHost>

Note: On this server all HTTP→HTTPS redirects use RewriteEngine/RewriteRule (which is exactly what certbot writes) — never Redirect permanent, which misbehaves here.

3. Enable the Virtual Host and Reload Apache¶

sudo a2ensite wiki.mus.is.conf
sudo systemctl reload apache2

4. Secure the Subdomain with Certbot¶

Obtain and deploy the certificate. Certbot creates <subdomain>-le-ssl.conf, wires in the Let's Encrypt cert, and (with --redirect) adds the HTTP→HTTPS redirect to the :80 vhost:

sudo certbot --apache -d wiki.mus.is

Non-interactive form (no prompts):

sudo certbot --apache -d <subdomain> --non-interactive --agree-tos -m <email> --redirect

5. PHP / dynamic subdomains (e.g. WordPress)¶

The static template above serves files directly. For a PHP app you also need PHP-FPM wired into Apache (this server runs the event MPM, so mod_php is not an option — use PHP-FPM):

sudo apt install php8.2-fpm php8.2-mysql php8.2-gd php8.2-curl php8.2-xml php8.2-mbstring php8.2-zip php8.2-intl php8.2-bcmath
sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.2-fpm          # routes *.php to /run/php/php8.2-fpm.sock for all vhosts
sudo systemctl reload apache2

In the vhost, point DocumentRoot at the app and use AllowOverride All so the app's .htaccess (WordPress permalinks, etc.) works:

<VirtualHost *:80>
    ServerName blek.franzvoid.is
    DocumentRoot /var/www/blek.franzvoid.is

    DirectoryIndex index.php index.html

    <Directory /var/www/blek.franzvoid.is>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/blek.franzvoid.is_error.log
    CustomLog ${APACHE_LOG_DIR}/blek.franzvoid.is_access.log combined
</VirtualHost>

App files must be owned by www-data:www-data. Then run certbot (step 4) as usual.