vela 0.11.3 → 0.11.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vela",
-	"version": "0.11.3",
+	"version": "0.11.5",
 	"type": "module",
 	"description": "A CLI for creating and updating SvelteKit projects",
 	"license": "MIT",
@@ -24,17 +24,19 @@
 		"build": "node --experimental-strip-types scripts/build.ts",
 		"dev": "node --experimental-strip-types scripts/build.ts --watch",
 		"clean": "rm -rf dist",
-		"lint": "npm run lint:ts && npm run lint:format",
+		"lint": "npm run lint:ts && npm run lint:format && npm run lint:sh",
 		"lint:ts": "tsc --noEmit",
 		"lint:format": "prettier --check .",
 		"format": "prettier --write .",
 		"test": "vitest run",
-		"prepare": "npm run build"
+		"prepare": "npm run build",
+		"lint:sh": "shellcheck -x -P SCRIPTDIR -S warning templates/server/*.sh",
+		"test:scripts": "bash scripts/test-server-scripts.sh"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.7.0",
 		"@faker-js/faker": "^10.6.0",
-		"@velastack/patterns": "^0.2.3",
+		"@velastack/patterns": "^0.2.4",
 		"@velastack/pocketbase-codegen": "^0.1.0",
 		"annotate-json-schema": "^0.1.0",
 		"commander": "^13.1.0",
@@ -60,6 +62,7 @@
 		"@types/node": "^22.0.0",
 		"esbuild": "^0.28.2",
 		"prettier": "^3.9.6",
+		"shellcheck": "^4.1.0",
 		"typescript": "^5.6.0",
 		"vite": "^8.2.2",
 		"vitest": "^4.1.11"
@@ -76,6 +79,18 @@
 			"optional": true
 		}
 	},
