Files
crosscode-platform/apps/events/DEPLOYMENT.md
T
joshuaandClaude Opus 5.5 0367e0ca6d Rename the product to Cross Events in UI text and docs
Display text only: storage keys, slugs, the encryption salt, the repo URL
and applied migrations keep their old names so existing installs keep working.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 13:06:20 +02:00

13 KiB

Deploying Cross Events behind frp

This guide is for a server that is not reachable from the internet directly: it runs frpc, which opens a tunnel to frps on a public server (the "VPS"). Visitors reach the VPS, and frp carries the traffic through to this server. The frp client config lives at /etc/frp/frpc.ini.

For a server with a public IP, scripts/install.sh does everything (see the README). Behind frp it needs a few changes, because:

  • HTTPS can't be set up by the installer. DNS points at the VPS, not at this server, so certbot --nginx can't work the usual way. HTTPS ends either on the VPS or in frpc.
  • There are more proxies in the way. The app must be told which of them to trust, or it sees every visitor as 127.0.0.1 (rate limiting then treats everyone as one person, and PayFast payment notifications fail their IP check).
  • The app must know the site is HTTPS even though nginx on this server only speaks HTTP; otherwise it builds http:// links (event images, payment return URLs).

1. How the traffic flows

Pick the setup that matches how your other frp sites get HTTPS.

A. HTTPS ends on the VPS (nginx/Caddy on the VPS holds the certificate) — recommended if the VPS already does this for other sites:

visitor ──https──▶ VPS nginx/Caddy ──http──▶ frps (vhost_http_port) ══tunnel══▶ frpc ──▶ nginx :80 ──▶ app

