vela 0.10.2 → 0.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vela",
-	"version": "0.10.2",
+	"version": "0.10.3",
 	"type": "module",
 	"description": "A CLI for creating and updating SvelteKit projects",
 	"license": "MIT",

package/templates/server/apply.sh

@@ -0,0 +1,349 @@
+#!/usr/bin/env bash
+#
+# Activate an uploaded release for one instance.
+#
+# The CLI has already put the release files in place; everything that makes them
+# live happens here, in one transaction. If any step fails the previous release
+# is put back and the services are restarted before exiting non-zero.
+#
+# usage: apply.sh <instance> <release> [options]
+set -Eeuo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=lib.sh
+. "$SCRIPT_DIR/lib.sh"
+
+require_provisioned
+[ "$(id -u)" -eq 0 ] || die "apply must run as root"
+
+INSTANCE=${1:-}; shift || true
+RELEASE=${1:-}; shift || true
+[ -n "$INSTANCE" ] && [ -n "$RELEASE" ] || die "usage: apply.sh <instance> <release> [options]"
+
+APP_NAME=$INSTANCE
+APP_ID=$INSTANCE
+ENV_TAG=prod
+DOMAIN=""
+HEALTH_PATH=/
+KEEP=5
+PB_VERSION=""
+BACKEND=1
+GIT_SHA=""
+SU_CREATED=0
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--name) APP_NAME=$2; shift 2 ;;
+		--app-id) APP_ID=$2; shift 2 ;;
+		--env) ENV_TAG=$2; shift 2 ;;
+		--domain) DOMAIN=$2; shift 2 ;;
+		--health-path) HEALTH_PATH=$2; shift 2 ;;
+		--keep) KEEP=$2; shift 2 ;;
+		--pb-version) PB_VERSION=$2; shift 2 ;;
+		--backend) BACKEND=$2; shift 2 ;;
+		--git-sha) GIT_SHA=$2; shift 2 ;;
+		*) die "unknown argument: $1" ;;
+	esac
+done
+
+# Commands that drop to the app user inherit this working directory, and the
+# directory the CLI happened to invoke from is usually one it cannot stat.
+cd "$VELA_ROOT"
+
+APP=$(app_dir "$INSTANCE")
+ETC=$(etc_dir "$INSTANCE")
+RELEASE_DIR="$APP/releases/$RELEASE"
+WEB_UNIT=$(unit_web "$INSTANCE")
+PB_UNIT=$(unit_pb "$INSTANCE")
+
+[ -d "$RELEASE_DIR" ] || die "release $RELEASE was not uploaded to $RELEASE_DIR"
+[ -f "$RELEASE_DIR/build/index.js" ] || die \
+	"release $RELEASE has no build/index.js - the app must build with @sveltejs/adapter-node"
+
+mkdir -p "$APP"/{releases,shared,bin,deps} "$APP/shared/pb_data"
+mkdir -p "$ETC"
+chmod 0700 "$ETC"
+chown -R "$VELA_USER:$VELA_USER" "$APP"
+chown "$VELA_USER:$VELA_USER" "$RELEASE_DIR"
+
+# ---------------------------------------------------------------- ports & env
+
+PORTS=$(allocate_ports "$INSTANCE")
+WEB_PORT=$(printf '%s' "$PORTS" | jq -r .web)
+PB_PORT=$(printf '%s' "$PORTS" | jq -r .pb)
+
+PRIMARY_DOMAIN=$(printf '%s' "$DOMAIN" | cut -d, -f1 | tr -d ' ')
+if [ -n "$PRIMARY_DOMAIN" ]; then
+	ORIGIN="https://$PRIMARY_DOMAIN"
+else
+	ORIGIN="http://127.0.0.1:$WEB_PORT"
+fi
+
+# Production secrets live in $ETC/env and are managed only by `vela env`.
+# Nothing here reads or rewrites that file.
+[ -f "$ETC/env" ] || { : > "$ETC/env"; chmod 0600 "$ETC/env"; chown root:root "$ETC/env"; }
+
+runtime_tmp=$(mktemp "$ETC/.runtime.XXXXXX")
+{
+	printf '# Generated by vela on each deploy. Edit /etc/vela/apps/%s/env instead.\n' "$INSTANCE"
+	printf 'NODE_ENV=production\n'
+	printf 'HOST=127.0.0.1\n'
+	printf 'PORT=%s\n' "$WEB_PORT"
+	printf 'ORIGIN=%s\n' "$ORIGIN"
+	printf 'PB_PORT=%s\n' "$PB_PORT"
+	printf 'POCKETBASE_URL=http://127.0.0.1:%s\n' "$PB_PORT"
+	printf 'VELA_APP_ID=%s\n' "$APP_ID"
+	printf 'VELA_APP_NAME=%s\n' "$APP_NAME"
+	printf 'VELA_ENV=%s\n' "$ENV_TAG"
+	printf 'VELA_RELEASE=%s\n' "$RELEASE"
+} > "$runtime_tmp"
+chmod 0600 "$runtime_tmp"
+chown root:root "$runtime_tmp"
+mv -f "$runtime_tmp" "$ETC/runtime.env"
+
+# ------------------------------------------------------------------- runtime
+
+if [ "$BACKEND" = "1" ]; then
+	[ -n "$PB_VERSION" ] || die "--pb-version is required for an app with a backend"
+	PB_BIN=$("$SCRIPT_DIR/pocketbase.sh" "$PB_VERSION" | tail -1)
+	ln -sfn "$PB_BIN" "$APP/bin/.pocketbase.tmp"
+	mv -Tf "$APP/bin/.pocketbase.tmp" "$APP/bin/pocketbase"
+fi
+
+# --------------------------------------------------------------- dependencies
+#
+# node_modules is keyed by the lockfile hash and shared between releases that
+# pin the same dependencies: redeploys of unchanged dependencies skip the
+# install entirely, and a rollback still finds the tree its own lockfile
+# described.
+
+install_deps() {
+	local lock="$RELEASE_DIR/package-lock.json"
+	local key
+	local -a install_cmd
+	# `--no-engine-strict`: vela projects set engine-strict for development, but a
+	# production install takes only `dependencies` - a dev tool that wants a newer
+	# Node than the server runs is not a reason to refuse the deploy.
+	local -a flags=(--omit=dev --no-audit --no-fund --no-engine-strict --loglevel=error)
+	if [ -f "$lock" ]; then
+		key=$(sha256sum "$lock" | cut -c1-16)
+		install_cmd=(npm ci "${flags[@]}")
+	elif [ -f "$RELEASE_DIR/package.json" ]; then
+		key=$(sha256sum "$RELEASE_DIR/package.json" | cut -c1-16)
+		install_cmd=(npm install "${flags[@]}")
+	else
+		log "no package.json in release - skipping dependency install"
+		return 0
+	fi
+
+	local deps="$APP/deps/$key"
+	if [ ! -d "$deps/node_modules" ]; then
+		log "installing dependencies ($key)"
+		rm -rf "$deps"
+		mkdir -p "$deps"
+		cp "$RELEASE_DIR/package.json" "$deps/"
+		if [ -f "$lock" ]; then cp "$lock" "$deps/"; fi
+		if [ -f "$RELEASE_DIR/.npmrc" ]; then cp "$RELEASE_DIR/.npmrc" "$deps/"; fi
+		chown -R "$VELA_USER:$VELA_USER" "$deps"
+		# npm needs a writable HOME and cache; $VELA_ROOT itself stays root-owned
+		# so the app user can never swap out the scripts root runs.
+		mkdir -p "$VELA_ROOT/cache/npm"
+		chown -R "$VELA_USER:$VELA_USER" "$VELA_ROOT/cache"
+		( cd "$deps" && runuser -u "$VELA_USER" -- env \
+			HOME="$deps" npm_config_cache="$VELA_ROOT/cache/npm" \
+			"${install_cmd[@]}" >&2 ) || die "dependency install failed"
+	else
+		log "dependencies already installed ($key)"
+	fi
+	ln -sfn "$deps/node_modules" "$RELEASE_DIR/.node_modules.tmp"
+	mv -Tf "$RELEASE_DIR/.node_modules.tmp" "$RELEASE_DIR/node_modules"
+	printf '%s' "$key" > "$RELEASE_DIR/.vela-deps"
+}
+install_deps
+
+# --------------------------------------------------------------- the swap
+
+PREVIOUS=""
+if [ -L "$APP/current" ]; then
+	PREVIOUS=$(basename "$(readlink -f "$APP/current")")
+fi
+
+# From here on the instance is being mutated. Any exit before ACTIVATED=1 puts
+# the previous release back - a failed deploy must never leave a dead service.
+IN_TRANSACTION=0
+ACTIVATED=0
+
+restore() {
+	log "deploy failed - restoring ${PREVIOUS:-nothing}"
+	if [ -n "$PREVIOUS" ] && [ -d "$APP/releases/$PREVIOUS" ]; then
+		ln -sfn "$APP/releases/$PREVIOUS" "$APP/.current.tmp"
+		mv -Tf "$APP/.current.tmp" "$APP/current"
+		if [ "$BACKEND" = "1" ]; then systemctl restart "$PB_UNIT" >/dev/null 2>&1 || true; fi
+		systemctl restart "$WEB_UNIT" >/dev/null 2>&1 || true
+	else
+		systemctl stop "$WEB_UNIT" >/dev/null 2>&1 || true
+		if [ "$BACKEND" = "1" ]; then systemctl stop "$PB_UNIT" >/dev/null 2>&1 || true; fi
+	fi
+}
+
+on_exit() {
+	local code=$?
+	if [ "$IN_TRANSACTION" = "1" ] && [ "$ACTIVATED" = "0" ]; then restore; fi
+	exit "$code"
+}
+trap on_exit EXIT
+
+IN_TRANSACTION=1
+
+log "stopping services"
+systemctl stop "$WEB_UNIT" >/dev/null 2>&1 || true
+if [ "$BACKEND" = "1" ]; then
+	systemctl stop "$PB_UNIT" >/dev/null 2>&1 || true
+
+	if [ -d "$RELEASE_DIR/migrations" ]; then
+		log "running migrations"
+		runuser -u "$VELA_USER" -- "$APP/bin/pocketbase" \
+			--dir "$APP/shared/pb_data" \
+			--migrationsDir "$RELEASE_DIR/migrations" \
+			migrate up >&2
+	fi
+
+	# ---------------------------------------------------- superuser bootstrap
+	#
+	# The app authenticates to its own PocketBase as a superuser on every render,
+	# so a database without one answers every request with a 401 and the deploy
+	# fails its health check. A brand new instance has an empty pb_data, which is
+	# why the account is created here rather than assumed to exist.
+	#
+	# $ETC/env is otherwise `vela env`'s alone. This is the single exception, and
+	# it writes only on the deploy that creates the account. From then on the env
+	# file is the source of truth: a value changed there is pushed into the
+	# database by the next deploy, which is what keeps the two from drifting.
+	SU_EMAIL=$(env_file_get "$ETC/env" POCKETBASE_SUPERUSER_EMAIL || true)
+	SU_PASSWORD=$(env_file_get "$ETC/env" POCKETBASE_SUPERUSER_PASSWORD || true)
+
+	if [ -z "$SU_EMAIL" ] || [ -z "$SU_PASSWORD" ]; then
+		SU_EMAIL=${SU_EMAIL:-admin@${PRIMARY_DOMAIN:-$INSTANCE.invalid}}
+		SU_PASSWORD=$(random_secret)
+		SU_CREATED=1
+	fi
+
+	# The password reaches PocketBase as an argument, so the upsert runs only on
+	# the deploys that need it rather than on every one.
+	SU_STAMP="$ETC/.superuser"
+	SU_FINGERPRINT=$(printf '%s\n%s' "$SU_EMAIL" "$SU_PASSWORD" | sha256sum | cut -d' ' -f1)
+	if [ "$SU_CREATED" = "1" ] || [ "$(cat "$SU_STAMP" 2>/dev/null || true)" != "$SU_FINGERPRINT" ]; then
+		if [ "$SU_CREATED" = "1" ]; then
+			log "creating the PocketBase superuser"
+		else
+			log "updating the PocketBase superuser"
+		fi
+		runuser -u "$VELA_USER" -- "$APP/bin/pocketbase" \
+			--dir "$APP/shared/pb_data" \
+			superuser upsert "$SU_EMAIL" "$SU_PASSWORD" >&2 \
+			|| die "could not create the PocketBase superuser"
+
+		# Recorded only once the database holds the account, so a failure above
+		# leaves nothing behind and the next deploy simply tries again.
+		if [ "$SU_CREATED" = "1" ]; then
+			env_file_append "$ETC/env" POCKETBASE_SUPERUSER_EMAIL "$SU_EMAIL"
+			env_file_append "$ETC/env" POCKETBASE_SUPERUSER_PASSWORD "$SU_PASSWORD"
+		fi
+		printf '%s\n' "$SU_FINGERPRINT" > "$SU_STAMP"
+		chmod 0600 "$SU_STAMP"
+		chown root:root "$SU_STAMP"
+	fi
+fi
+
+log "activating release $RELEASE"
+ln -sfn "$RELEASE_DIR" "$APP/.current.tmp"
+mv -Tf "$APP/.current.tmp" "$APP/current"
+# A human-readable alias for the opaque app id, purely for looking around.
+if [ "$ENV_TAG" = "prod" ]; then LINK_LABEL=$APP_NAME; else LINK_LABEL="$APP_NAME-$ENV_TAG"; fi
+LINK_NAME=$(printf '%s' "$LINK_LABEL" | tr -c 'A-Za-z0-9._-' '-')
+if [ -n "$LINK_NAME" ]; then
+	ln -sfn "$APP" "$VELA_ROOT/by-name/.link.tmp" && \
+		mv -Tf "$VELA_ROOT/by-name/.link.tmp" "$VELA_ROOT/by-name/$LINK_NAME" || true
+fi
+
+systemctl daemon-reload
+
+if [ "$BACKEND" = "1" ]; then
+	log "starting PocketBase on 127.0.0.1:$PB_PORT"
+	systemctl enable "$PB_UNIT" >/dev/null 2>&1 || true
+	systemctl restart "$PB_UNIT"
+	wait_for_http "http://127.0.0.1:$PB_PORT/api/health" 60 0.5 \
+		|| die "PocketBase did not become healthy - journalctl -u $PB_UNIT"
+fi
+
+log "starting app on 127.0.0.1:$WEB_PORT"
+systemctl enable "$WEB_UNIT" >/dev/null 2>&1 || true
+systemctl restart "$WEB_UNIT"
+wait_for_http "http://127.0.0.1:$WEB_PORT$HEALTH_PATH" 60 0.5 \
+	|| die "app did not become healthy at $HEALTH_PATH - journalctl -u $WEB_UNIT"
+
+ACTIVATED=1
+
+# --------------------------------------------------------------------- state
+
+state_merge "$INSTANCE" "$(jq -c -n \
+	--arg app "$APP_ID" --arg name "$APP_NAME" --arg env "$ENV_TAG" \
+	--arg instance "$INSTANCE" --arg release "$RELEASE" --arg previous "$PREVIOUS" \
+	--arg domain "$DOMAIN" --arg health "$HEALTH_PATH" --arg pb "$PB_VERSION" \
+	--arg sha "$GIT_SHA" --arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+	--argjson web "$WEB_PORT" --argjson pbport "$PB_PORT" --argjson backend "$BACKEND" \
+	'{appId: $app, name: $name, env: $env, instance: $instance,
+	  activeRelease: $release, previousRelease: $previous, domain: $domain,
+	  healthCheckPath: $health, pocketbaseVersion: $pb, gitSha: $sha,
+	  webPort: $web, pbPort: $pbport, backend: ($backend == 1), deployedAt: $at}')"
+
+# ------------------------------------------------------------------ routing
+
+CADDY_SNIPPET="$VELA_ETC/caddy/$INSTANCE.caddy"
+if [ -n "$DOMAIN" ]; then
+	hosts=$(printf '%s' "$DOMAIN" | tr ',' '\n' | sed 's/^ *//; s/ *$//' | grep -v '^$' | paste -sd, - | sed 's/,/, /g')
+	tmp=$(mktemp "$VELA_ETC/caddy/.snippet.XXXXXX")
+	{
+		printf '# Managed by vela - app %s (%s)\n' "$APP_NAME" "$INSTANCE"
+		printf '%s {\n\treverse_proxy 127.0.0.1:%s\n}\n' "$hosts" "$WEB_PORT"
+	} > "$tmp"
+	chmod 0644 "$tmp"
+	mv -f "$tmp" "$CADDY_SNIPPET"
+	if ! caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile >/dev/null 2>&1; then
+		rm -f "$CADDY_SNIPPET"
+		die "generated Caddy config for $DOMAIN is invalid"
+	fi
+	systemctl reload caddy
+elif [ -f "$CADDY_SNIPPET" ]; then
+	rm -f "$CADDY_SNIPPET"
+	systemctl reload caddy || true
+fi
+
+
+# ------------------------------------------------------------------- pruning
+
+if [ "$KEEP" -gt 0 ] 2>/dev/null; then
+	mapfile -t old < <(ls -1 "$APP/releases" | sort -r | tail -n +$((KEEP + 1)))
+	for rel in "${old[@]:-}"; do
+		[ -n "$rel" ] || continue
+		[ "$rel" = "$RELEASE" ] && continue
+		[ "$rel" = "$PREVIOUS" ] && continue
+		log "pruning release $rel"
+		rm -rf "${APP:?}/releases/$rel"
+	done
+	# Drop dependency trees no surviving release refers to.
+	for deps in "$APP"/deps/*; do
+		[ -d "$deps" ] || continue
+		key=$(basename "$deps")
+		if ! grep -rqs -- "$key" "$APP"/releases/*/.vela-deps; then
+			log "pruning dependencies $key"
+			rm -rf "$deps"
+		fi
+	done
+fi
+
+emit_result \
+	--arg instance "$INSTANCE" --arg release "$RELEASE" --arg domain "$DOMAIN" \
+	--arg url "$ORIGIN" --argjson web "$WEB_PORT" --argjson pb "$PB_PORT" --argjson su "$SU_CREATED" \
+	'{instance: $instance, release: $release, domain: $domain, url: $url,
+	  webPort: $web, pbPort: $pb, superuserCreated: ($su == 1)}'