+	"overrides": {
+		"global-agent": "^4.1.3",
+		"@xhmikosr/decompress-unzip": {
+			"file-type": "^21.3.1"
+		},
+		"@xhmikosr/decompress-tar": {
+			"file-type": "^21.3.1"
+		},
+		"@felipecrs/decompress-tarxz": {
+			"file-type": "^21.3.1"
+		}
+	},
 	"keywords": [
 		"svelte",
 		"sveltekit",

package/templates/minimal/package.template.json

@@ -16,7 +16,7 @@
 	},
 	"devDependencies": {
 		"@lucide/svelte": "^1.40.0",
-		"@sveltejs/adapter-auto": "^7.0.1",
+		"@sveltejs/adapter-node": "^5.5.7",
 		"@sveltejs/kit": "^2.70.3",
 		"@sveltejs/vite-plugin-svelte": "^7.3.0",
 		"@tailwindcss/forms": "^0.5.11",

package/templates/minimal/vite.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'vite';
 import tailwindcss from '@tailwindcss/vite';
 import { sveltekit } from '@sveltejs/kit/vite';
-import adapter from '@sveltejs/adapter-auto';
+import adapter from '@sveltejs/adapter-node';
 
 export default defineConfig({
 	plugins: [

package/templates/minimal/vitest.config.ts

@@ -5,6 +5,9 @@ export default mergeConfig(
 	viteConfig,
 	defineConfig({
 		test: {
+			expect: {
+				requireAssertions: true
+			},
 			name: 'server',
 			environment: 'node',
 			include: ['src/**/*.{test,spec}.{js,ts}'],

package/templates/server/apply.sh

@@ -7,6 +7,11 @@
 # is put back and the services are restarted before exiting non-zero.
 #
 # usage: apply.sh <instance> <release> [options]
+#
+# Only one of apply, destroy, rollback and restore runs for an instance at a
+# time; a second waits for the first (--lock-wait seconds) and then gives up. A
+# release that arrives after a newer one has gone live is refused rather than
+# put live over it.
 set -Eeuo pipefail
 
 SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
@@ -19,6 +24,8 @@ require_provisioned
 INSTANCE=${1:-}; shift || true
 RELEASE=${1:-}; shift || true
 [ -n "$INSTANCE" ] && [ -n "$RELEASE" ] || die "usage: apply.sh <instance> <release> [options]"
+require_instance_id "$INSTANCE"
+require_release_id "$RELEASE"
 
 APP_NAME=$INSTANCE
 APP_ID=$INSTANCE
@@ -30,10 +37,13 @@ KEEP=5
 PB_VERSION=""
 BACKEND=1
 GIT_SHA=""
+LOCK_WAIT=300
 SU_CREATED=0
+MIGRATED=0
 
 while [ $# -gt 0 ]; do
 	case "$1" in
+		--lock-wait) LOCK_WAIT=$2; shift 2 ;;
 		--name) APP_NAME=$2; shift 2 ;;
 		--app-id) APP_ID=$2; shift 2 ;;
 		--env) ENV_TAG=$2; shift 2 ;;
@@ -58,32 +68,84 @@ RELEASE_DIR="$APP/releases/$RELEASE"
 WEB_UNIT=$(unit_web "$INSTANCE")
 PB_UNIT=$(unit_pb "$INSTANCE")
 
+lock_instance "$INSTANCE" "$LOCK_WAIT"
+
 [ -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"
+# A release that sorts at or below the active one arrived late: a newer deploy
+# went live while this one was building or waiting for the lock. Putting it
+# live would take the site backwards, so it is dropped - its own directory
+# only; what is live is not touched.
+ACTIVE=$(state_get "$INSTANCE" activeRelease 2>/dev/null || true)
+if [ -n "$ACTIVE" ] && [ -L "$APP/current" ] && ! [[ "$RELEASE" > "$ACTIVE" ]]; then
+	rm -rf "${RELEASE_DIR:?}"
+	die "release $RELEASE is not newer than the active release $ACTIVE on $INSTANCE - a newer deploy went live first, so this one was dropped"
+fi
+
+# Whether the release this one replaces had a PocketBase backend. The CLI
+# detects the backend from the project on every deploy, so an instance can gain
+# one (`vela bless` between two deploys) or lose one; both are handled below.
+# Empty on a first deploy.
+PREVIOUS_BACKEND=""
+if [ -f "$(state_file "$INSTANCE")" ]; then
+	PREVIOUS_BACKEND=$(instance_backend "$INSTANCE")
+fi
+
+# Where this app keeps state that has to outlive a release.
+#
+# An app that works this out from its own working directory puts it inside the
+# release, which is the one place it cannot survive: `current` moves on the next
+# deploy and the pruner deletes what it left behind. An instance with a database
+# shares PocketBase's directory, so anything the app writes there is inside the
+# archives `vela backup` takes and inside the directory `vela restore` swaps. An
+# instance without one gets a directory of its own, which nothing backs up -
+# there is no database to back it up alongside.
+if [ "$BACKEND" = "1" ]; then
+	APP_DATA_DIR="$APP/shared/pb_data"
+else
+	APP_DATA_DIR="$APP/shared/data"
+fi
+
+mkdir -p "$APP"/{releases,shared,bin,deps} "$APP_DATA_DIR"
 mkdir -p "$ETC"
 chmod 0700 "$ETC"
 
 # Only the directories just created need their ownership set, and only at the
-# top level: everything below pb_data is written by PocketBase as $VELA_USER
-# already. Recursing here would walk every uploaded file on every deploy, which
-# makes deploy time grow with the size of the app's storage forever.
+# top level: everything below the data directory is written by PocketBase (or
+# the app) as $VELA_USER already. Recursing here would walk every uploaded file
+# on every deploy, which makes deploy time grow with the size of the app's
+# storage forever.
 chown "$VELA_USER:$VELA_USER" \
-	"$APP" "$APP/releases" "$APP/shared" "$APP/shared/pb_data" "$APP/bin" "$APP/deps"
+	"$APP" "$APP/releases" "$APP/shared" "$APP_DATA_DIR" "$APP/bin" "$APP/deps"
 # The release is the exception - rsync uploaded it as whoever we ssh'd in as.
 chown -R "$VELA_USER:$VELA_USER" "$RELEASE_DIR"
 
-# A pb_data the app cannot write is a dead instance, and it fails as an opaque
-# 500 rather than anything that names a cause. This is what the blanket recurse
-# above used to paper over; checking costs one stat, repairing costs a walk that
-# now happens only when something is actually wrong.
-if ! runuser -u "$VELA_USER" -- test -w "$APP/shared/pb_data"; then
+# A data directory the app cannot write is a dead instance, and it fails as an
+# opaque 500 rather than anything that names a cause. This is what the blanket
+# recurse above used to paper over; checking costs one stat, repairing costs a
+# walk that now happens only when something is actually wrong.
+if ! runuser -u "$VELA_USER" -- test -w "$APP_DATA_DIR"; then
 	log "repairing ownership under shared/"
 	chown -R "$VELA_USER:$VELA_USER" "$APP/shared"
 fi
 
+# An instance gaining a backend moves its data directory: VELA_DATA_DIR was
+# shared/data and is now shared/pb_data, which is what `vela backup` archives.
+# Whatever the app kept follows it, into a pb_data that PocketBase has not yet
+# written - once there is a database in there, nothing is moved over it.
+if [ "$PREVIOUS_BACKEND" = "false" ] && [ "$BACKEND" = "1" ] \
+	&& [ -d "$APP/shared/data" ] && [ -n "$(ls -A "$APP/shared/data")" ]; then
+	if [ ! -e "$APP/shared/pb_data/data.db" ]; then
+		log "adding a backend - moving shared/data into shared/pb_data"
+		find "$APP/shared/data" -mindepth 1 -maxdepth 1 -exec mv -t "$APP/shared/pb_data" {} +
+	else
+		log "warning: this instance now has a backend, and its data directory is $APP/shared/pb_data"
+		log "warning: what the app kept in $APP/shared/data was left there"
+	fi
+fi
+
 # ---------------------------------------------------------------- ports & env
 
 PORTS=$(allocate_ports "$INSTANCE")
@@ -104,23 +166,6 @@ fi
 # Nothing here reads or rewrites that file.
 [ -f "$ETC/env" ] || { : > "$ETC/env"; chmod 0600 "$ETC/env"; chown root:root "$ETC/env"; }
 
-# Where this app keeps state that has to outlive a release.
-#
-# An app that works this out from its own working directory puts it inside the
-# release, which is the one place it cannot survive: `current` moves on the next
-# deploy and the pruner deletes what it left behind. An instance with a database
-# shares PocketBase's directory, so anything the app writes there is inside the
-# archives `vela backup` takes and inside the directory `vela restore` swaps. An
-# instance without one gets a directory of its own, which nothing backs up -
-# there is no database to back it up alongside.
-if [ "$BACKEND" = "1" ]; then
-	APP_DATA_DIR="$APP/shared/pb_data"
-else
-	APP_DATA_DIR="$APP/shared/data"
-	mkdir -p "$APP_DATA_DIR"
-	chown "$VELA_USER:$VELA_USER" "$APP_DATA_DIR"
-fi
-
 runtime_tmp=$(mktemp "$ETC/.runtime.XXXXXX")
 {
 	printf '# Generated by vela on each deploy. Edit /etc/vela/apps/%s/env instead.\n' "$INSTANCE"
@@ -128,8 +173,14 @@ runtime_tmp=$(mktemp "$ETC/.runtime.XXXXXX")
 	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"
+	# Only an instance with a PocketBase gets pointed at one: a URL to a port
+	# nothing listens on is not a setting, it is a trap. Kept for one more
+	# deploy when the backend is being removed, so that a failed deploy can put
+	# the previous release - which still needs it - back.
+	if [ "$BACKEND" = "1" ] || [ "$PREVIOUS_BACKEND" = "true" ]; then
+		printf 'PB_PORT=%s\n' "$PB_PORT"
+		printf 'POCKETBASE_URL=http://127.0.0.1:%s\n' "$PB_PORT"
+	fi
 	printf 'VELA_DATA_DIR=%s\n' "$APP_DATA_DIR"
 	printf 'VELA_APP_ID=%s\n' "$APP_ID"
 	printf 'VELA_APP_NAME=%s\n' "$APP_NAME"
@@ -188,9 +239,11 @@ install_deps() {
 		# 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"
+		# 8>&-: npm must not inherit the instance lock, or a child it leaves
+		# behind would hold it after this script has exited.
 		( cd "$deps" && runuser -u "$VELA_USER" -- env \
 			HOME="$deps" npm_config_cache="$VELA_ROOT/cache/npm" \
-			"${install_cmd[@]}" >&2 ) || die "dependency install failed"
+			"${install_cmd[@]}" >&2 8>&- ) || die "dependency install failed"
 	else
 		log "dependencies already installed ($key)"
 	fi
@@ -214,10 +267,25 @@ ACTIVATED=0
 
 restore() {
 	log "deploy failed - restoring ${PREVIOUS:-nothing}"
+	# The schema moved with this release; the previous one must not run
+	# against it. Same steps `vela rollback` takes, best-effort here because
+	# the app is being put back either way and the alternative is a dead site.
+	if [ "$BACKEND" = "1" ] && [ "$MIGRATED" = "1" ] && [ -n "$PREVIOUS" ] \
+		&& [ -d "$APP/releases/$PREVIOUS" ]; then
+		systemctl stop "$PB_UNIT" >/dev/null 2>&1 || true
+		revert_migrations "$APP" "$RELEASE_DIR/migrations" "$APP/releases/$PREVIOUS/migrations" \
+			|| log "down migrations failed - the database schema is ahead of $PREVIOUS; run 'vela rollback' once it is fixed"
+	fi
 	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
+		# runtime.env was already written for the release that failed; the
+		# services about to restart must read the one they will actually run.
+		set_runtime_release "$ETC" "$PREVIOUS"
+		# The previous release needs its PocketBase whether or not this one did.
+		if [ "$BACKEND" = "1" ] || [ "$PREVIOUS_BACKEND" = "true" ]; 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
@@ -245,6 +313,7 @@ if [ "$BACKEND" = "1" ]; then
 			--dir "$APP/shared/pb_data" \
 			--migrationsDir "$RELEASE_DIR/migrations" \
 			migrate up >&2
+		MIGRATED=1
 	fi
 
 	# ---------------------------------------------------- superuser bootstrap
@@ -284,8 +353,11 @@ mv -Tf "$APP/.current.tmp" "$APP/current"
 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
+	# A staging name of its own: a fixed one would be shared with every other
+	# deploy on the server, and two of them would swap each other's links.
+	link_tmp=$(mktemp -u "$VELA_ROOT/by-name/.link.XXXXXX")
+	{ ln -sfn "$APP" "$link_tmp" && mv -Tf "$link_tmp" "$VELA_ROOT/by-name/$LINK_NAME"; } \
+		|| rm -f "$link_tmp" || true
 fi
 
 systemctl daemon-reload
@@ -325,6 +397,15 @@ wait_for_http "http://127.0.0.1:$WEB_PORT$HEALTH_PATH" 60 0.5 \
 
 ACTIVATED=1
 
+# An instance that no longer has a backend keeps its database on disk - only
+# `vela destroy deployment --purge` removes data - but the unit serving it is
+# retired, or `vela status` would keep reporting a PocketBase and every restart
+# would bring it back up.
+if [ "$PREVIOUS_BACKEND" = "true" ] && [ "$BACKEND" = "0" ]; then
+	log "removing the backend - stopping PocketBase; $APP/shared/pb_data is kept"
+	systemctl disable --now "$PB_UNIT" >/dev/null 2>&1 || true
+fi
+
 # --------------------------------------------------------------------- state
 
 state_merge "$INSTANCE" "$(jq -c -n \
@@ -352,6 +433,11 @@ CADDY_SNIPPET="$VELA_ETC/caddy/$INSTANCE.caddy"
 ROUTE_SNIPPET="$VELA_ETC/caddy/routes/$INSTANCE.route"
 ROUTING_CHANGED=0
 
+# From here the release is live and stays live: a routing failure below
+# exits non-zero with the site running the new release and its routes as
+# they were, which is what the messages say.
+caddy_lock
+
 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")
@@ -359,7 +445,8 @@ if [ -n "$DOMAIN" ]; then
 		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"
-	caddy_install "$tmp" "$CADDY_SNIPPET" || die "generated Caddy config for $DOMAIN is invalid"
+	caddy_install "$tmp" "$CADDY_SNIPPET" \
+		|| die "release $RELEASE is live, but the generated Caddy config for $DOMAIN is invalid and was not installed - routing is unchanged"
 	ROUTING_CHANGED=1
 elif [ -f "$CADDY_SNIPPET" ]; then
 	rm -f "$CADDY_SNIPPET"
@@ -386,7 +473,8 @@ if [ -n "$MANAGED" ]; then
 		printf '\t\theader_up X-Forwarded-For {http.request.header.X-Velastack-Client-IP}\n'
 		printf '\t}\n}\n'
 	} > "$tmp"
-	caddy_install "$tmp" "$ROUTE_SNIPPET" || die "generated Caddy route for $MANAGED is invalid"
+	caddy_install "$tmp" "$ROUTE_SNIPPET" \
+		|| die "release $RELEASE is live, but the generated Caddy route for $MANAGED is invalid and was not installed - routing is unchanged"
 	ROUTING_CHANGED=1
 elif [ -f "$ROUTE_SNIPPET" ]; then
 	rm -f "$ROUTE_SNIPPET"
@@ -394,7 +482,7 @@ elif [ -f "$ROUTE_SNIPPET" ]; then
 fi
 
 [ "$ROUTING_CHANGED" = 0 ] || caddy_reload
-
+caddy_unlock
 
 # ------------------------------------------------------------------- pruning
 
@@ -404,6 +492,8 @@ if [ "$KEEP" -gt 0 ] 2>/dev/null; then
 		[ -n "$rel" ] || continue
 		[ "$rel" = "$RELEASE" ] && continue
 		[ "$rel" = "$PREVIOUS" ] && continue
+		# Uploaded by a deploy that is waiting on the lock: not ours to prune.
+		if [[ "$rel" > "$RELEASE" ]]; then continue; fi
 		log "pruning release $rel"
 		rm -rf "${APP:?}/releases/$rel"
 	done

package/templates/server/destroy.sh

@@ -4,8 +4,9 @@
 #
 # Releases and configuration always go; the database and uploads only go with
 # --purge, so a mistyped instance name cannot silently delete production data.
+# A purge snapshots them into $VELA_ROOT/trash first, kept for two weeks.
 #
-# usage: destroy.sh <instance> [--purge]
+# usage: destroy.sh <instance> [--purge] [--lock-wait <seconds>]
 set -Eeuo pipefail
 
 SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
@@ -16,33 +17,75 @@ require_provisioned
 [ "$(id -u)" -eq 0 ] || die "destroy must run as root"
 
 INSTANCE=${1:-}; shift || true
-[ -n "$INSTANCE" ] || die "usage: destroy.sh <instance> [--purge]"
+[ -n "$INSTANCE" ] || die "usage: destroy.sh <instance> [--purge] [--lock-wait <seconds>]"
 PURGE=0
+LOCK_WAIT=300
 while [ $# -gt 0 ]; do
 	case "$1" in
 		--purge) PURGE=1; shift ;;
+		--lock-wait) LOCK_WAIT=$2; shift 2 ;;
 		*) die "unknown argument: $1" ;;
 	esac
 done
 
+require_instance_id "$INSTANCE"
+
 APP=$(app_dir "$INSTANCE")
 ETC=$(etc_dir "$INSTANCE")
 
+lock_instance "$INSTANCE" "$LOCK_WAIT"
+
+# Nothing to remove is a result, not an error: a preview that never deployed
+# still gets a cleanup run when its pull request closes. Nothing is touched,
+# so a mistyped name cannot do harm either way.
+EXISTS=0
+for path in "$APP/state.json" "$APP/releases" "$APP/current" "$ETC"; do
+	if [ -e "$path" ]; then EXISTS=1; fi
+done
+if [ "$PURGE" = 1 ] && [ -d "$APP" ]; then EXISTS=1; fi
+if [ "$EXISTS" = 0 ]; then
+	log "nothing named $INSTANCE on this server"
+	emit_result --arg instance "$INSTANCE" \
+		'{instance: $instance, purged: false, existed: false}'
+	exit 0
+fi
+
 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"
+caddy_lock
 rm -f "$VELA_ETC/caddy/$INSTANCE.caddy" "$VELA_ETC/caddy/routes/$INSTANCE.route"
 caddy_reload || true
+caddy_unlock
 
 log "removing releases"
-rm -rf "$APP/releases" "$APP/deps" "$APP/current" "$APP/bin"
+rm -rf "${APP:?}/releases" "${APP:?}/deps" "${APP:?}/current" "${APP:?}/bin"
 
+SNAPSHOT=""
 if [ "$PURGE" = "1" ]; then
+	# The services are stopped, so the database is quiet: this is the one copy
+	# of it that will exist once the purge runs. Root-only, pruned after two
+	# weeks, and taken before anything is removed - a snapshot that fails
+	# leaves the instance's data where it was.
+	TRASH="$VELA_ROOT/trash"
+	mkdir -p "$TRASH"
+	chmod 0700 "$TRASH"
+	find "$TRASH" -maxdepth 1 -name '*.tar.gz' -mtime +14 -delete 2>/dev/null || true
+	members=()
+	[ -d "$APP/shared" ] && members+=("${APP#/}/shared")
+	[ -d "$ETC" ] && members+=("${ETC#/}")
+	if [ "${#members[@]}" -gt 0 ]; then
+		SNAPSHOT="$TRASH/$INSTANCE-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
+		log "snapshotting data and configuration to $SNAPSHOT"
+		tar -C / -czf "$SNAPSHOT" "${members[@]}" \
+			|| die "could not snapshot $INSTANCE before purging - its data was left in place"
+		chmod 0600 "$SNAPSHOT"
+	fi
 	log "purging data and configuration"
-	rm -rf "$APP" "$ETC"
+	rm -rf "${APP:?}" "${ETC:?}"
 	release_ports "$INSTANCE"
 else
 	log "keeping $APP/shared (pass --purge to remove the database)"
@@ -51,5 +94,5 @@ 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)}'
+emit_result --arg instance "$INSTANCE" --argjson purged "$PURGE" --arg trash "$SNAPSHOT" \
+	'{instance: $instance, purged: ($purged == 1), existed: true, trash: $trash}'

package/templates/server/lib.sh

@@ -15,15 +15,63 @@ state_file() { printf '%s/apps/%s/state.json' "$VELA_ROOT" "$1"; }
 log() { printf '  %s\n' "$*" >&2; }
 die() { printf 'error: %s\n' "$*" >&2; exit 1; }
 
+# Release ids are compared as strings, in `sort` and in `[[ < ]]` alike, and
+# the two have to agree whatever locale the server booted with.
+export LC_ALL=C
+
+# An instance id is `<appId>` or `<appId>--<envTag>`: lowercase letters and
+# digits joined by single or double dashes, exactly what the CLI's instanceId()
+# produces. It arrives from the CLI, but it ends up in paths that root removes,
+# so its shape is checked here too before anything is touched.
+require_instance_id() {
+	[[ $1 =~ ^[a-z0-9]+(-{1,2}[a-z0-9]+)*$ ]] || die "not an instance id: $1"
+}
+
+# A release id is a UTC stamp with an optional short suffix: 20260910T141203Z
+# or 20260910T141203Z-a3f9.
+require_release_id() {
+	[[ $1 =~ ^[0-9]{8}T[0-9]{6}Z(-[a-z0-9]{1,8})?$ ]] || die "not a release id: $1"
+}
+
+# Hold the instance's lock for the rest of this process.
+#
+# Every script that mutates an instance - deploy, destroy, rollback, restore -
+# takes this first, so two of them can never interleave: the second waits for
+# the first, up to `wait` seconds, then gives up. The lock file lives under
+# state/ rather than in the instance's own directory, so a purge cannot unlink
+# a lock somebody else is holding. Descriptor 8; 9 belongs to the port table.
+#
+# usage: lock_instance <instance> [wait_seconds]
+lock_instance() {
+	local instance=$1 wait=${2:-300} dir="$VELA_ROOT/state/locks"
+	mkdir -p "$dir"
+	exec 8>"$dir/$instance.lock"
+	if flock -n 8; then return 0; fi
+	[ "$wait" -gt 0 ] 2>/dev/null \
+		|| die "another deploy, destroy, rollback or restore is running for $instance - aborting"
+	log "waiting for another operation on $instance to finish (up to ${wait}s)"
+	flock -w "$wait" 8 \
+		|| die "another deploy, destroy, rollback or restore is still running for $instance after ${wait}s - aborting"
+}
+
 require_provisioned() {
 	[ -f "$VELA_ETC/provisioned" ] || die "server is not provisioned - run 'vela provision' first"
 }
 
-# Refuse on a frontend-only instance. Absent state is treated as having one, so
-# this only ever fires on an instance that was deployed with --backend 0.
+# Whether an instance was last deployed with a PocketBase backend: `true` or
+# `false`. Absent state, or state from before the flag existed, is treated as
+# having one, so this only ever answers `false` for an instance that was
+# deployed with --backend 0.
+instance_backend() {
+	local instance=$1 value
+	value=$(state_get "$instance" backend 2>/dev/null || echo true)
+	[ "$value" = "false" ] && printf 'false' || printf 'true'
+}
+
+# Refuse on a frontend-only instance.
 require_backend() {
 	local instance=$1
-	[ "$(state_get "$instance" backend 2>/dev/null || echo true)" = "true" ] \
+	[ "$(instance_backend "$instance")" = "true" ] \
 		|| die "$instance has no database - there is nothing to back up or restore"
 }
 
@@ -32,8 +80,10 @@ 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
+	# Presence is checked on its own: `// empty` would swallow a legitimate
+	# `false`, and so would `-e` on the read, which exits non-zero for one.
+	jq -e --arg k "$key" 'has($k) and .[$k] != null' "$file" >/dev/null 2>&1 || return 1
+	jq -r --arg k "$key" '.[$k]' "$file" 2>/dev/null
 }
 
 # Merge a JSON object into an instance's state file, atomically.
@@ -115,14 +165,19 @@ 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.
+# Poll an HTTP endpoint until it answers like a running app.
+#
+# Success, a redirect, or a refusal that proves something is home (401, 403 -
+# a health path behind auth). A 404 is not that: it is what a wrong
+# --health-path or a route that never mounted looks like, and it used to pass.
+# No `-f`: curl has to report the status of an error response, not fail on it.
 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)
+		code=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 5 "$url" 2>/dev/null || echo 000)
 		case "$code" in
