crosscode: --json reports, --config, env templates, frpc tunnels, restart/export/uninstall/purge

- Every command takes --json (crosscode.script-report/1 on stdout, the
  log on stderr) and --config (the .env values by layer, from the agent).
- .env files come from the release's env.template.json (lib/envtpl.js):
  written whole on install; on deploy only new variables are appended,
  and a new required one with no value stops the deploy at the checks.
- install --frp: Hub-given ports, a marked frpc.ini block (backup,
  frpc verify, reload; [common] admin lines added once), no nginx.
  A database on another server via DB_ADMIN_URL. Refuses an existing
  database or role. Everything the run made is removed if it fails.
- restart, export (crosscode.church-export/1 ZIP), uninstall (final
  backup, uploads and .env kept 30 days) and purge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 12:50:19 +02:00
co-authored by Claude Opus 5.5
parent 350ab9f4e8
commit e9e9b5a97f
17 changed files with 1308 additions and 88 deletions
+141 -77
View File
@@ -1,26 +1,34 @@
# shellcheck shell=bash
# crosscode install: a new church on this server (from hope-events' scripts/install.sh 2.1.x).
# Events only in 2.2.0; Accounts, Website and App follow as their products/*.sh are added.
# crosscode install: a new church on this server (from hope-events' scripts/install.sh 2.1.x;
# behind frp from the Hub in agent 1.0, docs/AGENT-1.0-PLAN.md §7).
# Events only so far; Accounts, Website and App follow as their products/*.sh are added.
install_usage() {
cat <<'EOF'
crosscode install <church> --products events --domain <address> [options]
A new church: system packages (Node 24, PostgreSQL, PM2, nginx, certbot) if missing, then per
product an app user, database, checkout, .env, PM2 processes, nginx site and certificate.
Writes /var/www/sites/<church>/church.env. DNS must already point here (it prints the records).
A new church: system packages if missing, then per product an app user, database, checkout,
.env files (from the release's env.template.json), PM2 processes, and either an nginx site with
a certificate (a server with its own address) or frpc tunnels (--frp, behind the central
server). Writes /var/www/sites/<church>/church.env. If a step fails, everything this run created
is removed again.
--products events the products to install (only events in this version)
--domain <address> the church's address: hopefamily.co.za or hopefamily.crosscode.co.za;
Events is served on events.<address>
--events-domain <domain> serve Events somewhere else instead
--email <email> for Let's Encrypt notices (required unless --no-ssl)
--version events@x.y.z that release (default: the latest)
--main the latest main (staging churches only)
--user <name> the Linux user the apps run as (default: cc-<church>)
--api-port <n> Events backend port (default: the first free one from 5000)
--web-port <n> Events frontend port (default: the first free one from 3000)
--frp behind frp: add tunnels to frpc.ini (ports must be given, and are
used for the tunnel too); no nginx or certificate here
--email <email> for Let's Encrypt notices (required unless --frp or --no-ssl)
--no-ssl no certificate (behind another proxy that does HTTPS)
--config <file> the .env values by layer (JSON; given by the agent)
--keep-on-failure leave what was made if a step fails (to look into it)
--json print a report (JSON) at the end; the log goes to stderr
EOF
}
@@ -44,8 +52,30 @@ free_port() {
random_secret() { openssl rand -base64 64 | tr -d '/+=\n' | head -c "${1:-48}"; }
# ── Undo: what this run made, undone in reverse if it fails ──────────────────────────────────
INSTALL_UNDO=""
undo_add() { [ -z "$INSTALL_UNDO" ] || printf '%s\n' "$*" >> "$INSTALL_UNDO"; }
install_undo() {
local kind a b
step "Removing what this install made"
tac "$INSTALL_UNDO" | while read -r kind a b; do
case "$kind" in
pm2) # shellcheck disable=SC2086 # b is a space-separated list of PM2 names
run_as "$a" / pm2 delete $b >/dev/null 2>&1 || true
run_as "$a" / pm2 save --force >/dev/null 2>&1 || true
info "PM2: $b removed" ;;
frpc) frpc_remove "$a" "$b" && frpc_reload || warn "frpc block $a:$b not removed" ;;
nginx) rm -f "/etc/nginx/sites-enabled/$a" "/etc/nginx/sites-available/$a"; systemctl reload nginx 2>/dev/null || true; info "nginx: $a removed" ;;
db) db_drop "$a" >/dev/null 2>&1 && info "database $a removed" || warn "database $a not removed" ;;
dir) rm -rf -- "$a" && info "$a removed" ;;
user) pkill -u "$a" 2>/dev/null || true; userdel -r "$a" >/dev/null 2>&1 && info "user $a removed" || true ;;
esac
done
}
cmd_install() {
local church="" products="" address="" events_domain="" email="" version="" main=0 user="" api="" web="" ssl=1
local church="" products="" address="" events_domain="" email="" version="" main=0 user="" api="" web="" ssl=1 frp=0 keep=0
while [ $# -gt 0 ]; do
case "$1" in
--products) products="$(printf '%s' "$2" | tr ',' ' ')"; shift 2 ;;
@@ -58,6 +88,8 @@ cmd_install() {
--api-port) api="$2"; shift 2 ;;
--web-port) web="$2"; shift 2 ;;
--no-ssl) ssl=0; shift ;;
--frp) frp=1; ssl=0; shift ;;
--keep-on-failure) keep=1; shift ;;
-h|--help) install_usage; return 0 ;;
-*) die "Unknown option $1 (crosscode install --help)." ;;
*) [ -z "$church" ] || die "One church at a time."; church="$1"; shift ;;
@@ -73,43 +105,84 @@ cmd_install() {
done
[[ "$address" =~ ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?\.[a-z]{2,}$ ]] || die "--domain: give the church's address, e.g. hopefamily.co.za."
events_domain="${events_domain:-events.$address}"
[ "$ssl" = 0 ] || [ -n "$email" ] || die "--email is required for the certificate (or use --no-ssl)."
[[ "$events_domain" =~ ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?\.[a-z]{2,}$ ]] || die "--events-domain: expected a domain."
[ "$ssl" = 0 ] || [ -n "$email" ] || die "--email is required for the certificate (or use --frp or --no-ssl)."
[ -z "$version" ] || [[ "$version" =~ ^events@[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || die "--version: expected events@x.y.z."
[ "$main" = 0 ] || [ -z "$version" ] || die "Use --main or --version, not both."
if [ "$frp" = 1 ]; then
[ -n "$api" ] && [ -n "$web" ] || die "--frp needs --api-port and --web-port (from the Hub's port list)."
fi
user="${user:-cc-$church}"
user="${user:0:32}"
require_root
[ ! -f "$(church_env_path "$church")" ] || die "$church is already installed here (crosscode status $church). New products for it come with \`crosscode add\` (phase 3)."
[ ! -e "$(church_dir "$church")" ] || die "$(church_dir "$church") exists without a church.env. Move it away first."
local taken
mapfile -t taken < <(used_ports)
if [ -n "$api" ] && printf '%s\n' "${taken[@]}" | grep -qx "$api"; then die "Port $api is already in use here."; fi
if [ -n "$web" ] && printf '%s\n' "${taken[@]}" | grep -qx "$web"; then die "Port $web is already in use here."; fi
api="${api:-$(free_port 5000 "${taken[@]}")}"
web="${web:-$(free_port 3000 "${taken[@]}" "$api")}"
[[ "$api" =~ ^[0-9]+$ && "$web" =~ ^[0-9]+$ && "$api" != "$web" ]] || die "Ports must be two different numbers."
if [ "$frp" = 1 ]; then
command -v "$FRPC_BIN" >/dev/null || die "frpc isn't installed here ($FRPC_BIN)."
frpc_check_format
fi
report_result church "$church"
report_result_json ports "{\"events\":{\"web\":$web,\"api\":$api}}"
report_result_json domains "{\"events\":\"$events_domain\"}"
install_system_packages "$ssl"
step "App user ($user)"
id "$user" >/dev/null 2>&1 || useradd --create-home --shell /bin/bash "$user"
CENV=()
church_env_set CHURCH "$church"
church_env_set PRODUCTS "events"
church_env_set ADDRESS "$address"
install_events "$church" "$user" "$events_domain" "$api" "$web" "$version" "$main" "$ssl" "$email"
church_env_write "$(church_env_path "$church")"
INSTALL_UNDO="$(mktemp)"
local rc
set +e
(
set -e
install_system_packages "$ssl" "$frp"
step "App user ($user)"
if ! id "$user" >/dev/null 2>&1; then
useradd --create-home --shell /bin/bash "$user"
undo_add user "$user"
fi
CENV=()
church_env_set CHURCH "$church"
church_env_set PRODUCTS "events"
church_env_set ADDRESS "$address"
install_events "$church" "$user" "$events_domain" "$api" "$web" "$version" "$main" "$ssl" "$email" "$frp"
church_env_write "$(church_env_path "$church")"
)
rc=$?
set -e
if [ "$rc" != 0 ]; then
if [ "$keep" = 1 ]; then
warn "Install failed; --keep-on-failure: what was made is left in place ($(church_dir "$church"))."
else
install_undo
fi
rm -f "$INSTALL_UNDO"
die "Install of $church failed."
fi
rm -f "$INSTALL_UNDO"
step "Done"
info "DNS (if not set yet): $events_domain → this server (A record, or a CNAME)."
info "Open https://$events_domain/setup to create the admin account, then enter the licence key."
if [ "$frp" = 1 ]; then
info "Tunnels: $church-events-web → $web, $church-events-api → $api. Set up the site on the central server."
else
info "DNS (if not set yet): $events_domain → this server (A record, or a CNAME)."
fi
info "Open https://$events_domain/setup to create the admin account."
info "Updates: crosscode deploy $church events"
}
install_system_packages() {
local ssl="$1"
local ssl="$1" frp="$2"
step "System packages"
export DEBIAN_FRONTEND=noninteractive
apt-get update -q
apt-get install -y -q curl git rsync nginx postgresql postgresql-client openssl build-essential ca-certificates gnupg
apt-get install -y -q curl git rsync zip postgresql-client openssl build-essential ca-certificates gnupg
# A database here, unless the server's configuration names another PostgreSQL server.
[ -n "$(cfg server DB_ADMIN_URL)" ] || apt-get install -y -q postgresql
[ "$frp" = 1 ] || apt-get install -y -q nginx
[ "$ssl" = 0 ] || apt-get install -y -q certbot python3-certbot-nginx
# Node 24 is the LTS line supported until April 2028.
if ! command -v node >/dev/null || [ "$(node_major)" -lt 24 ]; then
@@ -121,32 +194,29 @@ install_system_packages() {
}
install_events() {
local church="$1" user="$2" domain="$3" api="$4" web="$5" version="$6" main="$7" ssl="$8" email="$9"
local dir app db pass url name scheme
local church="$1" user="$2" domain="$3" api="$4" web="$5" version="$6" main="$7" ssl="$8" email="$9" frp="${10}"
local dir app db pass name ref
# shellcheck source=/dev/null
source "$CROSSCODE_HOME/products/events.sh"
dir="$(church_dir "$church")/events"
app="$dir/apps/events"
db="$(printf '%s_events' "$church" | tr '-' '_')"
name="$church-events"
scheme=https
[ "$ssl" = 1 ] || scheme=http
url="$scheme://$domain"
church_env_set EVENTS_DIR "$dir"
church_env_set EVENTS_DOMAIN "$domain"
church_env_set EVENTS_PM2 "$name-backend $name-frontend"
church_env_set EVENTS_PORTS "$api $web"
church_env_set EVENTS_DB "$db"
church_env_set EVENTS_USER "$user"
[ "$frp" = 0 ] || church_env_set EVENTS_FRP 1
step "Events: code ($dir)"
mkdir -p "$(church_dir "$church")"
undo_add dir "$(church_dir "$church")"
chmod 755 "$CROSSCODE_SITES" "$(church_dir "$church")"
if [ ! -d "$dir/.git" ]; then
mkdir -p "$dir"
chown "$user:$user" "$dir"
run_as "$user" "$dir" git clone --quiet "$CROSSCODE_REPO" .
fi
mkdir -p "$dir"
chown "$user:$user" "$dir"
run_as "$user" "$dir" git clone --quiet "$CROSSCODE_REPO" .
run_as "$user" "$dir" git fetch --tags --quiet origin
if [ "$main" = 1 ]; then
version=origin/main
@@ -155,47 +225,31 @@ install_events() {
[ -n "$version" ] || die "No events@x.y.z release tags yet (use --version or --main)."
fi
run_as "$user" "$dir" git checkout -q --detach "$version"
info "At $(checkout_ref "$dir" events)"
ref="$(checkout_ref "$dir" events)"
info "At $ref"
report_result_json versions "{\"events\":\"$ref\"}"
step "Events: database ($db)"
# Re-running keeps the password already in backend/.env; otherwise a new one.
pass=""
if [ -f "$app/backend/.env" ]; then
pass="$(env_value "$app/backend/.env" DATABASE_URL | sed -nE 's#^postgresql://[^:]+:([^@]+)@.*#\1#p')"
fi
pass="${pass:-$(random_secret 32)}"
sudo -u postgres psql -v ON_ERROR_STOP=1 -q <<SQL
DO \$\$ BEGIN
IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '$db') THEN
CREATE ROLE "$db" LOGIN PASSWORD '$pass';
ELSE
ALTER ROLE "$db" WITH LOGIN PASSWORD '$pass';
END IF;
END \$\$;
SQL
sudo -u postgres psql -tAc "SELECT 1 FROM pg_database WHERE datname = '$db'" | grep -q 1 ||
sudo -u postgres createdb -O "$db" "$db"
step "Events: database ($db on $(db_host))"
# Never reuse (or later drop) a database or role that something else may be using.
! db_exists "$db" || die "A database or role named $db already exists on $(db_host). Remove it first if it's left over, or choose another church name."
pass="$(random_secret 32)"
undo_add db "$db"
db_create "$db" "$pass"
step "Events: configuration"
if [ ! -f "$app/backend/.env" ]; then
cat > "$app/backend/.env" <<ENV
NODE_ENV=production
PORT=$api
DATABASE_URL=postgresql://$db:$pass@localhost:5432/$db
JWT_SECRET=$(random_secret 64)
FRONTEND_URL=$url
APP_BASE_URL=$url
BACKEND_URL=$url
TRUST_PROXY=1
APP_TIMEZONE=Africa/Johannesburg
ENV
info "Wrote backend/.env (keep JWT_SECRET: it also encrypts stored secrets)."
else
info "backend/.env exists: kept."
fi
[ -f "$app/frontend/.env.production" ] || echo "NEXT_PUBLIC_API_URL=$url" > "$app/frontend/.env.production"
local trust=1
[ "$frp" = 0 ] || trust=loopback
(
export CROSSCODE_GEN_NODE_ENV=production
export CROSSCODE_GEN_JWT_SECRET
CROSSCODE_GEN_JWT_SECRET="$(random_secret 64)"
export CROSSCODE_GEN_DATABASE_URL="postgresql://$db:$pass@$(db_host):$(db_port)/$db"
env_apply "$app" events "$ref" --var "domain=$domain" --var "apiPort=$api" --var "webPort=$web" --var "church=$church" \
--fallback "TRUST_PROXY=$trust"
) | sed 's/^/ /'
[ "${PIPESTATUS[0]}" = 0 ] || die "The .env files couldn't be written (see above)."
chown "$user:$user" "$app/backend/.env" "$app/frontend/.env.production"
chmod 600 "$app/backend/.env"
chmod 600 "$app/backend/.env" "$app/frontend/.env.production"
events_ensure_pm2_config "$dir" "$user"
step "Events: install, migrate, build"
@@ -204,20 +258,29 @@ ENV
events_build "$dir" "$user"
step "Events: PM2"
undo_add pm2 "$user" "$name-backend $name-frontend"
run_as "$user" "$app" pm2 startOrReload ecosystem.config.js
run_as "$user" "$app" pm2 save
env PATH="$PATH:/usr/bin" pm2 startup systemd -u "$user" --hp "$(getent passwd "$user" | cut -d: -f6)" >/dev/null
step "Events: nginx ($domain)"
install_events_nginx "$name" "$domain" "$api" "$web"
if [ "$ssl" = 1 ]; then
step "Events: certificate"
certbot --nginx -d "$domain" --non-interactive --agree-tos -m "$email" --redirect
if [ "$frp" = 1 ]; then
step "Events: frpc tunnels"
frpc_add "$church" events "$web" "$api"
undo_add frpc "$church" events
frpc_reload
else
step "Events: nginx ($domain)"
install_events_nginx "$name" "$domain" "$api" "$web"
undo_add nginx "$name"
if [ "$ssl" = 1 ]; then
step "Events: certificate"
certbot --nginx -d "$domain" --non-interactive --agree-tos -m "$email" --redirect
fi
fi
step "Events: checking"
wait_for_version "$(events_health_url)" "$(events_expected_version "$dir")" 60 ||
warn "The backend isn't answering yet: sudo -u $user pm2 logs"
step "Events: checking it answers"
wait_for_version "$(events_health_url)" "$(events_expected_version "$dir")" 90 ||
die "The backend didn't answer with its version (sudo -u $user pm2 logs $name-backend)."
}
install_events_nginx() {
@@ -230,6 +293,7 @@ server {
client_max_body_size 25m;
# The API, uploaded files, health and API docs go to the backend; everything else to the site.
# (From Events 2.2.0 everything is under /api; the other paths are for older releases.)
location ~ ^/(api|uploads|health|docs)(/|\$) {
proxy_pass http://127.0.0.1:$api;
proxy_set_header Host \$host;