- tsconfig (allowJs, strict .ts), npm run build -> dist/, typecheck, dev via tsx, ts-jest. - src/index.js is now a launcher (dist build when it matches, else tsx); server moved to app.js. - /api/v2: defineRoute with zod -> request validation, response stripping, OpenAPI 3.1 at /docs/v2; one error shape and one paged-list shape. First endpoints: events, event, me, my registrations. - deploy.sh/install.sh build the backend; rollback to older releases skips the build. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ls1vMdg2GYqbnKZmPaX1ot
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 --nginxcan't work the usual way. HTTPS ends either on the VPS or infrpc. - 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
frpcalready installed and connected (it runs as a systemd service, usuallyfrpc.service). - The site's DNS record (e.g.
events.yourchurch.org) points at the VPS. - On the VPS,
frps.inihasvhost_http_portset (andvhost_https_portfor 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 usesfrpc.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
- Open
https://events.yourchurch.org/health— it should answer with the version. - Open
https://events.yourchurch.org/setup: create the admin account. - 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). - 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"(only127.0.0.1after the real address): good,TRUST_PROXY=loopbackis 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, thenpm2 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 = v2on the frpc section plus nginx'slisten … proxy_protocolandset_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 (the backend too,
since 1.51.0) 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.
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. |