# shellcheck shell=bash # 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 --products events|accounts --domain
[options] 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.env. If a step fails, everything this run created is removed again. --products the product to install first (events or accounts; add more with `crosscode add`) --domain
the church's address: hopefamily.co.za or hopefamily.crosscode.co.za; the product is served on .
--events-domain serve the product somewhere other than .
--accounts-domain (the same, for Accounts) --version events@x.y.z that release (default: the latest) --main the latest main (staging churches only) --user the Linux user the apps run as (default: cc-) --api-port Events backend port (default: the first free one from 5000) --web-port 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 for Let's Encrypt notices (required unless --frp or --no-ssl) --no-ssl no certificate (behind another proxy that does HTTPS) --config 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 } # Ports in use: every church's *_PORTS on this server, and anything listening now. used_ports() { local f for f in "$CROSSCODE_SITES"/*/church.env; do [ -f "$f" ] && sed -nE 's/^[A-Z]+_PORTS="?([0-9 ]+)"?.*/\1/p' "$f" | tr ' ' '\n' done ss -ltnH 2>/dev/null | awk '{ n = split($4, a, ":"); print a[n] }' return 0 } # free_port : the first port from not in the list. free_port() { local p="$1" shift while printf '%s\n' "$@" | grep -qx "$p"; do p=$((p + 1)); done echo "$p" } 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="" pdomain="" 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 ;; --domain) address="$2"; shift 2 ;; --events-domain|--accounts-domain) pdomain="$2"; shift 2 ;; --email) email="$2"; shift 2 ;; --version) version="$2"; shift 2 ;; --main) main=1; shift ;; --user) user="$2"; shift 2 ;; --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 ;; esac done [ -n "$church" ] || { install_usage; die "Name the church."; } valid_slug "$church" || die "\"$church\" isn't a church name (a-z, 0-9 and -, starting with a letter)." [ -n "$products" ] || die "--products is required (e.g. --products events)." local p product="" for p in $products; do is_known_product "$p" || die "Unknown product \"$p\"." [ "$p" = events ] || [ "$p" = accounts ] || die "This version of crosscode can only install events and accounts." [ -z "$product" ] || die "One product per install; add the others with \`crosscode add\`." product="$p" 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." pdomain="${pdomain:-$product.$address}" [[ "$pdomain" =~ ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?\.[a-z]{2,}$ ]] || die "--$product-domain: expected a domain." install_check_options "$product" "$ssl" "$email" "$version" "$main" "$frp" "$api" "$web" user="${user:-cc-$church}" user="${user:0:32}" require_root [ ! -f "$(church_env_path "$church")" ] || die "$church is already installed here (crosscode status $church). Add products with \`crosscode add $church \`." [ ! -e "$(church_dir "$church")" ] || die "$(church_dir "$church") exists without a church.env. Move it away first." read -r api web <<< "$(install_ports "$api" "$web")" report_result church "$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 mkdir -p "$(church_dir "$church")" undo_add dir "$(church_dir "$church")" chmod 755 "$CROSSCODE_SITES" "$(church_dir "$church")" CENV=() church_env_set CHURCH "$church" church_env_set PRODUCTS "$product" church_env_set ADDRESS "$address" install_product "$product" "$church" "$user" "$pdomain" "$api" "$web" "$version" "$main" "$ssl" "$email" "$frp" church_env_write "$(church_env_path "$church")" ) rc=$? set -e install_finish "$rc" "$keep" "$church" install_done "$church" "$product" "$pdomain" "$api" "$web" "$frp" } # The checks every install and add share, before anything is touched. install_check_options() { local product="$1" ssl="$2" email="$3" version="$4" main="$5" frp="$6" api="$7" web="$8" [ "$ssl" = 0 ] || [ -n "$email" ] || die "--email is required for the certificate (or use --frp or --no-ssl)." [ -z "$version" ] || [[ "$version" =~ ^$product@[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || die "--version: expected $product@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 return 0 } # " ": the ones given (checked free), or the first free from 5000 / 3000. install_ports() { local api="$1" web="$2" 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." printf '%s %s\n' "$api" "$web" } # install_product
install_product() { local product="$1" shift if [ "${10}" = 1 ]; then command -v "$FRPC_BIN" >/dev/null || die "frpc isn't installed here ($FRPC_BIN)." frpc_check_format fi report_result_json ports "{\"$product\":{\"web\":$5,\"api\":$4}}" report_result_json domains "{\"$product\":\"$3\"}" case "$product" in events) install_events "$@" ;; accounts) install_accounts "$@" ;; *) die "This version of crosscode can't install $product." ;; esac } # After the subshell: undo what was made if it failed (unless --keep-on-failure). install_finish() { local rc="$1" keep="$2" church="$3" 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" } install_done() { local church="$1" product="$2" domain="$3" api="$4" web="$5" frp="$6" step "Done" if [ "$frp" = 1 ]; then info "Tunnels: $church-$product-web → $web, $church-$product-api → $api. Set up the site on the central server." else info "DNS (if not set yet): $domain → this server (A record, or a CNAME)." fi info "Open https://$domain/setup to create the admin account." if [ "$product" = accounts ]; then info "Updates: crosscode deploy $church (Accounts is always updated first)"; else info "Updates: crosscode deploy $church $product"; fi } add_usage() { cat <<'EOF' crosscode add [options] Adds a product to a church already installed here (from phase 3: Accounts next to Events), in its own folder, database, PM2 processes and site, run by the church's app user. If a step fails, what this run made is removed again; the church's other products aren't touched. --domain where it's served (default: .) --version @x.y.z that release (default: the latest) --main the latest main (staging churches only) --api-port backend port (default: the first free one from 5000) --web-port frontend port (default: the first free one from 3000) --frp behind frp: tunnels in frpc.ini (ports must be given); no nginx here --email for Let's Encrypt notices (required unless --frp or --no-ssl) --no-ssl no certificate (behind another proxy that does HTTPS) --config the .env values by layer (JSON; given by the agent) --keep-on-failure leave what was made if a step fails --json print a report (JSON) at the end EOF } cmd_add() { local church="" product="" domain="" email="" version="" main=0 api="" web="" ssl=1 frp=0 keep=0 while [ $# -gt 0 ]; do case "$1" in --domain) domain="$2"; shift 2 ;; --email) email="$2"; shift 2 ;; --version) version="$2"; shift 2 ;; --main) main=1; shift ;; --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) add_usage; return 0 ;; -*) die "Unknown option $1 (crosscode add --help)." ;; *) if [ -z "$church" ]; then church="$1" elif [ -z "$product" ]; then product="$1" else die "crosscode add : one product at a time." fi shift ;; esac done [ -n "$church" ] && [ -n "$product" ] || { add_usage; die "Name the church and the product."; } valid_slug "$church" || die "\"$church\" isn't a church name." is_known_product "$product" || die "Unknown product \"$product\"." [ "$product" = events ] || [ "$product" = accounts ] || die "This version of crosscode can only add events and accounts." install_check_options "$product" "$ssl" "$email" "$version" "$main" "$frp" "$api" "$web" require_root load_church "$church" ! church_has_product "$product" || die "$church already has $product (crosscode status $church)." local address user="" existing address="$(cenv ADDRESS)" [ -n "$domain" ] || [ -n "$address" ] || die "--domain is needed: the church has no address in church.env." domain="${domain:-$product.$address}" [[ "$domain" =~ ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?\.[a-z]{2,}$ ]] || die "--domain: expected a domain." [ ! -e "$(church_dir "$church")/$product" ] || die "$(church_dir "$church")/$product exists already. Move it away first." # The church's app user: the one its other products run as. for existing in $(cenv PRODUCTS); do user="$(pvar "$existing" USER)" [ -z "$user" ] || break done user="${user:-cc-$church}" id "$user" >/dev/null 2>&1 || die "The church's app user $user doesn't exist." read -r api web <<< "$(install_ports "$api" "$web")" report_result church "$church" INSTALL_UNDO="$(mktemp)" local rc set +e ( set -e command -v pm2 >/dev/null || install_system_packages "$ssl" "$frp" install_product "$product" "$church" "$user" "$domain" "$api" "$web" "$version" "$main" "$ssl" "$email" "$frp" local -a all # shellcheck disable=SC2046 # the product names are single words mapfile -t all < <(in_product_order $(cenv PRODUCTS) "$product") church_env_set PRODUCTS "${all[*]}" church_env_write "$(church_env_path "$church")" ) rc=$? set -e install_finish "$rc" "$keep" "$church" install_done "$church" "$product" "$domain" "$api" "$web" "$frp" } install_system_packages() { local ssl="$1" frp="$2" step "System packages" export DEBIAN_FRONTEND=noninteractive apt-get update -q 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 step "Node.js 24" curl -fsSL https://deb.nodesource.com/setup_24.x | bash - apt-get install -y -q nodejs fi command -v pm2 >/dev/null || npm install -g pm2 } install_events() { 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" 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 "$dir" undo_add dir "$dir" chown "$user:$user" "$dir" run_as "$user" "$dir" git clone --quiet "$CROSSCODE_REPO" . run_as "$user" "$dir" git fetch --tags --force --quiet origin if [ "$main" = 1 ]; then version=origin/main elif [ -z "$version" ]; then version="$(latest_tag "$dir" 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" ref="$(checkout_ref "$dir" events)" info "At $ref" report_result_json versions "{\"events\":\"$ref\"}" 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" 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" "$app/frontend/.env.production" events_ensure_pm2_config "$dir" "$user" step "Events: install, migrate, build" events_install_deps "$dir" "$user" events_migrate "$dir" "$user" 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 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_site_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 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_accounts() { 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/accounts.sh" dir="$(church_dir "$church")/accounts" app="$dir/apps/accounts" db="$(printf '%s_accounts' "$church" | tr '-' '_')" name="$church-accounts" church_env_set ACCOUNTS_DIR "$dir" church_env_set ACCOUNTS_DOMAIN "$domain" church_env_set ACCOUNTS_PM2 "$name-backend $name-frontend" church_env_set ACCOUNTS_PORTS "$api $web" church_env_set ACCOUNTS_DB "$db" church_env_set ACCOUNTS_USER "$user" [ "$frp" = 0 ] || church_env_set ACCOUNTS_FRP 1 step "Accounts: code ($dir)" mkdir -p "$dir" undo_add dir "$dir" chown "$user:$user" "$dir" run_as "$user" "$dir" git clone --quiet "$CROSSCODE_REPO" . run_as "$user" "$dir" git fetch --tags --force --quiet origin if [ "$main" = 1 ]; then version=origin/main elif [ -z "$version" ]; then version="$(latest_tag "$dir" accounts)" [ -n "$version" ] || die "No accounts@x.y.z release tags yet (use --version or --main)." fi run_as "$user" "$dir" git checkout -q --detach "$version" ref="$(checkout_ref "$dir" accounts)" info "At $ref" report_result_json versions "{\"accounts\":\"$ref\"}" step "Accounts: database ($db on $(db_host))" ! 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 "Accounts: configuration" local trust=1 [ "$frp" = 0 ] || trust=loopback ( export CROSSCODE_GEN_NODE_ENV=production export CROSSCODE_GEN_ACCOUNTS_SECRET CROSSCODE_GEN_ACCOUNTS_SECRET="$(random_secret 64)" export CROSSCODE_GEN_DATABASE_URL="postgresql://$db:$pass@$(db_host):$(db_port)/$db" env_apply "$app" accounts "$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" "$app/frontend/.env.production" accounts_ensure_pm2_config "$dir" "$user" step "Accounts: install, migrate, build" accounts_install_deps "$dir" "$user" accounts_migrate "$dir" "$user" accounts_build "$dir" "$user" step "Accounts: PM2" undo_add pm2 "$user" "$name-backend $name-frontend" run_as "$user" "$app" pm2 startOrReload ecosystem.config.cjs run_as "$user" "$app" pm2 save if [ "$frp" = 1 ]; then step "Accounts: frpc tunnels" frpc_add "$church" accounts "$web" "$api" undo_add frpc "$church" accounts frpc_reload else step "Accounts: nginx ($domain)" install_site_nginx "$name" "$domain" "$api" "$web" undo_add nginx "$name" if [ "$ssl" = 1 ]; then step "Accounts: certificate" certbot --nginx -d "$domain" --non-interactive --agree-tos -m "$email" --redirect fi fi step "Accounts: checking it answers" wait_for_version "$(accounts_health_url)" "$(accounts_expected_version "$dir")" 90 || die "The backend didn't answer with its version (sudo -u $user pm2 logs $name-backend)." } install_site_nginx() { local name="$1" domain="$2" api="$3" web="$4" # Only this domain is served by this site (no catch-all), as ROADMAP §8 asks. cat > "/etc/nginx/sites-available/$name" <