B. HTTPS ends in frpc (the VPS only runs frps; the certificate lives on this server and frpc's https2http plugin uses it):

visitor ──https──▶ frps (vhost_https_port) ══tunnel══▶ frpc https2http ──▶ nginx 127.0.0.1:8080 ──▶ app
visitor ──http───▶ frps (vhost_http_port)  ══tunnel══▶ frpc ──▶ nginx :80 (certificate check + redirect to https)

On this server, nginx sends /api, /uploads, /health and /docs to the backend (port 5000) and everything else to the Next.js site (port 3000), the same as a normal install.

2. Before you start

  • Ubuntu 22.04 or 24.04 on this server, with frpc already installed and connected (it runs as a systemd service, usually frpc.service).
  • The site's DNS record (e.g. events.yourchurch.org) points at the VPS.
  • On the VPS, frps.ini has vhost_http_port set (and vhost_https_port for setup B). Note the values; you need them below.
  • The licence key for this site from the Cross Events Hub.

3. Install the app

On this server, as root, run the installer without its certificate step:

curl -fsSLO https://c-git.crosscode.co.za/joshua/hope-events/raw/branch/main/scripts/install.sh
sudo bash install.sh --domain events.yourchurch.org --no-ssl --version v1.41.2

It installs Node 20, PostgreSQL, PM2 and nginx, creates the database, writes the config, builds and starts the app (in /opt/hope-events, run by the hopeevents user). Use --name, --dir, --web-port and --api-port if other apps already use those names or ports; adjust the ports below to match.

Switch the URLs to https

With --no-ssl the installer writes http:// addresses. Change them to https://:

cd /opt/hope-events
sudo sed -i 's#=http://#=https://#' backend/.env frontend/.env.production
grep -E 'URL=' backend/.env frontend/.env.production   # all should now start with https://

While backend/.env is open, set which proxies to trust (all of them run on loopback in both setups; see step 7 to confirm):

sudo sed -i 's#^TRUST_PROXY=.*#TRUST_PROXY=loopback#' backend/.env

NEXT_PUBLIC_API_URL is baked in when the site is built, so rebuild the frontend and restart:

sudo -u hopeevents -H bash -lc 'cd /opt/hope-events/frontend && npm run build'
sudo -u hopeevents -H bash -lc 'cd /opt/hope-events && pm2 reload ecosystem.config.js --update-env'

Keep JWT_SECRET in backend/.env as it is: it also encrypts the secrets stored in the database (SMTP, payment keys).

4. nginx on this server

The installer wrote /etc/nginx/sites-available/hope-events. Replace it with the version for your setup, changing the domain (and the ports if you changed them).

Setup A (HTTPS on the VPS)

# Shows the forwarded-for chain in the access log (see step 7). Safe to keep.
log_format hope_proxy '$remote_addr xff="$http_x_forwarded_for" "$request" $status';

server {
    listen 80;
    server_name events.yourchurch.org;
    client_max_body_size 25m;
    access_log /var/log/nginx/hope-events.access.log hope_proxy;

    # Visitors only reach this through the VPS over HTTPS, so tell the app so.
    location ~ ^/(api|uploads|health|docs)(/|$) {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

The VPS nginx/Caddy must redirect plain HTTP to HTTPS and pass the Host header through to frps unchanged (frps picks the site by its host name). For nginx on the VPS, roughly:

server {
    listen 443 ssl;
    server_name events.yourchurch.org;
    # ssl_certificate / ssl_certificate_key from certbot on the VPS
    client_max_body_size 25m;
    location / {
        proxy_pass http://127.0.0.1:8080;          # frps vhost_http_port
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Setup B (HTTPS in frpc)

Port 80 only answers certificate checks and redirects everything else; the real site is on 127.0.0.1:8080, which only frpc's https2http plugin reaches.

log_format hope_proxy '$remote_addr xff="$http_x_forwarded_for" "$request" $status';

server {
    listen 80;
    server_name events.yourchurch.org;
    location /.well-known/acme-challenge/ { root /var/www/certbot; }
    location / { return 301 https://$host$request_uri; }
}

server {
    listen 127.0.0.1:8080;
    server_name events.yourchurch.org;
    client_max_body_size 25m;
    access_log /var/log/nginx/hope-events.access.log hope_proxy;

    location ~ ^/(api|uploads|health|docs)(/|$) {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Then, for either setup:

sudo mkdir -p /var/www/certbot          # setup B only
sudo nginx -t && sudo systemctl reload nginx

5. frpc: /etc/frp/frpc.ini

Back it up first, then add a section for the site below the existing ones. Leave [common] (server address, port, token) and the other sections as they are. Section names must be unique across everything connected to your frps.

sudo cp /etc/frp/frpc.ini /etc/frp/frpc.ini.bak-$(date +%F)
sudo nano /etc/frp/frpc.ini

Setup A

[hope-events-http]
type = http
local_ip = 127.0.0.1
local_port = 80
custom_domains = events.yourchurch.org

Setup B

# Plain HTTP: certificate checks and the redirect to https
[hope-events-http]
type = http
local_ip = 127.0.0.1
local_port = 80
custom_domains = events.yourchurch.org

# HTTPS: frpc holds the certificate and passes plain HTTP to nginx on 127.0.0.1:8080
[hope-events-https]
type = https
custom_domains = events.yourchurch.org
plugin = https2http
plugin_local_addr = 127.0.0.1:8080
plugin_crt_path = /etc/letsencrypt/live/events.yourchurch.org/fullchain.pem
plugin_key_path = /etc/letsencrypt/live/events.yourchurch.org/privkey.pem
plugin_header_X-Forwarded-Proto = https

Restart frpc and check it registered the new sections without errors:

sudo systemctl restart frpc
sudo journalctl -u frpc -n 30 --no-pager      # look for "start proxy success" for each section

Newer frp releases (0.52+) prefer frpc.toml, but still read .ini. Don't mix the two: if your service already uses frpc.ini, keep adding to it.

Certificate (setup B only)

Request it through the tunnel with the webroot method (not --nginx, which would rewrite the nginx config), then have renewals restart frpc so it loads the new certificate:

sudo apt-get install -y certbot
sudo certbot certonly --webroot -w /var/www/certbot -d events.yourchurch.org \
  -m you@yourchurch.org --agree-tos --non-interactive
echo 'systemctl restart frpc' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/restart-frpc.sh
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-frpc.sh
sudo systemctl restart frpc

frpc needs to be able to read the certificate files (it does when it runs as root, the usual setup). If the [hope-events-https] section fails to start, check journalctl -u frpc.

6. Finish in the browser

  1. Open https://events.yourchurch.org/health — it should answer with the version.
  2. Open https://events.yourchurch.org/setup: create the admin account.
  3. Site settings → Licence: enter the licence key to connect to the Hub. The site checks in every 15 minutes from then on (outgoing HTTPS to events-hub.crosscode.co.za, which frp doesn't affect).
  4. Configure SMTP, payments (Yoco/PayFast webhooks use the https:// BACKEND_URL), branding, etc. in Site settings.

7. Check that visitor addresses come through

Open the site from your phone (on mobile data, so it isn't your own network), then on the server:

sudo tail -n 5 /var/log/nginx/hope-events.access.log

The xff="…" part is what the app sees, with nginx's own entry added at the end:

  • xff="<your phone's IP>, 127.0.0.1" (only 127.0.0.1 after the real address): good, TRUST_PROXY=loopback is right.
  • xff="<your phone's IP>, 203.0.113.10" (a non-local address after it, e.g. the VPS's): add that address: TRUST_PROXY=loopback,203.0.113.10, then pm2 reload ecosystem.config.js --update-env.
  • Your phone's IP doesn't appear at all: frp isn't passing the visitor's address on (can happen with setup B on some frp versions). Rate limiting and the PayFast IP check will then misbehave. Fix it by moving TLS to the VPS (setup A), or with frp's proxy_protocol_version = v2 on the frpc section plus nginx's listen … proxy_protocol and set_real_ip_from 127.0.0.1; real_ip_header proxy_protocol;.

The backend logs the setting it uses at startup: pm2 logs hope-events-backend | grep trust.

8. Updating

Nothing about frp changes for updates. On the server:

cd /opt/hope-events
sudo -u hopeevents -H bash scripts/deploy.sh v1.41.2     # or no tag for the latest main

It backs up the database, checks out the release, installs, migrates, builds and reloads PM2, and goes back to the previous version if anything fails first. backend/.env, frontend/.env.production, ecosystem.config.js and the nginx/frpc configs are not in git, so updates keep your changes from this guide.

Deploying from CI over SSH

The Gitea workflow deploys on a v* tag by SSHing to DEPLOY_HOST. Behind frp, that needs an SSH tunnel too, e.g. in frpc.ini:

[hope-events-ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6022

Then use the VPS as DEPLOY_HOST. The workflow's ssh call (.gitea/workflows/ci.yml) doesn't take a port yet, so add -p 6022 there (or a DEPLOY_PORT secret) before relying on it. Only open this if you need it: it exposes this server's SSH on the VPS. Use key-only login. Deploying by hand (above) needs none of this.

Troubleshooting

Symptom Likely cause
frps shows "404 Not Found" page The custom_domains value doesn't match the address typed, or frpc didn't start that section (journalctl -u frpc).
502 Bad Gateway nginx is up but the app isn't: sudo -u hopeevents pm2 ls and pm2 logs.
Site loads but login/API calls fail (CORS) FRONTEND_URL in backend/.env is still http://, or the frontend wasn't rebuilt after changing NEXT_PUBLIC_API_URL.
Images or links use http:// (browser "mixed content" warnings) nginx isn't sending X-Forwarded-Proto https, or TRUST_PROXY isn't set.
"Too many requests" for everyone at once All visitors look like one address: see step 7.
PayFast payments stay pending Same as above: the PayFast notification's IP check sees the proxy, not PayFast.
Uploads over ~1 MB fail client_max_body_size missing on this server's nginx or the VPS's.
Redirect loop (setup B) The site's server block is on port 80 instead of 127.0.0.1:8080, or plugin_local_addr points at port 80.