-			2*|3*|4*) return 0 ;;
+			2*|3*|401|403) return 0 ;;
 		esac
 		i=$((i + 1))
 		sleep "$delay"
@@ -142,6 +197,39 @@ migrations_ahead() {
 	printf '%s' "$count"
 }
 
+# Revert the migrations `from_dir` has that `to_dir` lacks. They run from
+# `from_dir` - the release that introduced them owns their down steps - and
+# PocketBase reverts by count, which `migrations_ahead` supplies. The
+# instance's PocketBase must be stopped: `migrate down` opens the database
+# directly. Returns non-zero if PocketBase refuses; the caller decides how bad
+# that is.
+#
+# usage: revert_migrations <app_dir> <from_dir> <to_dir>
+revert_migrations() {
+	local app=$1 from=$2 to=$3 ahead
+	ahead=$(migrations_ahead "$from" "$to")
+	[ "$ahead" -gt 0 ] || return 0
+	log "reverting $ahead migration(s) the previous release does not have"
+	runuser -u "$VELA_USER" -- "$app/bin/pocketbase" \
+		--dir "$app/shared/pb_data" \
+		--migrationsDir "$from" \
+		migrate down "$ahead" >&2
+}
+
+# Point an instance's runtime.env at a release. Rewritten whole and renamed
+# into place, the way apply.sh writes it, so systemd never reads half a line.
+#
+# usage: set_runtime_release <etc_dir> <release>
+set_runtime_release() {
+	local etc=$1 release=$2 tmp
+	[ -f "$etc/runtime.env" ] || return 0
+	tmp=$(mktemp "$etc/.runtime.XXXXXX")
+	sed "s|^VELA_RELEASE=.*|VELA_RELEASE=$release|" "$etc/runtime.env" > "$tmp"
+	chmod 0600 "$tmp"
+	chown root:root "$tmp" 2>/dev/null || true
+	mv -f "$tmp" "$etc/runtime.env"
+}
+
 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
