← Writing
DevOps

Deploying a Static Service to a Fresh Server: Nginx, Cloudflare, GitHub Actions, and WireGuard

Moving a site to a new server is not a git pull problem. It is a small systems-design exercise: DNS, TLS, the web server, deployment identity, firewall policy, and any pre-existing network services all need to agree.

This note records a working pattern for deploying a static service to a fresh Ubuntu server. The examples use zsh, nginx, Cloudflare, GitHub Actions, and a WireGuard gateway. The domain and addresses below are deliberately placeholders.

1. Start with roles and boundaries

Give each concern one owner:

Concern Owner
Public HTTP/HTTPS entry point nginx
Site files and release process deploy
nginx configuration and private TLS key root
DNS, edge TLS, proxying Cloudflare
Build metadata and deployment trigger GitHub Actions

The deployment account should own application files, not the entire machine. It does not need unrestricted sudo. nginx runs as its usual unprivileged worker user and only needs read/traverse access to published files.

For a server expected to host several services, a dedicated data filesystem such as /data/www is entirely reasonable. The traditional /var/www is a convention, not a requirement. A useful layout is:

/data/www/
|-- homepage/
|   |-- repo/       # deployment checkout; never exposed by nginx
|   |-- releases/   # immutable releases, named by commit SHA
|   `-- current -> releases/<commit-sha>
|-- app-one/
`-- app-two/

Keeping repo/ outside the nginx root means .git and deployment helpers are never accidentally served.

2. Publish immutable releases instead of editing the live tree

An in-place git reset --hard is simple but can briefly expose a mixture of old and new assets. A release directory plus a symlink makes publication atomic.

The deployment script is a zsh program owned by deploy. Its essential algorithm is:

#!/usr/bin/env zsh
emulate -LR zsh
setopt ERR_EXIT NO_UNSET PIPE_FAIL

readonly site=/data/www/homepage
readonly repo=$site/repo
readonly releases=$site/releases

git -C "$repo" fetch --prune origin master
revision=$(git -C "$repo" rev-parse origin/master)
target="$releases/$revision"

if [[ ! -d "$target" ]]; then
  staging="$releases/.${revision}.${RANDOM}.tmp"
  mkdir -p "$staging"
  git -C "$repo" archive "$revision" | tar -xf - -C "$staging"
  mv "$staging" "$target"
fi

next="$site/.current-${revision}"
ln -s "releases/$revision" "$next"
mv -Tf "$next" "$site/current"

mv -T replaces the symlink in one filesystem operation. A request therefore reaches the old complete release or the new complete release. Keeping a few old release directories also makes rollback a symlink change rather than another build.

nginx should point only at the symlinked release:

root /data/www/homepage/current;
index index.html;

location / {
    try_files $uri $uri/ =404;
}

3. Put HTTPS in place before changing DNS

When Cloudflare proxies a hostname, Cloudflare handles browser-facing TLS and connects separately to the origin. The origin should still use TLS. Create a Cloudflare Origin Certificate with both the apex and first-level wildcard names:

example.com
*.example.com

Store the certificate and key in a root-owned directory such as /etc/ssl/cloudflare/, with the private key mode 0600. Configure nginx on both IPv4 and IPv6, then use Cloudflare’s Full (strict) mode. Never use Flexible mode: it leaves the Cloudflare-to-origin hop unencrypted and often causes redirect loops.

Before changing the DNS record, test the new origin directly while preserving the real hostname for SNI:

curl -kI --resolve www.example.com:443:NEW_SERVER_IPV4 https://www.example.com/

-k is appropriate only for this direct test because a Cloudflare Origin Certificate is not trusted by browsers. Through Cloudflare, the browser receives Cloudflare’s publicly trusted certificate.

Once that succeeds, update only the web records in Cloudflare. A typical proxied setup is:

Type Name Content
A @ new server IPv4
AAAA @ new server IPv6
CNAME www apex domain

