201 lines
6.2 KiB
Markdown
201 lines
6.2 KiB
Markdown
# Deployment Guide for LXC Container
|
||
|
||
This guide explains how to deploy this Hugo website to an LXC container running Ubuntu (or similar). The site runs as a live Hugo server with a reverse proxy forwarding requests.
|
||
|
||
## Prerequisites
|
||
|
||
- LXC container with Arch Linux (or adjust package manager commands for your distribution)
|
||
- SSH access to the container
|
||
- Git installed on container
|
||
- Domain name `dustin.coffee` pointing to container's IP address (or adjust baseURL in `hugo.toml`)
|
||
|
||
## Step 1: Install Hugo Extended on LXC
|
||
|
||
**Important**: This theme requires Hugo **extended** version ≥ 0.123.0. Ubuntu's default apt repository provides an outdated version (v0.123.7). You must install a newer extended version.
|
||
|
||
### Option A: Using installation script (Recommended)
|
||
|
||
Copy the `install-hugo.sh` script to your container and run it:
|
||
|
||
```bash
|
||
# On your container, as root or with sudo:
|
||
chmod +x install-hugo.sh
|
||
./install-hugo.sh
|
||
```
|
||
|
||
### Option B: Manual installation for Ubuntu/Debian
|
||
|
||
```bash
|
||
# Remove old Hugo if installed
|
||
sudo apt remove -y hugo
|
||
|
||
# Add Hugo APT repository
|
||
ARCH=$(dpkg --print-architecture)
|
||
echo "deb [arch=${ARCH} signed-by=/etc/apt/keyrings/hugo.gpg] https://hugo-apt.8hob.io latest main" | sudo tee /etc/apt/sources.list.d/hugo.list
|
||
sudo chmod 644 /etc/apt/sources.list.d/hugo.list
|
||
|
||
# Add signing key
|
||
sudo mkdir -p /etc/apt/keyrings
|
||
sudo wget -O /etc/apt/keyrings/hugo.gpg https://hugo-apt.8hob.io/signing-key
|
||
sudo chmod 644 /etc/apt/keyrings/hugo.gpg
|
||
|
||
# Pin repository priority
|
||
echo 'Package: hugo
|
||
Pin: origin "hugo-apt.8hob.io"
|
||
Pin-Priority: 520' | sudo tee /etc/apt/preferences.d/hugo
|
||
sudo chmod 644 /etc/apt/preferences.d/hugo
|
||
|
||
# Install Hugo Extended
|
||
sudo apt update
|
||
sudo apt install -y hugo
|
||
|
||
# Install git (required for Hugo modules)
|
||
sudo apt install -y git
|
||
```
|
||
|
||
### Verify installation
|
||
|
||
Check that you have the extended version:
|
||
|
||
```bash
|
||
hugo version
|
||
hugo env | grep HUGO_EXTENDED
|
||
# Should show: HUGO_EXTENDED=true
|
||
```
|
||
|
||
If `hugo version` shows v0.123.7 or earlier, the installation failed. Try Option B or install the binary manually from [Hugo releases](https://github.com/gohugoio/hugo/releases).
|
||
|
||
## Step 2: Clone Repository
|
||
|
||
Clone your git repository to a directory, e.g., `/srv/www/dustin.coffee`:
|
||
|
||
```bash
|
||
sudo mkdir -p /srv/www
|
||
sudo chown $USER:$USER /srv/www
|
||
cd /srv/www
|
||
git clone <your-git-repo-url> dustin.coffee
|
||
cd dustin.coffee
|
||
|
||
# Initialize theme submodule (required for hello-friend-ng theme)
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
## Step 3: Run Hugo Server (Reverse Proxy Setup)
|
||
|
||
Since you're using a reverse proxy pointing to the LXC container, run Hugo as a live server:
|
||
|
||
```bash
|
||
cd /srv/www/dustin.coffee
|
||
hugo server --bind 0.0.0.0 --port 1313 --baseURL=https://dustin.coffee --appendPort=false --disableLiveReload
|
||
```
|
||
|
||
**Important flags:**
|
||
- `--bind 0.0.0.0` – Listen on all network interfaces
|
||
- `--port 1313` – Port for the reverse proxy to forward to (adjust if different)
|
||
- `--baseURL=https://dustin.coffee` – Your public domain (must match reverse proxy)
|
||
- `--appendPort=false` – Don't include port 1313 in generated URLs (critical for correct links)
|
||
- `--disableLiveReload` – Disable live reload in production
|
||
|
||
### Systemd Service (Recommended for production)
|
||
|
||
Create `/etc/systemd/system/hugo-dustin.service`:
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=Hugo Server for dustin.coffee
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=www-data
|
||
Group=www-data
|
||
WorkingDirectory=/srv/www/dustin.coffee
|
||
ExecStart=/usr/bin/hugo server --bind 0.0.0.0 --port 1313 --baseURL=https://dustin.coffee --appendPort=false --disableLiveReload
|
||
Restart=on-failure
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
**Adjust paths:**
|
||
- Replace `/usr/bin/hugo` with `hugo` if installed via apt repository
|
||
- Set `User`/`Group` to your LXC user if not www-data
|
||
- Update `WorkingDirectory` to your site path
|
||
|
||
Enable and start the service:
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable hugo-dustin
|
||
sudo systemctl start hugo-dustin
|
||
```
|
||
|
||
Check status: `sudo systemctl status hugo-dustin`
|
||
|
||
## Step 4: Reverse Proxy Configuration
|
||
|
||
SSL/TLS encryption should be configured at your reverse proxy level (not Hugo).
|
||
|
||
Hugo itself runs on HTTP (port 1313). Your reverse proxy should:
|
||
- Terminate SSL at the proxy (HTTPS on port 443)
|
||
- Forward HTTP requests to Hugo on port 1313
|
||
- Set appropriate `X-Forwarded-*` headers if needed
|
||
|
||
**If using Caddy, Traefik, or another reverse proxy:** Consult your proxy's documentation for SSL configuration. Most modern proxies automatically handle SSL with Let's Encrypt.
|
||
|
||
**Important:** Ensure your reverse proxy forwards requests to `http://<lxc-internal-ip>:1313` (or `localhost:1313` if proxy runs on same container). The domain `dustin.coffee` must resolve to your reverse proxy's public IP.
|
||
|
||
## Step 5: Automation Script
|
||
|
||
Create a deployment script `deploy.sh` in the repository root:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# deploy.sh - update site and restart Hugo server
|
||
|
||
set -e
|
||
|
||
cd /srv/www/dustin.coffee
|
||
|
||
echo "Pulling latest changes from git..."
|
||
git pull
|
||
|
||
echo "Updating theme submodule..."
|
||
git submodule update --init --recursive
|
||
|
||
echo "Restarting Hugo server..."
|
||
sudo systemctl restart hugo-dustin
|
||
|
||
echo "Deployment completed at $(date)"
|
||
```
|
||
|
||
Make it executable:
|
||
|
||
```bash
|
||
chmod +x deploy.sh
|
||
```
|
||
|
||
Now after SSH-ing into the container, you can run `./deploy.sh` to update the site.
|
||
|
||
## Notes
|
||
|
||
- Update the `baseURL` in `hugo.toml` if your domain changes.
|
||
- The site uses the `hello-friend-ng` theme as a git submodule.
|
||
- Blog posts are stored in `content/posts/` as markdown files.
|
||
- To add new blog posts, create markdown files in `content/posts/` on your development machine, push to git, then run the deploy script on the container.
|
||
|
||
## Troubleshooting
|
||
|
||
- If Hugo server fails to start, check logs: `sudo journalctl -u hugo-dustin -f`
|
||
- If Hugo fails to build, check Hugo version matches the one used in development.
|
||
- If blog post URLs are incorrect, verify `permalinks` configuration in `hugo.toml`.
|
||
- If reverse proxy shows 404, ensure Hugo server is running on port 1313 and reverse proxy forwards to correct port.
|
||
|
||
## Updating
|
||
|
||
To update the site after making changes on your development machine:
|
||
|
||
1. Push changes to your git server
|
||
2. SSH into LXC container
|
||
3. Navigate to site directory: `cd /srv/www/dustin.coffee`
|
||
4. Run `./deploy.sh` |