package/templates/server/destroy.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+#
+# Remove one instance from the server.
+#
+# Releases and configuration always go; the database and uploads only go with
+# --purge, so a mistyped instance name cannot silently delete production data.
+#
+# usage: destroy.sh <instance> [--purge]
+set -Eeuo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=lib.sh
+. "$SCRIPT_DIR/lib.sh"
+
+require_provisioned
+[ "$(id -u)" -eq 0 ] || die "destroy must run as root"
+
+INSTANCE=${1:-}; shift || true
+[ -n "$INSTANCE" ] || die "usage: destroy.sh <instance> [--purge]"
+PURGE=0
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--purge) PURGE=1; shift ;;
+		*) die "unknown argument: $1" ;;
+	esac
+done
+
+APP=$(app_dir "$INSTANCE")
+ETC=$(etc_dir "$INSTANCE")
+
+log "stopping services"
+for unit in "$(unit_web "$INSTANCE")" "$(unit_pb "$INSTANCE")"; do
+	systemctl disable --now "$unit" >/dev/null 2>&1 || true
+done
+
+log "removing routing"
+rm -f "$VELA_ETC/caddy/$INSTANCE.caddy"
+systemctl reload caddy >/dev/null 2>&1 || true
+
+log "removing releases"
+rm -rf "$APP/releases" "$APP/deps" "$APP/current" "$APP/bin"
+
+if [ "$PURGE" = "1" ]; then
+	log "purging data and configuration"
+	rm -rf "$APP" "$ETC"
+	release_ports "$INSTANCE"
+else
+	log "keeping $APP/shared (pass --purge to remove the database)"
+	rm -f "$APP/state.json"
+fi
+
+find "$VELA_ROOT/by-name" -maxdepth 1 -type l ! -exec test -e {} \; -delete 2>/dev/null || true
+
+emit_result --arg instance "$INSTANCE" --argjson purged "$PURGE" \
+	'{instance: $instance, purged: ($purged == 1)}'