Do not disturb MX, SPF, DKIM, DMARC, or other unrelated records. Keep the old origin running until curl -I https://www.example.com/ returns the expected page through Cloudflare.

4. Let GitHub Actions build, then ask the server to publish

This homepage derives posts/index.json, assets/site-meta.json, and sitemap.xml from Markdown frontmatter and Git history. The GitHub workflow must therefore generate and commit those artifacts before it asks the server to deploy.

The deployment step itself is intentionally small:

- name: Deploy release
  uses: appleboy/[email protected]
  with:
    host: ${{ secrets.SERVER_HOST }}
    username: ${{ secrets.SERVER_USER }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}
    port: ${{ secrets.SERVER_PORT }}
    script: |
      exec zsh /data/www/homepage/deploy-homepage.zsh

The SSH host must be the server’s direct IP address, not the proxied web domain: Cloudflare does not proxy normal SSH traffic.

Use a dedicated deployment key. Its public half belongs in /home/deploy/.ssh/authorized_keys with a forced command and OpenSSH restrictions:

restrict,command="/data/www/homepage/deploy-homepage.zsh" ssh-ed25519 AAAA... github-actions-homepage

That key cannot open an interactive shell, create a tunnel, or execute arbitrary commands. It can only run the release publisher as the unprivileged deploy user.

After a push, verify both sides:

readlink -f /data/www/homepage/current
curl -I https://www.example.com/

The symlink target should be the commit that GitHub Actions deployed, and the edge response should be successful.

5. Firewall changes must preserve existing VPN services

This server also acted as a WireGuard gateway on wg0, with the gateway at 10.8.0.1 and a local DNS resolver on port 53. Enabling UFW with only SSH, HTTP, and HTTPS rules silently broke the VPN:

  1. macOS preferred 10.8.0.1 as its DNS resolver.
  2. UFW blocked the WireGuard UDP socket and/or DNS packets arriving on wg0.
  3. Browsers appeared unable to reach Google and the newly deployed website.
  4. A curl --resolve request succeeded, proving that HTTPS worked and isolating the failure to DNS over the VPN.

Before enabling a firewall, inventory existing listeners and routes:

ss -lntup
ip -br address
ip route show
systemctl --type=service --state=running

For a WireGuard gateway, preserve these categories of traffic. Replace the port with the ListenPort from wg0.conf:

sudo ufw allow <WIREGUARD_PORT>/udp
sudo ufw allow in on wg0 to 10.8.0.1 port 53 proto udp
sudo ufw allow in on wg0 to 10.8.0.1 port 53 proto tcp
sudo ufw route allow in on wg0 out on eth0 from 10.8.0.0/24
sudo ufw reload

The final route rule is needed in addition to net.ipv4.ip_forward=1: forwarding enabled in the kernel does not override a firewall’s forward policy. If the VPN provides full internet egress, also ensure its existing NAT/MASQUERADE rule remains present.

From a client, test the gateway explicitly before blaming the public DNS:

dig @10.8.0.1 www.google.com +time=2 +tries=1
dig www.example.com
curl -I https://www.example.com/

6. Operate the next service the same way

For each future service.example.com:

  1. Give it a separate directory under /data/www.
  2. Run its application process as deploy, bound to 127.0.0.1 or a Unix socket.
  3. Give nginx a dedicated server_name and reverse-proxy rule.
  4. Add a proxied Cloudflare DNS record.
  5. Make origin TLS work before exposing the hostname.
  6. Add the service’s required ports, routes, and health checks to the firewall plan.

HSTS with includeSubDomains means every future subdomain must be HTTPS-ready from its first public use. This is a useful safety property, but it makes an HTTP-only test deployment under the production domain a bad idea.

Final checklist

With these boundaries in place, deploying another static site or introducing a reverse-proxied service becomes a repeatable operation rather than a fresh migration project.