@@ -216,7 +304,7 @@ reconcile_superuser() {
 
 # Prove the app's own credentials actually sign in to its database.
 #
-# `wait_for_http` accepts 4xx as healthy, so a PocketBase whose database no
+# `wait_for_http` accepts a 401 as healthy, so a PocketBase whose database no
 # longer matches `$ETC/env` sails through the health gate and then answers every
 # render with a 401. Only an actual login catches that. The password travels
 # through the environment rather than argv, so it never appears in `ps`.
@@ -266,3 +354,20 @@ caddy_install() {
 caddy_reload() {
 	systemctl reload caddy >/dev/null 2>&1 || systemctl restart caddy
 }
+
+# Serialize every change to the Caddy config across instances.
+#
+# `caddy_valid` checks the whole Caddyfile, so two scripts installing snippets
+# at once would each judge the other's: a bad snippet from one deploy would
+# have the other roll back a good route of its own. Held from the first
+# snippet write through the reload. Descriptor 7; blocking, since a Caddy
+# change takes well under a second.
+caddy_lock() {
+	mkdir -p "$VELA_ROOT/state"
+	exec 7>"$VELA_ROOT/state/.caddy.lock"
+	flock 7
+}
+
+caddy_unlock() {
+	exec 7>&-
+}

package/templates/server/origin.sh

@@ -51,6 +51,7 @@ if [ -f "$SNIPPET" ] && [ "$(cat "$SNIPPET")" = "$desired" ]; then
 	exit 0
 fi
 
+caddy_lock
 tmp=$(mktemp "$VELA_ETC/caddy/.origin.XXXXXX")
 printf '%s\n' "$desired" > "$tmp"
 # Readable by the caddy user (which is what `caddy reload` runs as) and no one
@@ -58,5 +59,6 @@ printf '%s\n' "$desired" > "$tmp"
 caddy_install "$tmp" "$SNIPPET" 0640 root:caddy \
 	|| die "generated origin config for $HOST is invalid"
 caddy_reload
+caddy_unlock
 
 emit_result --arg host "$HOST" '{originHost: $host, changed: true}'