HTMLy

Install HTMLy on Ubuntu 22.04 (Beginner Friendly, Apache + PHP‑FPM + HTTPS)

This guide helps you get a working HTMLy website on a fresh Ubuntu 22.04 server with a real domain and HTTPS. No database needed (HTMLy is flat‑file). At the end, you’ll also see how to publish this tutorial on WordPress (Gutenberg) neatly.

1) Before You Start

You need
- A domain name like example.com.
- A fresh Ubuntu 22.04 server (VPS or dedicated). Keep your provider dashboard open.
- DNS A record for example.com (and optional www.example.com) pointing to your server’s public IP.
- SSH access (username/password or SSH key).
What we’ll install
- Apache (web server), PHP‑FPM (PHP engine), HTMLy, and Let’s Encrypt (HTTPS).

Tip: Replace example.com everywhere with your real domain.

2) Connect to Your Server

On macOS/Linux terminal:
```
ssh youruser@your.server.ip
```

Optional: if you only have root, create a sudo user (recommended):

adduser myuser
usermod -aG sudo myuser
# Log out, then back in as the new user
ssh myuser@your.server.ip

3) Update and Install Software

sudo apt update && sudo apt -y upgrade

# Install Apache, PHP-FPM, and common extensions HTMLy/most CMS need
sudo apt -y install apache2 php-fpm php-cli php-xml php-mbstring php-json php-gd php-zip php-curl unzip

# Enable useful Apache modules (rewrite and headers are important)
sudo a2enmod proxy_fcgi setenvif rewrite headers

# Start and enable services (PHP 8.1 is default on Ubuntu 22.04)
sudo systemctl enable --now apache2
sudo systemctl enable --now php8.1-fpm

Optional firewall (UFW):

sudo ufw allow OpenSSH
sudo ufw allow "Apache Full"
# sudo ufw enable   # only if you want UFW

4) Create Your Website Folder

sudo mkdir -p /var/www/example.com
sudo chown -R $USER:$USER /var/www/example.com

5) Download and Place HTMLy

We’ll install the latest 3.1.x release (adjust version as needed).

cd /var/www/example.com
curl -L -o htmly-3.1.0.zip https://github.com/danpros/htmly/archive/refs/tags/v3.1.0.zip
unzip htmly-3.1.0.zip

# Move extracted contents into the web root, then clean up
shopt -s dotglob nullglob
mv htmly-3.1.0/* .
rm -rf htmly-3.1.0 htmly-3.1.0.zip

Make writable folders for HTMLy content and cache:

mkdir -p content cache
sudo chown -R www-data:www-data content cache
sudo find content cache -type d -exec chmod 775 {} \;
sudo find content cache -type f -exec chmod 664 {} \;

6) Configure Apache for Your Domain

Create a vhost file at /etc/apache2/sites-available/example.com.conf:

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com

    DocumentRoot /var/www/example.com

    <Directory /var/www/example.com>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # Send .php files to PHP-FPM (Ubuntu 22.04 default: PHP 8.1)
    <FilesMatch "\.php$">
        SetHandler "proxy:unix:/run/php/php8.1-fpm.sock|fcgi://localhost"
    </FilesMatch>

    # Basic security headers
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-XSS-Protection "1; mode=block"

    ErrorLog ${APACHE_LOG_DIR}/example.com_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_access.log combined
</VirtualHost>

Enable the site and reload Apache:

sudo a2ensite example.com.conf
sudo a2dissite 000-default.conf
sudo apache2ctl configtest
sudo systemctl reload apache2

Quick check PHP‑FPM is running:

systemctl status php8.1-fpm --no-pager

7) Add HTTPS (Let’s Encrypt)

Install Certbot (snap is recommended on Ubuntu 22.04):

sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

Get a certificate and auto-configure Apache (includes HTTP→HTTPS redirect):

sudo certbot --apache -d example.com -d www.example.com --redirect -m you@example.com --agree-tos -n

Test automatic renewal:

sudo certbot renew --dry-run

8) Finish HTMLy Setup

Open https://example.com/.
Follow on-screen steps if prompted (site name, admin user).
Pretty URLs use .htaccess. We already enabled AllowOverride All and rewrite.

Final permissions (safe to re-run):

sudo chown -R www-data:www-data /var/www/example.com/content /var/www/example.com/cache

9) Common Issues (Quick Fixes)

Blank page or 500 error
- Check logs: /var/log/apache2/example.com_error.log.
- Confirm PHP‑FPM socket matches: /run/php/php8.1-fpm.sock.
- Ensure content/ and cache/ are writable by www-data.
URLs not rewriting
- Run sudo a2enmod rewrite; ensure AllowOverride All is in the <Directory> block.
- Ensure .htaccess exists in your HTMLy root.
SSL problems
- DNS must point to your server first; ensure ports 80/443 open.
- If using UFW, check sudo ufw status.

10) Backup and Update (Safe Path)

Backup your site (before changes):

sudo tar -czf /root/backup-htmly-$(date +%F).tar.gz -C /var/www example.com

Update HTMLy (preserve content/ and cache/):
“`bash
VERSION=3.1.0
TMP=/tmp/htmly-update-$VERSION
mkdir -p “$TMP” && cd “$TMP”
curl -L -o htmly-$VERSION.zip “https://github.com/danpros/htmly/archive/refs/tags/v$VERSION.zip”
unzip htmly-$VERSION.zip
SRC=”$TMP/htmly-$VERSION”

sudo rsync -av –delete
–exclude ‘content/’ –exclude ‘cache/’
“$SRC/” /var/www/example.com/

Fix permissions for writable areas

sudo chown -R www-data:www-data /var/www/example.com/content /var/www/example.com/cache


## 11) Choose www or non‑www (Optional)

To force non‑www (`example.com`) via `.htaccess` (put at top of `/var/www/example.com/.htaccess`):
```apache
RewriteEngine On
RewriteCond %{HTTP_HOST} ^www\.example\.com$ [NC]
RewriteRule ^(.*)$ https://example.com/$1 [R=301,L]

Or force www.example.com:

RewriteEngine On
RewriteCond %{HTTP_HOST} !^www\.example\.com$ [NC]
RewriteRule ^(.*)$ https://www.example.com/$1 [R=301,L]

Use only one. Clear your browser cache to test.

Publish This Tutorial on WordPress (Gutenberg)

Goal: Copy this tutorial to your WordPress site cleanly.

A) Prepare the Post

In WordPress Admin, go to Posts → Add New.
Set a clear title, e.g., “Install HTMLy on Ubuntu 22.04 (Beginner Guide)”.
Set the URL slug (permalink) to something short, e.g., htmly-ubuntu-22-04.

B) Paste Content and Keep Formatting

Copy each section from this file and paste into Gutenberg.
For commands and config, use a Code block:
- Click the plus (+) → search “Code” → paste the code.
- For long commands, enable “Preserve whitespace” if your theme supports it.
For headings, use Heading blocks (H2 for main sections, H3 for sub‑steps).
For notes or tips, use the “Quote” or “List” block to keep it readable.

C) Images (Optional)

If you took screenshots (e.g., DNS settings or terminal output), insert them as Image blocks.
Add alt text (e.g., “Example DNS A record for example.com”).