package/templates/server/lib.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# Shared helpers for the vela server scripts. Sourced, never run directly.
+
+VELA_ROOT=${VELA_ROOT:-/var/lib/vela}
+VELA_ETC=${VELA_ETC:-/etc/vela}
+VELA_USER=${VELA_USER:-vela}
+VELA_WEB_PORT_BASE=${VELA_WEB_PORT_BASE:-4100}
+VELA_PB_PORT_BASE=${VELA_PB_PORT_BASE:-8100}
+VELA_PORT_RANGE=${VELA_PORT_RANGE:-900}
+
+app_dir() { printf '%s/apps/%s' "$VELA_ROOT" "$1"; }
+etc_dir() { printf '%s/apps/%s' "$VELA_ETC" "$1"; }
+state_file() { printf '%s/apps/%s/state.json' "$VELA_ROOT" "$1"; }
+
+log() { printf '  %s\n' "$*" >&2; }
+die() { printf 'error: %s\n' "$*" >&2; exit 1; }
+
+require_provisioned() {
+	[ -f "$VELA_ETC/provisioned" ] || die "server is not provisioned - run 'vela provision' first"
+}
+
+# Read a top-level key out of an instance's state file.
+state_get() {
+	local instance=$1 key=$2 file
+	file=$(state_file "$instance")
+	[ -f "$file" ] || return 1
+	# `// empty` would swallow a legitimate `false`, so test for the key itself.
+	jq -er --arg k "$key" 'if has($k) and .[$k] != null then .[$k] else empty end' "$file" 2>/dev/null
+}
+
+# Merge a JSON object into an instance's state file, atomically.
+state_merge() {
+	local instance=$1 patch=$2 file tmp
+	file=$(state_file "$instance")
+	mkdir -p "$(dirname "$file")"
+	[ -f "$file" ] || echo '{}' > "$file"
+	tmp=$(mktemp "$(dirname "$file")/.state.XXXXXX")
+	jq -S --argjson patch "$patch" '. * $patch' "$file" > "$tmp"
+	chown "$VELA_USER:$VELA_USER" "$tmp" 2>/dev/null || true
+	mv -f "$tmp" "$file"
+}
+
+# Assign a web/PocketBase port pair to an instance, or echo the existing one.
+# Ports live in one server-wide file guarded by flock so that concurrent
+# deploys of different apps cannot land on the same port.
+allocate_ports() {
+	local instance=$1
+	local ports_file="$VELA_ROOT/state/ports.json"
+	local lock="$VELA_ROOT/state/.ports.lock"
+	mkdir -p "$VELA_ROOT/state"
+	[ -f "$ports_file" ] || echo '{}' > "$ports_file"
+	touch "$lock"
+
+	(
+		flock 9
+		local existing
+		existing=$(jq -er --arg i "$instance" '.[$i] // empty' "$ports_file")
+		if [ -n "$existing" ]; then
+			printf '%s' "$existing"
+			exit 0
+		fi
+
+		local offset=0 web pb
+		while [ "$offset" -lt "$VELA_PORT_RANGE" ]; do
+			web=$((VELA_WEB_PORT_BASE + offset))
+			pb=$((VELA_PB_PORT_BASE + offset))
+			if ! jq -e --argjson w "$web" 'to_entries | any(.value.web == $w)' "$ports_file" >/dev/null \
+				&& ! port_in_use "$web" && ! port_in_use "$pb"; then
+				local tmp
+				tmp=$(mktemp "$VELA_ROOT/state/.ports.XXXXXX")
+				jq -S --arg i "$instance" --argjson w "$web" --argjson p "$pb" \
+					'.[$i] = {web: $w, pb: $p}' "$ports_file" > "$tmp"
+				mv -f "$tmp" "$ports_file"
+				jq -c -n --argjson w "$web" --argjson p "$pb" '{web: $w, pb: $p}'
+				exit 0
+			fi
+			offset=$((offset + 1))
+		done
+		die "no free port pair in range"
+	) 9>"$lock"
+}
+
+release_ports() {
+	local instance=$1
+	local ports_file="$VELA_ROOT/state/ports.json"
+	local lock="$VELA_ROOT/state/.ports.lock"
+	[ -f "$ports_file" ] || return 0
+	(
+		flock 9
+		local tmp
+		tmp=$(mktemp "$VELA_ROOT/state/.ports.XXXXXX")
+		jq -S --arg i "$instance" 'del(.[$i])' "$ports_file" > "$tmp"
+		mv -f "$tmp" "$ports_file"
+	) 9>"$lock"
+}
+
+port_in_use() {
+	local port=$1
+	if command -v ss >/dev/null 2>&1; then
+		ss -ltn "sport = :$port" 2>/dev/null | tail -n +2 | grep -q . && return 0
+	fi
+	return 1
+}
+
+unit_web() { printf 'vela-web@%s.service' "$1"; }
+unit_pb() { printf 'vela-pb@%s.service' "$1"; }
+
+unit_active() { systemctl is-active --quiet "$1"; }
+
+# Poll an HTTP endpoint until it answers with a non-5xx status.
+wait_for_http() {
+	local url=$1 attempts=${2:-60} delay=${3:-0.5} code
+	local i=0
+	while [ "$i" -lt "$attempts" ]; do
+		code=$(curl -fsS -o /dev/null -w '%{http_code}' --max-time 5 "$url" 2>/dev/null || echo 000)
+		case "$code" in
+			2*|3*|4*) return 0 ;;
+		esac
+		i=$((i + 1))
+		sleep "$delay"
+	done
+	return 1
+}
+
+# How many migrations the current release has that the target release does not.
+# PocketBase reverts by count, so this is what `migrate down` needs.
+migrations_ahead() {
+	local current_dir=$1 target_dir=$2 count=0 f
+	[ -d "$current_dir" ] || { printf '0'; return 0; }
+	for f in "$current_dir"/*.js; do
+		[ -f "$f" ] || continue
+		if [ ! -f "$target_dir/$(basename "$f")" ]; then count=$((count + 1)); fi
+	done
+	printf '%s' "$count"
+}
+
+emit_result() { printf 'VELA_RESULT %s\n' "$(jq -c -n "$@")"; }
+
+# Read one value out of a vela-managed env file. `vela env` writes values with
+# systemd's quoting, whose escapes (\\, \", \n, \t) are also JSON's, so jq
+# decodes them exactly.
+env_file_get() {
+	local file=$1 key=$2 raw
+	[ -f "$file" ] || return 1
+	raw=$(sed -n "s/^[[:space:]]*${key}=//p" "$file" | head -n1)
+	[ -n "$raw" ] || return 1
+	case "$raw" in
+		'"'*) printf '%s' "$raw" | jq -r . ;;
+		*) printf '%s' "$raw" ;;
+	esac
+}
+
+# Append a value in the same quoted form `vela env` uses, so it round-trips.
+env_file_append() {
+	local file=$1 key=$2 value=$3
+	[ -f "$file" ] || : > "$file"
+	if [ -s "$file" ] && [ -n "$(tail -c1 "$file")" ]; then printf '\n' >> "$file"; fi
+	printf '%s=%s\n' "$key" "$(jq -rn --arg v "$value" '$v | @json')" >> "$file"
+	chmod 0600 "$file"
+	chown root:root "$file"
+}
+
+# 24 bytes of hex - no shell metacharacters, nothing to escape anywhere it goes.
+random_secret() {
+	head -c 24 /dev/urandom | od -An -tx1 | tr -d ' \n'
+}

package/templates/server/pocketbase.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Ensure a given PocketBase version is available on this server and print its
+# path. Versions live side by side so two apps can pin different ones and a
+# rollback never has to downgrade a shared binary.
+#
+# usage: pocketbase.sh <version>
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=lib.sh
+. "$SCRIPT_DIR/lib.sh"
+
+VERSION=${1:-}
+[ -n "$VERSION" ] || die "pocketbase.sh needs a version"
+
+DEST="$VELA_ROOT/runtime/pocketbase/$VERSION"
+BIN="$DEST/pocketbase"
+
+if [ -x "$BIN" ]; then
+	printf '%s\n' "$BIN"
+	exit 0
+fi
+
+case "$(uname -m)" in
+	x86_64) NPM_PKG=pocketbase-server-linux-x64 ;;
+	aarch64|arm64) NPM_PKG=pocketbase-server-linux-arm64 ;;
+	*) die "unsupported architecture: $(uname -m)" ;;
+esac
+
+# The same npm package the CLI runs locally, so the server and a developer's
+# machine are always on the identical PocketBase build.
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+(
+	cd "$tmp"
+	npm init -y >/dev/null 2>&1
+	npm install --no-audit --no-fund --loglevel=error "$NPM_PKG@$VERSION" >/dev/null
+)
+[ -f "$tmp/node_modules/$NPM_PKG/bin/pocketbase" ] \
+	|| die "PocketBase $VERSION could not be installed from $NPM_PKG"
+
+mkdir -p "$DEST"
+install -m 0755 "$tmp/node_modules/$NPM_PKG/bin/pocketbase" "$BIN"
+printf '%s\n' "$BIN"