#!/usr/bin/env bash # ══════════════════════════════════════════════════════════════════════ # Devolyn Guard — one-command installer for the self-hosted stack. # # From a checkout or an extracted release archive: # sudo ./deploy/install.sh # # From nothing (clones the release into /opt/nucleus-guard): # curl -fsSL https://raw.githubusercontent.com/nucleus-guard/nucleus_guard/main/deploy/install.sh | sudo bash # # What it does, in order, and every step is safe to run again: # # 1. Preflight root, OS/arch, the handful of tools the rest needs. # 2. Docker remove snap docker; install Engine + Compose if absent; # verify versions; start the daemon (systemd or not). # 3. Docker DNS a container that cannot resolve names cannot build. Detect, # write 8.8.8.8/1.1.1.1 into /etc/docker/daemon.json, restart. # 4. Source use the checkout we are in, or clone the release. # 5. Secrets every REQUIRED value in deploy/.env that is blank gets # generated. Existing values are never touched. Validated # with `docker compose config` before anything starts. # 6. Images pull the five prebuilt images from GHCR at the pinned # version. --build compiles them from source instead, for # an air-gapped host or one that cannot reach ghcr.io. # 7. Database postgres + redis up; the two least-privilege roles are # created or repaired if the init script did not run (a # bind mount without the execute bit, a CRLF checkout, a # volume that predates the script) -- idempotent. # 8. Stack everything up, and WAIT for every service to be healthy. # On failure: that service's logs and a specific hint. # 9. Verify /health/ready through nginx over TLS. # 10. Summary the URL, the admin login (printed ONCE, on the run that # generated it), where the secrets live, the next step. # # Flags: # --dir PATH where to clone/run from (default: /opt/nucleus-guard, # or the checkout this script lives in) # --ref TAG|BRANCH git ref to clone (default: $NUCLEUS_VERSION or main) # --domain HOST the URL to print and record (default: this host's IP) # --admin-email EMAIL dashboard admin identity (default: admin@) # --reset-admin-password generate a new admin password and print it once # --skip-docker-install fail rather than install Docker # --build build the images from source instead of pulling them # --no-build skip images entirely (re-run on a host that has them) # --refresh-from DIR refresh an existing install's bundle files from an already # unpacked, already verified bundle (used by `devolyn update`) # -y, --yes never prompt (also the default when stdin is not a TTY) # -h, --help # # Environment overrides: NUCLEUS_DIR, NUCLEUS_VERSION, NUCLEUS_REPO_URL. # ══════════════════════════════════════════════════════════════════════ set -Eeuo pipefail INSTALLER_VERSION="0.7.1" # The release this installer pulls. PINNED on purpose: `latest` is also published, # but a stranger running this today and someone running it next month must get the # same stack, or "works on mine" stops meaning anything. Must equal the VERSION file # and the compose tags -- tests/unit/test_release_images.py asserts all three. GUARD_VERSION="0.7.1" REPO_URL_DEFAULT="https://github.com/nucleus-guard/nucleus_guard.git" # Where `curl | bash` gets the deploy bundle when there is no checkout to run from. # Deliberately NOT a git clone: the product repository is private, and a stranger # installing Guard does not need its source -- only the compose file, this script, # the database role-init and an env template. Override with NUCLEUS_BUNDLE_URL. BUNDLE_URL="${NUCLEUS_BUNDLE_URL:-https://get.devolyn.com/devolyn-guard.tar.gz}" INSTALL_DIR_DEFAULT="/opt/nucleus-guard" MIN_DOCKER="24.0.0" MIN_COMPOSE="2.20.0" HEALTH_TIMEOUT="${NUCLEUS_HEALTH_TIMEOUT:-900}" # seconds; first build on a small box is slow # ── output ──────────────────────────────────────────────────────────── if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then C_BOLD=$'\e[1m'; C_DIM=$'\e[2m'; C_RED=$'\e[31m'; C_GRN=$'\e[32m'; C_YLW=$'\e[33m'; C_CYN=$'\e[36m'; C_RST=$'\e[0m' else C_BOLD=""; C_DIM=""; C_RED=""; C_GRN=""; C_YLW=""; C_CYN=""; C_RST="" fi STEP=0 T0=$(date +%s) step() { STEP=$((STEP + 1)); printf '\n%s==> [%d] %s%s %s(%ss)%s\n' "$C_BOLD$C_CYN" "$STEP" "$*" "$C_RST" "$C_DIM" "$(( $(date +%s) - T0 ))" "$C_RST"; } ok() { printf ' %s✔%s %s\n' "$C_GRN" "$C_RST" "$*"; } info() { printf ' %s·%s %s\n' "$C_DIM" "$C_RST" "$*"; } warn() { printf ' %s!%s %s\n' "$C_YLW" "$C_RST" "$*"; } fixed() { printf ' %s⚒ fixed%s %s\n' "$C_YLW" "$C_RST" "$*"; } die() { printf '\n%s✘ %s%s\n' "$C_RED$C_BOLD" "$*" "$C_RST" >&2; exit 1; } on_error() { local line=$1 caller=$2 local where="line ${line}" [[ "$caller" != 0 && "$caller" != "$line" ]] && where="line ${caller} (in a helper at line ${line})" printf '\n%s✘ install.sh failed at %s, step %s.%s\n' "$C_RED$C_BOLD" "$where" "$STEP" "$C_RST" >&2 printf ' Re-run the same command: every step is idempotent and picks up where this left off.\n' >&2 } trap 'on_error $LINENO ${BASH_LINENO[0]:-0}' ERR # ── args ────────────────────────────────────────────────────────────── INSTALL_DIR="${NUCLEUS_DIR:-}" REF="${NUCLEUS_VERSION:-main}" REPO_URL="${NUCLEUS_REPO_URL:-$REPO_URL_DEFAULT}" DOMAIN="" ADMIN_EMAIL="" RESET_ADMIN=0 SKIP_DOCKER_INSTALL=0 NO_BUILD=0 BUILD_FROM_SOURCE=0 # --hosted. 0 means "leave deploy/.env alone", NOT "single": an install that is already # hosted stays hosted when this flag is absent, because the mode lives in .env and only # an explicit `NUCLEUS_DEPLOYMENT_MODE=single` takes it back. An update must never # silently return a shared server to single-tenant behaviour. WANT_HOSTED=0 # An already-unpacked, already-verified bundle to refresh an existing install from. # `devolyn update` sets this; nothing else should need it. REFRESH_FROM="" ASSUME_YES=0 [[ -t 0 ]] || ASSUME_YES=1 # Printing the header block back is the nicest --help there is, but it only works when # there is a FILE to read. Piped into bash, `$0` is "bash": sed found no such file, the # 2>/dev/null swallowed the complaint, and `curl ... | bash -s -- --help` printed # absolutely nothing and exited 0. That is the first command a curious person tries, # and it answered with silence. # # So: the header when it is readable, an embedded summary when it is not. The embedded # list is kept honest by tests/unit/test_installer_pipe_safety.py, which asserts it # names every flag the parser below accepts -- a second copy of a flag list is only # safe if something fails when the two disagree. usage() { local src="${BASH_SOURCE[0]:-}" if [[ -n "$src" && -f "$src" ]]; then sed -n '2,50p' "$src" | sed 's/^# \{0,1\}//' else cat <<'USAGE' Devolyn Guard — one-command installer for the self-hosted stack. curl -fsSL https://get.devolyn.com | sudo bash -s -- [flags] It installs Docker if needed, fetches the deploy bundle and the prebuilt images, generates every secret into deploy/.env, creates the least-privilege database roles, brings the stack up and waits for it to be healthy. Flags: --dir PATH where to install (default: /opt/nucleus-guard) --ref TAG|BRANCH git ref to clone, with NUCLEUS_REPO_URL set --domain HOST the URL to print and record (default: this host's IP) --admin-email EMAIL dashboard admin identity (default: admin@) --reset-admin-password generate a new admin password and print it once --skip-docker-install fail rather than install Docker --build build the images from source instead of pulling them --no-build skip images entirely (a host that already has them) --hosted run this server in HOSTED (multi-tenant) mode. Writes NUCLEUS_DEPLOYMENT_MODE=hosted to deploy/.env, which is what persists across updates; omitting the flag later does NOT switch back. --refresh-from DIR refresh an existing install from an unpacked bundle -y, --yes never prompt (also the default when stdin is not a TTY) -h, --help Environment overrides: NUCLEUS_DIR, NUCLEUS_VERSION, NUCLEUS_REPO_URL, NUCLEUS_BUNDLE_URL, NUCLEUS_HEALTH_TIMEOUT. Secrets live in /deploy/.env. Back that file up: without it the audit chain cannot be verified and the data volume cannot be reused. USAGE fi exit 0 } while [[ $# -gt 0 ]]; do case "$1" in --dir) INSTALL_DIR="$2"; shift 2 ;; --ref) REF="$2"; shift 2 ;; --domain) DOMAIN="$2"; shift 2 ;; --admin-email) ADMIN_EMAIL="$2"; shift 2 ;; --reset-admin-password) RESET_ADMIN=1; shift ;; --skip-docker-install) SKIP_DOCKER_INSTALL=1; shift ;; --build) BUILD_FROM_SOURCE=1; shift ;; --no-build) NO_BUILD=1; shift ;; --hosted) WANT_HOSTED=1; shift ;; --refresh-from) REFRESH_FROM="$2"; shift 2 ;; -y|--yes) ASSUME_YES=1; shift ;; -h|--help) usage ;; *) die "unknown flag: $1 (try --help)" ;; esac done confirm() { # $1 = question. Returns 0 to proceed. Non-interactive runs always proceed. [[ "$ASSUME_YES" == 1 ]] && return 0 local reply read -r -p " $1 [Y/n] " reply [[ -z "$reply" || "$reply" =~ ^[Yy] ]] } # ── helpers ─────────────────────────────────────────────────────────── have() { command -v "$1" >/dev/null 2>&1; } # version_ge A B : true when A >= B (dotted numerics). version_ge() { [[ "$(printf '%s\n%s\n' "$2" "$1" | sort -V | head -n1)" == "$2" ]] } # version_gt A B : true when A > B. Strict, so equal versions are not "newer" -- the # version ratchet below must let a re-run of the SAME release through. version_gt() { [[ "$1" != "$2" ]] && version_ge "$1" "$2" } rand_b64() { openssl rand -base64 "$1" | tr -d '\n'; } rand_hex() { openssl rand -hex "$1" | tr -d '\n'; } # env_get KEY -> value from $ENV_FILE (empty if absent/blank). Strips one layer of quotes. # # The trailing \r strip is not cosmetic. A CRLF .env made every blank value read as # "\r", which is one character, not zero -- so `fill_secret`'s emptiness test said # "already set" for every secret and generated NOTHING. The stack then died on # `required variable NUCLEUS_DB_PASSWORD is missing a value`, several steps later and # with no mention of line endings. The bundle is built LF now and normalised again # below, but a stray CRLF must never again be able to mean "no secrets". env_get() { local line line=$(grep -E "^${1}=" "$ENV_FILE" 2>/dev/null | tail -n1 || true) line="${line%$'\r'}" line="${line#*=}" line="${line%$'\r'}" line="${line%\"}"; line="${line#\"}" line="${line%\'}"; line="${line#\'}" printf '%s' "$line" } # Rewrite $ENV_FILE with LF endings. Run once, right after the file is created from # .env.example, so everything downstream -- env_get, docker compose interpolation, # the app's own dotenv parsing -- sees clean bytes. # `tr -d | cmp` rather than `grep $'\r'`: no pattern to lose and no text-mode input, so # it cannot report a carriage return that is not there (or miss one that is). normalise_env_endings() { [[ -f "$ENV_FILE" ]] || return 0 if LC_ALL=C tr -d '\r' < "$ENV_FILE" | cmp -s - "$ENV_FILE"; then return 0 # already clean; leave the file untouched fi LC_ALL=C tr -d '\r' < "$ENV_FILE" > "$ENV_FILE.lf" mv "$ENV_FILE.lf" "$ENV_FILE" chmod 600 "$ENV_FILE" fixed "normalised deploy/.env to LF line endings" } # env_set KEY VALUE -> replace the line in place, or append. awk with ENVIRON, so the # value is never interpreted by sed/shell -- a hash full of `$` goes in verbatim. env_set() { local key="$1" K="$key" V="$2" awk ' BEGIN { k = ENVIRON["K"]; v = ENVIRON["V"]; done = 0 } $0 ~ ("^" k "=") { if (!done) { print k "=" v; done = 1 }; next } { print } END { if (!done) print k "=" v } ' "$ENV_FILE" > "$ENV_FILE.tmp" mv "$ENV_FILE.tmp" "$ENV_FILE" chmod 600 "$ENV_FILE" } # fill_secret KEY GENERATOR-CMD... -> generate only when blank. Never overwrites. fill_secret() { local key="$1"; shift if [[ -z "$(env_get "$key")" ]]; then env_set "$key" "$("$@")" GENERATED+=("$key") fi } # HOSTED mode, read from deploy/.env rather than from a flag that has to be remembered. # # .env is the one file that survives `devolyn update` -- the bundle replaces everything # else -- so a mode kept there is a mode that persists, with no second place to set it # and no way for an update to quietly revert a shared server to single-tenant behaviour. # `--hosted` only writes that line; the line is what takes effect. # # The overlay is not optional in HOSTED, and this is the reason: the runner's supervisor # refuses to run in HOSTED and exits 78, while the base file gives it # `restart: unless-stopped`. Setting the mode in .env ALONE would leave Docker restarting # a container that is correctly refusing, forever. The overlay puts the runner behind a # profile nothing activates, so it never starts. hosted_mode() { [[ "$(env_get NUCLEUS_DEPLOYMENT_MODE | tr '[:upper:]' '[:lower:]')" == "hosted" ]] } # runner_container_ids -> the ids of any runner container, running or stopped. # # `compose ps -q -a runner` finds it even when the overlay has put the service behind an # inactive profile, because naming a service addresses it directly. Measured, because the # whole fix depends on it. # # Captured whole rather than piped into `head`: a producer piped into something that exits # early dies of SIGPIPE, and under `set -o pipefail` that becomes the pipeline's status -- # which is how a backup reported a file it had just written as missing. runner_container_ids() { compose ps -q -a runner 2>/dev/null || true } # withdraw_runner -> stop and remove any runner container. For HOSTED only. # # The overlay's profile stops compose CREATING a runner. It does nothing about one that # already exists, and that is the bug: a box switched from SINGLE to HOSTED keeps the # container it started under SINGLE, still running, with `restart: unless-stopped` to put # it back if it stops. Measured on a throwaway project -- `up -d --force-recreate` with # the overlay leaves the existing runner running -- and seen on production, where # `devolyn status` reported "runner Up About an hour" after the switch. # # A HOSTED runner is not a cosmetic problem. It is the 006 path: it executes customer code # and holds a GitHub registration token. Withheld routes do not help if the process that # used them is still alive. withdraw_runner() { local ids ids="$(runner_container_ids)" [[ -n "$ids" ]] || return 0 # `rm -sf`: stop then force-remove. Addresses the service by name, so the inactive # profile is not in the way, and leaves every other service alone. compose rm -sf runner >/dev/null 2>&1 || true if [[ -n "$(runner_container_ids)" ]]; then die "a runner container exists and could not be removed. HOSTED must not run one -- it executes customer code. Remove it by hand: docker rm -f \$(docker ps -aq --filter label=com.docker.compose.service=runner)" fi fixed "removed the runner container left over from SINGLE mode (HOSTED does not run one)" } # Prod pulls prebuilt images and has no `build:` anywhere. --build layers the build # overlay on top, which adds the build definitions back to those same services -- # so mounts, limits and health gates have one definition and cannot drift. compose() { local files=(-f "$COMPOSE_FILE") if [[ "$BUILD_FROM_SOURCE" == 1 && -f "$BUILD_COMPOSE_FILE" ]]; then files+=(-f "$BUILD_COMPOSE_FILE") fi # Last, so its settings win over both. Every compose call goes through here -- config, # pull, up, ps, exec -- so the overlay cannot be applied to some of them and not # others, which is how a runner gets started on a host that must not have one. if [[ -f "$HOSTED_COMPOSE_FILE" ]] && hosted_mode; then files+=(-f "$HOSTED_COMPOSE_FILE") # The App's private key, mounted only once it EXISTS. See the header of # docker-compose.hosted-key.yml: an absent bind-mount source is not an error, it is # a directory Docker creates where the key was meant to go. # # `:-` because this function is DEFINED here and the path variables are assigned # later, after the bundle is unpacked. Under `set -u` a bare reference would abort # the installer on any compose call that happened before that point, which is a far # worse failure than a missing mount. The behavioural tests in # tests/unit/test_installer_hosted_mode.py assert the overlay really is applied when # the key exists, so the tolerant reference cannot hide a regression. if [[ -f "${HOSTED_KEY_COMPOSE_FILE:-}" && -f "$(gh_app_key_path)" ]]; then files+=(-f "$HOSTED_KEY_COMPOSE_FILE") fi fi docker compose "${files[@]}" "$@" } # Where the hosted GitHub App's private key lives on this host. # # Resolved the way COMPOSE resolves it, or the check above would disagree with the mount # it guards: a relative path in a compose file is relative to the project directory, which # is the directory of the first -f file -- deploy/ -- and not to the current directory. gh_app_key_path() { local p p=$(env_get DEVOLYN_GH_APP_KEY) [[ -n "$p" ]] || p="./secrets/github-app.pem" case "$p" in /*) printf '%s' "$p" ;; *) printf '%s' "${INSTALL_DIR}/deploy/${p#./}" ;; esac } # ── what the closing summary says, and why it is three functions ────── # # The summary is the last thing an operator reads and the first thing they act on, and # on a HOSTED server it was wrong in three places at once: it asserted a self-signed # certificate to a box terminating TLS with a real one, announced a self-hosted runner # that HOSTED deliberately never starts, and ended by telling the operator to run # `devolyn onboard` -- which mints a CI credential and prints a workflow file for a flow # HOSTED does not use at all. # # Separated out of `main` so each piece can be exercised on its own: the parts that # DECIDE (`tls_kind`, which needs a socket) are apart from the parts that SPEAK # (`tls_note`, `next_steps`), and a test can pin the words without standing up nginx. # tls_kind -> self-signed | real | unknown # # READ from the certificate nginx is actually serving, rather than assumed. A # self-signed certificate has issuer == subject; anything a CA issued does not. Asked # over the socket because the volume is inside a container and the socket is what a # browser will meet. tls_kind() { local text issuer subject text=$(printf '' | openssl s_client -connect "127.0.0.1:443" -servername "${DOMAIN:-localhost}" 2>/dev/null \ | openssl x509 -noout -issuer -subject 2>/dev/null) || true issuer=$(printf '%s\n' "$text" | sed -n 's/^issuer=//p' | tr -d ' ') subject=$(printf '%s\n' "$text" | sed -n 's/^subject=//p' | tr -d ' ') if [[ -z "$issuer" || -z "$subject" ]]; then printf 'unknown' elif [[ "$issuer" == "$subject" ]]; then printf 'self-signed' else printf 'real' fi } # tls_note -> the line under the dashboard URL, or nothing. # # UNKNOWN PRINTS NOTHING, deliberately. Guessing in either direction is worse than # silence: "your browser will warn" on a real certificate is a false statement about the # operator's own setup, made by the thing that just configured it, and promising a # trusted certificate on a self-signed install sends them hunting for a problem that is # not there. tls_note() { case "${1:-unknown}" in self-signed) printf '%s\n' " (self-signed certificate: your browser will warn once)" ;; real) printf '%s\n' " (serving the certificate mounted at /etc/nginx/certs)" ;; *) : ;; esac } # next_steps -> what to do now, for THIS kind of installation. # # An installer that ends by telling the operator to do something that does not apply is # an installer they stop reading, and after that the parts that do apply go unread too. next_steps() { if ! hosted_mode; then cat < GitHub. Installing the App IS the connection: there is no workflow file to paste and no per-repository onboarding. EOF else cat < GitHub. Installing the App IS the connection: there is no workflow file to paste and no per-repository onboarding. EOF fi cat < die unless SRC holds every required file. # # Checked on the host rather than trusting the build: the bundle is assembled in a # different repository (devolyn-dist/scripts/build-dist.sh), whose own manifest check # cannot be run from here and had the same omission. Two independent checks, because the # failure they catch is a file that is simply absent -- which produces a perfectly valid # tarball and no error anywhere. assert_bundle_complete() { local src="$1" rel missing=() for rel in "${BUNDLE_MANAGED[@]}"; do [[ -f "$src/$rel" ]] || missing+=("$rel") done if (( ${#missing[@]} )); then die "this bundle is incomplete -- missing: ${missing[*]}. Refusing to refresh ${INSTALL_DIR:-the installation} from it, because a partial refresh leaves an install that is neither the old release nor the new one." fi } # refresh_managed_files SRC DEST -> replace DEST's bundle-owned files with SRC's. # # Each file is written to a sibling temp name and then renamed over the target. rename() # is atomic and swaps the directory entry, so a process holding the OLD file open keeps # reading the old inode -- which matters because one of these files is very often the # installer that is running right now. Overwriting it in place would let bash re-read a # half-replaced script it is still executing. refresh_managed_files() { local src="$1" dest="$2" rel skip changed=0 assert_bundle_complete "$src" # DERIVED FROM THE BUNDLE, not from a list kept here. Whatever the tarball contains is # what an upgrade installs, so the next release that adds a deploy file needs no edit # in this function and cannot be forgotten in it. # # `find -print0` and a null-delimited read, because a path is allowed to contain # anything except NUL -- and an upgrade that mangled a filename would be writing a # file nobody asked for next to the one that matters. while IFS= read -r -d '' rel; do rel="${rel#./}" for skip in "${BUNDLE_NEVER[@]}"; do [[ "$rel" == "$skip" ]] && continue 2 done [[ -f "$src/$rel" ]] || continue if [[ -f "$dest/$rel" ]] && cmp -s "$src/$rel" "$dest/$rel"; then continue fi mkdir -p "$(dirname "$dest/$rel")" cp "$src/$rel" "$dest/$rel.new" # Carry the executable bit across; `git show` in the bundle build emits content only. [[ -x "$src/$rel" ]] && chmod +x "$dest/$rel.new" mv -f "$dest/$rel.new" "$dest/$rel" changed=$((changed + 1)) # `cd` into the bundle and walk `.`, so find emits paths relative to it and the # prefix comes off with a bash expansion. No `sed -z`, which is GNU-only. done < <(cd "$src" && find . -type f -print0) printf '%s' "$changed" } # Sourced with DEVOLYN_INSTALL_LIB=1 by tests/unit/test_installer_env.py, which needs # env_get and fill_secret without installing Docker on the machine running the suite. # Everything above this line is definitions only; everything below it acts. Same # convention as deploy/setup, for the same reason: the alternative is a second copy of # these functions inside the test, which would drift from the ones that actually run. # # Written as an `if` rather than `[[ ... ]] && return 0`: under `set -e` that AND-list # evaluates to status 1 whenever the variable is unset, and a failing list at top level # ends the script -- which would mean the installer exits silently on every real run. if [[ "${DEVOLYN_INSTALL_LIB:-}" == "1" ]]; then return 0 fi # ══════════════════════════════════════════════════════════════════════ # EVERYTHING BELOW RUNS INSIDE main(), CALLED ON THE LAST LINE. # # This is not organisation, it is the fix for a silent failure that made # `curl ... | sudo bash` stop dead after step 7 -- no error, no summary, exit 0, # containers never recreated. The operator had every reason to believe the update # had worked. # # In pipe mode bash reads the script FROM STDIN, incrementally: read a chunk, # execute it, read more. So stdin is simultaneously the program and an inheritable # file descriptor. `docker compose exec` forwards stdin to the container whether or # not the remote command wants it -- `-T` only disables the pseudo-TTY, it does not # detach stdin -- so it drained the unread remainder of the installer. bash then # found EOF where step 8 should have been and exited 0, having done what looked # like a successful run. # # Wrapping the body in a function means bash must parse through the closing brace # before it can execute anything, and `main "$@"` is the last line -- so by the time # any of this runs, the whole script has already been read off stdin and nothing # downstream can eat it. The `/dev/null ;; dnf) dnf install -y -q "$@" >/dev/null ;; yum) yum install -y -q "$@" >/dev/null ;; *) die "no supported package manager (apt/dnf/yum); install $* by hand and re-run" ;; esac } # The tools the rest of this script needs. ubuntu:24.04 base has none of curl/git/openssl. NEED=() for t in curl openssl git; do have "$t" || NEED+=("$t"); done have update-ca-certificates || have update-ca-trust || NEED+=(ca-certificates) if [[ ${#NEED[@]} -gt 0 ]]; then info "installing: ${NEED[*]}" [[ "$PKG" == apt ]] && apt-get update -q >/dev/null pkg_install "${NEED[@]}" fixed "installed ${NEED[*]}" fi ok "tools: curl, openssl, git" # ══════════════════════════════════════════════════════════════════════ # 2. Docker Engine + Compose # ══════════════════════════════════════════════════════════════════════ step "Docker" # Snap docker is the single most common broken-Docker on Ubuntu: confined, stale, and it # ships its own compose that ignores /etc/docker/daemon.json. Out it goes. if have snap && snap list docker >/dev/null 2>&1; then warn "snap docker found -- removing (it cannot run this stack)" snap remove --purge docker >/dev/null 2>&1 || snap remove docker >/dev/null fixed "removed snap docker" fi install_docker() { [[ "$SKIP_DOCKER_INSTALL" == 1 ]] && die "Docker is not installed and --skip-docker-install was given" case "$OS_ID:$OS_LIKE" in ubuntu:*|debian:*|*:*debian*|*:*ubuntu*|fedora:*|centos:*|rhel:*|rocky:*|almalinux:*|*:*rhel*|*:*fedora*) ;; *) die "don't know how to install Docker on ${OS_ID}; install Docker Engine 24+ with the compose plugin, then re-run" ;; esac info "installing Docker Engine + Compose plugin (get.docker.com)" curl -fsSL https://get.docker.com -o /tmp/get-docker.sh sh /tmp/get-docker.sh >/tmp/get-docker.log 2>&1 || { tail -n 30 /tmp/get-docker.log; die "Docker install failed (log: /tmp/get-docker.log)"; } rm -f /tmp/get-docker.sh fixed "installed Docker Engine" } have docker || install_docker # On cgroup v2 with no init system (a container, an LXC guest, some CI runners) the root # cgroup still holds our own processes, so the kernel's "no internal processes" rule stops # the domain controllers (memory, io) from being delegated to children. dockerd then gets a # root that is `domain threaded`, and any container with a memory limit -- which is every # service in the compose file -- fails with "cannot enter cgroupv2 ... in threaded mode". # Plain `docker run` still works, which is what makes this one confusing. # # The cure is what Docker's own dind entrypoint does: move every process into a leaf # cgroup, then enable every controller for the subtree. Harmless where not needed. prepare_cgroups() { [[ "$HAS_SYSTEMD" == 0 && -f /sys/fs/cgroup/cgroup.controllers ]] || return 0 [[ -w /sys/fs/cgroup/cgroup.subtree_control ]] || return 0 mkdir -p /sys/fs/cgroup/init xargs -rn1 < /sys/fs/cgroup/cgroup.procs > /sys/fs/cgroup/init/cgroup.procs 2>/dev/null || : sed -e 's/ / +/g' -e 's/^/+/' < /sys/fs/cgroup/cgroup.controllers > /sys/fs/cgroup/cgroup.subtree_control 2>/dev/null || : } # A daemon that was started WITHOUT that preparation has already created a threaded # `docker` cgroup; it has to go before a restart can help. Only ever called with the daemon # stopped, and only removes cgroups that are empty (rmdir refuses otherwise). remove_threaded_cgroups() { local f d # cgroup paths never contain whitespace; deepest first so parents empty out. while IFS= read -r f; do grep -q '^threaded' "$f" 2>/dev/null || continue d=$(dirname "$f") find "$d" -depth -mindepth 1 -type d -exec rmdir {} \; 2>/dev/null || : rmdir "$d" 2>/dev/null || : done < <(find /sys/fs/cgroup -mindepth 1 -maxdepth 3 -name cgroup.type 2>/dev/null | sort -r) } start_dockerd() { if [[ "$HAS_SYSTEMD" == 1 ]]; then systemctl enable --now docker >/dev/null 2>&1 || systemctl start docker else # No init system: run the daemon ourselves. Same daemon.json, same socket. if ! pgrep -x dockerd >/dev/null; then prepare_cgroups nohup dockerd >/var/log/dockerd.log 2>&1 & fi fi for _ in $(seq 1 60); do docker info >/dev/null 2>&1 && return 0 sleep 1 done [[ "$HAS_SYSTEMD" == 1 ]] || tail -n 20 /var/log/dockerd.log >&2 return 1 } restart_dockerd() { if [[ "$HAS_SYSTEMD" == 1 ]]; then systemctl restart docker else pkill -x dockerd || true for _ in $(seq 1 30); do pgrep -x dockerd >/dev/null || break; sleep 1; done pkill -x containerd || true remove_threaded_cgroups prepare_cgroups nohup dockerd >/var/log/dockerd.log 2>&1 & fi for _ in $(seq 1 60); do docker info >/dev/null 2>&1 && return 0; sleep 1; done return 1 } if ! docker info >/dev/null 2>&1; then info "docker daemon not running -- starting it" start_dockerd || die "could not start the Docker daemon" fixed "docker daemon started" fi DOCKER_VER=$(docker version --format '{{.Server.Version}}' 2>/dev/null | sed 's/[^0-9.].*//') version_ge "$DOCKER_VER" "$MIN_DOCKER" || die "Docker ${DOCKER_VER} is too old; need ${MIN_DOCKER}+ (apt-get install docker-ce, or remove the distro package and re-run)" ok "Docker Engine ${DOCKER_VER}" if ! docker compose version >/dev/null 2>&1; then info "compose plugin missing -- installing" case "$PKG" in apt) apt-get update -q >/dev/null; pkg_install docker-compose-plugin ;; dnf|yum) pkg_install docker-compose-plugin ;; esac docker compose version >/dev/null 2>&1 || die "docker compose plugin could not be installed" fixed "installed docker-compose-plugin" fi COMPOSE_VER=$(docker compose version --short 2>/dev/null | sed 's/^v//; s/[^0-9.].*//') version_ge "$COMPOSE_VER" "$MIN_COMPOSE" || die "Docker Compose ${COMPOSE_VER} is too old; need ${MIN_COMPOSE}+" ok "Docker Compose ${COMPOSE_VER}" # Can the daemon actually run what the compose file asks for? Every service carries a # memory limit, and that is exactly the thing a mis-delegated cgroup v2 root cannot do # while a plain `docker run` still can. Test the real case, not the easy one. LIMITS_PROBE_IMAGE="alpine:3.20" if ! docker image inspect "$LIMITS_PROBE_IMAGE" >/dev/null 2>&1; then docker pull -q "$LIMITS_PROBE_IMAGE" >/dev/null 2>&1 \ || die "cannot pull ${LIMITS_PROBE_IMAGE}: the HOST cannot reach Docker Hub. Check /etc/resolv.conf and outbound HTTPS, then re-run" fi # `docker run` without -i does not attach stdin, so this was never the pipe-mode # culprit -- the redirection is here so that "no command in this script reads stdin" # is true by inspection rather than by knowing which flags imply it. limits_ok() { docker run --rm --memory 64m --cpus 0.5 "$LIMITS_PROBE_IMAGE" true /dev/null 2>&1; } if limits_ok; then ok "containers start with resource limits" else if [[ "$HAS_SYSTEMD" == 0 ]]; then warn "a container with a memory limit cannot start (cgroup v2 delegation) -- repairing and restarting the daemon" restart_dockerd || die "docker did not come back after the cgroup repair (see /var/log/dockerd.log)" limits_ok || die "containers with memory limits still cannot start. A daemon that was started before this installer (without cgroup preparation) converts the cgroup root to 'threaded', and that is not reversible from inside: reboot this host or recreate this container, then re-run -- the installer prepares cgroups before it ever starts the daemon" fixed "cgroup v2 controllers delegated; daemon restarted" else die "a container with a memory limit cannot start. On a systemd host this is usually cgroup configuration -- check 'docker info' for cgroup driver/version and 'journalctl -u docker'" fi fi # ══════════════════════════════════════════════════════════════════════ # 3. Docker DNS # ══════════════════════════════════════════════════════════════════════ step "Docker DNS" # The daemon resolves names for PULLS with the host's resolver; CONTAINERS resolve with # whatever the daemon hands them, which on a host running systemd-resolved (127.0.0.53) or # behind some VPNs is nothing that works. Every `RUN apt-get` and `pip install` in the # build then fails with "Temporary failure resolving". Test from inside a container. DNS_PROBE_IMAGE="$LIMITS_PROBE_IMAGE" if ! docker image inspect "$DNS_PROBE_IMAGE" >/dev/null 2>&1; then docker pull -q "$DNS_PROBE_IMAGE" >/dev/null 2>&1 \ || die "cannot pull ${DNS_PROBE_IMAGE}: the HOST cannot reach Docker Hub. Check /etc/resolv.conf and outbound HTTPS, then re-run" fi container_dns_ok() { docker run --rm "$DNS_PROBE_IMAGE" sh -c 'nslookup deb.debian.org >/dev/null 2>&1 && nslookup registry-1.docker.io >/dev/null 2>&1' "$DAEMON_JSON.tmp" && mv "$DAEMON_JSON.tmp" "$DAEMON_JSON" else die "${DAEMON_JSON} exists and neither python3 nor jq is available to merge into it; add \"dns\": [\"8.8.8.8\",\"1.1.1.1\"] by hand and re-run" fi else printf '{\n "dns": ["8.8.8.8", "1.1.1.1"]\n}\n' > "$DAEMON_JSON" fi restart_dockerd || die "docker did not come back after the DNS change (see: journalctl -u docker)" container_dns_ok || die "containers still cannot resolve names after the fix; the host may block outbound DNS (port 53)" fixed "docker DNS -> 8.8.8.8 / 1.1.1.1 (${DAEMON_JSON})" fi # ══════════════════════════════════════════════════════════════════════ # 4. Source # ══════════════════════════════════════════════════════════════════════ step "Source" # Are we running from a file on disk, or piped into bash? # # "BASH_SOURCE is empty when piped" is true only at the TOP LEVEL. Inside a function -- # which everything now is -- bash reports the FUNCTION NAME instead, so BASH_SOURCE[0] # is the literal string "main" on a piped run. Testing it for non-emptiness therefore # says "running from a file" for every `curl | bash`, which is the opposite of the # truth, and it silently disabled the upgrade refresh below. # # So the test is whether it names a file that exists. That is the question actually # being asked, it was already the condition used just below, and it cannot be fooled by # how bash chooses to describe its own call stack. SELF="${BASH_SOURCE[0]:-}" [[ -n "$SELF" && -f "$SELF" ]] || SELF="" # The bundle tree the running installer belongs to, if any. Used below to refresh an # install directory from a NEWER extracted bundle without going near the network. SELF_TREE="" if [[ -n "$SELF" ]]; then CANDIDATE=$(cd "$(dirname "$SELF")/.." && pwd) if [[ -f "$CANDIDATE/deploy/docker-compose.prod.yml" ]]; then SELF_TREE="$CANDIDATE" INSTALL_DIR="${INSTALL_DIR:-$CANDIDATE}" fi fi INSTALL_DIR="${INSTALL_DIR:-$INSTALL_DIR_DEFAULT}" # fetch_bundle -> downloads, checksum-verifies and extracts the published bundle into a # temp directory, printing its path. Factored out because an UPGRADE needs exactly the # same fetch as a fresh install; having one copy is what stops the two drifting. fetch_bundle() { local dest="$1" expected actual have curl || die "curl is required to download the deploy bundle" have tar || die "tar is required to unpack the deploy bundle" curl -fsSL "$BUNDLE_URL" -o "$dest/bundle.tar.gz" \ || die "could not download ${BUNDLE_URL}" # The checksum is fetched from the same origin, so this is not a defence against # someone who controls that origin. It IS a defence against the thing that actually # happens: a truncated download, a captive portal, a proxy that returns a login page # with a 200. Running a partial shell archive as root is the failure this prevents. if curl -fsSL "${BUNDLE_URL}.sha256" -o "$dest/bundle.sha256" 2>/dev/null; then expected=$(awk '{print $1}' "$dest/bundle.sha256") if have sha256sum; then actual=$(sha256sum "$dest/bundle.tar.gz" | awk '{print $1}') else actual=$(shasum -a 256 "$dest/bundle.tar.gz" | awk '{print $1}') fi [[ "$expected" == "$actual" ]] \ || die "bundle checksum mismatch (expected ${expected}, got ${actual}). Refusing to run it." ok "bundle checksum verified" else warn "no published checksum at ${BUNDLE_URL}.sha256 -- continuing unverified" fi mkdir -p "$dest/tree" # --strip-components=1: the tarball is rooted at devolyn-guard-/. tar xzf "$dest/bundle.tar.gz" -C "$dest/tree" --strip-components=1 \ || die "could not unpack the deploy bundle" [[ -f "$dest/tree/deploy/docker-compose.prod.yml" ]] \ || die "the bundle did not contain deploy/docker-compose.prod.yml" } if [[ -f "$INSTALL_DIR/deploy/docker-compose.prod.yml" ]]; then if git -C "$INSTALL_DIR" rev-parse --git-dir >/dev/null 2>&1; then # A source checkout. `devolyn update` git-pulls it, so refreshing from the bundle # here would fight that and could overwrite local changes. ok "using ${INSTALL_DIR} (git checkout)" elif [[ -n "$REFRESH_FROM" ]]; then # `devolyn update` has already downloaded and verified a bundle; reuse it rather # than fetching the same bytes twice. [[ -f "$REFRESH_FROM/deploy/docker-compose.prod.yml" ]] \ || die "--refresh-from ${REFRESH_FROM} is not an unpacked bundle" N=$(refresh_managed_files "$REFRESH_FROM" "$INSTALL_DIR") if [[ "$N" == 0 ]]; then ok "using ${INSTALL_DIR} (bundle files already current)" else fixed "refreshed ${N} bundle file(s) in ${INSTALL_DIR} (deploy/.env untouched)" fi elif [[ -z "$SELF" ]]; then # Piped into bash over an EXISTING bundle install: this is an upgrade, and it is the # case that failed on production. Without this the installer kept the OLD compose # file -- still pinning the previous image tags -- so it recreated nothing and the # operator was told the new version was installed while the old one kept running. info "existing bundle install -- refreshing it from ${BUNDLE_URL}" TMP_BUNDLE=$(mktemp -d) trap 'rm -rf "$TMP_BUNDLE"' EXIT fetch_bundle "$TMP_BUNDLE" N=$(refresh_managed_files "$TMP_BUNDLE/tree" "$INSTALL_DIR") if [[ "$N" == 0 ]]; then ok "using ${INSTALL_DIR} (already at the published version)" else fixed "refreshed ${N} bundle file(s) in ${INSTALL_DIR} (deploy/.env untouched)" fi elif [[ -n "$SELF_TREE" && "$SELF_TREE" != "$INSTALL_DIR" ]]; then # Run from one bundle tree against a DIFFERENT install directory -- somebody # extracted a release and pointed it at an existing install. Refresh from the tree # in hand rather than the network: it is already on disk, it is what the operator # chose, and a password reset should never depend on reaching get.devolyn.com. N=$(refresh_managed_files "$SELF_TREE" "$INSTALL_DIR") if [[ "$N" == 0 ]]; then ok "using ${INSTALL_DIR} (bundle files already current)" else fixed "refreshed ${N} bundle file(s) in ${INSTALL_DIR} (deploy/.env untouched)" fi else # The installer IS the one in the install directory -- `devolyn reset-admin-password` # and any re-run of `./deploy/install.sh` in place. There is nothing to refresh # FROM: these files are the source. Staleness is handled instead by the version # ratchet in step 5, which refuses outright if this installer is older than the # installation, so an old copy on disk cannot quietly re-pin the stack backwards. # # Deliberately no network fetch here. Making a password reset download and install # a newer bundle would turn a maintenance command into an unrequested upgrade, and # break it entirely on an air-gapped host. ok "using ${INSTALL_DIR}" fi elif [[ -n "${NUCLEUS_REPO_URL:-}" ]]; then # Explicitly asked for a source checkout. This is the path for someone who HAS # access to the repository and wants the full tree -- notably the GitHub PR gate, # whose runner bind-mounts src/, scripts/ and action/ (see docker-compose.prod.yml). info "cloning ${REPO_URL} @ ${REF} -> ${INSTALL_DIR}" git clone --quiet --depth 1 --branch "$REF" "$REPO_URL" "$INSTALL_DIR" \ || die "clone failed. Is NUCLEUS_REPO_URL right (${REPO_URL}) and the ref '${REF}' published?" fixed "cloned ${REF}" else # The default when piped through `curl | bash`: fetch the DEPLOY BUNDLE, not the # source. Guard's repository is private, so cloning it is not something a stranger # can do -- and they do not need to. The bundle carries the compose file, this # installer, the database's role-init script and an env template; the images # themselves come from GHCR. Verified against its published checksum before a # single byte of it is trusted. info "downloading the deploy bundle from ${BUNDLE_URL}" TMP_BUNDLE=$(mktemp -d) trap 'rm -rf "$TMP_BUNDLE"' EXIT fetch_bundle "$TMP_BUNDLE" mkdir -p "$INSTALL_DIR" cp -r "$TMP_BUNDLE/tree/." "$INSTALL_DIR/" [[ -f "$INSTALL_DIR/deploy/docker-compose.prod.yml" ]] \ || die "the bundle did not contain deploy/docker-compose.prod.yml" fixed "deploy bundle unpacked into ${INSTALL_DIR}" fi cd "$INSTALL_DIR" COMPOSE_FILE="$INSTALL_DIR/deploy/docker-compose.prod.yml" BUILD_COMPOSE_FILE="$INSTALL_DIR/deploy/docker-compose.build.yml" HOSTED_COMPOSE_FILE="$INSTALL_DIR/deploy/docker-compose.hosted.yml" HOSTED_KEY_COMPOSE_FILE="$INSTALL_DIR/deploy/docker-compose.hosted-key.yml" ENV_FILE="$INSTALL_DIR/deploy/.env" GIT_SHA=$(git -C "$INSTALL_DIR" rev-parse --short HEAD 2>/dev/null || true) [[ -n "$GIT_SHA" ]] && info "commit ${GIT_SHA}" || info "not a git checkout (release archive)" # ══════════════════════════════════════════════════════════════════════ # 5. Secrets # ══════════════════════════════════════════════════════════════════════ step "Secrets (deploy/.env)" GENERATED=() if [[ ! -f "$ENV_FILE" ]]; then cp "$INSTALL_DIR/deploy/.env.example" "$ENV_FILE" chmod 600 "$ENV_FILE" fixed "created deploy/.env from .env.example" else ok "deploy/.env exists -- only blank values will be filled" fi # Before anything reads it. Also repairs a host that already has a CRLF deploy/.env # from an earlier bundle: this only rewrites line endings, never a value, so the # "existing values are never touched" rule is intact. normalise_env_endings # Where the dashboard will be reached. Recorded so `devolyn onboard` can print the # right URL later, and so the summary is true. Not a NUCLEUS_ key: the app ignores it. if [[ -z "$DOMAIN" ]]; then DOMAIN=$(env_get GUARD_PUBLIC_URL); DOMAIN="${DOMAIN#https://}"; DOMAIN="${DOMAIN#http://}"; DOMAIN="${DOMAIN%%/*}" fi if [[ -z "$DOMAIN" ]]; then DOMAIN=$(hostname -I 2>/dev/null | awk '{print $1}') [[ -n "$DOMAIN" ]] || DOMAIN=$(ip -4 route get 1.1.1.1 2>/dev/null | awk '{for(i=1;i<=NF;i++) if($i=="src") print $(i+1)}' | head -n1) [[ -n "$DOMAIN" ]] || DOMAIN=localhost fi PUBLIC_URL="https://${DOMAIN}" env_set GUARD_PUBLIC_URL "$PUBLIC_URL" # The same value under the name the GitHub settings class reads directly. The backend # falls back to GUARD_PUBLIC_URL when this is absent, so an older deploy/.env keeps # working -- writing both means a fresh install does not depend on that fallback at all. env_set NUCLEUS_GITHUB_PUBLIC_URL "$PUBLIC_URL" # Fixed-by-design values. Written only if blank, so an operator's edit survives. [[ -n "$(env_get NUCLEUS_ENVIRONMENT)" ]] || env_set NUCLEUS_ENVIRONMENT PRODUCTION [[ -n "$(env_get NUCLEUS_DEBUG)" ]] || env_set NUCLEUS_DEBUG false [[ -n "$(env_get NUCLEUS_DASHBOARD_COOKIE_SECURE)" ]] || env_set NUCLEUS_DASHBOARD_COOKIE_SECURE true [[ -n "$(env_get NUCLEUS_IMPACT_BLAST_RADIUS_ADVISORY)" ]] || env_set NUCLEUS_IMPACT_BLAST_RADIUS_ADVISORY true [[ -n "$GIT_SHA" ]] && env_set GIT_SHA "$GIT_SHA" # ── refuse to move this installation BACKWARDS ──────────────────────── # # `env_set DEVOLYN_VERSION` used to be unconditional, and that made an old installer a # downgrade tool. The route in is ordinary: `devolyn reset-admin-password` and # `devolyn update` both run the install.sh sitting in the install directory, and until # that file started being refreshed it stayed at whatever version first wrote it. So a # password reset, months after an upgrade, re-pinned DEVOLYN_VERSION to the OLD release # and the next `compose up` pulled old images. # # The damage is not a version string. Migrations have already run: the database is at # the NEW schema, and nothing downgrades it, because alembic downgrade is never invoked # here. Old code then meets a schema it has never seen -- and it does so quietly, on a # run whose stated purpose was to change a password. # # So the version pin is a ratchet. It only ever goes up, and an installer older than # the installation refuses to run at all rather than half-apply itself: by this point # deploy/.env has already been touched, and continuing would leave a mix of new secrets # and old pins that is harder to reason about than a clean refusal. INSTALLED_VERSION=$(env_get DEVOLYN_VERSION) # The on-disk VERSION can be ahead of the pin if a previous run was interrupted between # the refresh and the env_set, so take whichever is higher as "what is installed". if [[ -f "$INSTALL_DIR/VERSION" ]]; then DISK_VERSION=$(tr -d ' \t\r\n' < "$INSTALL_DIR/VERSION") if [[ -n "$DISK_VERSION" ]] && version_gt "$DISK_VERSION" "${INSTALLED_VERSION:-0}"; then INSTALLED_VERSION="$DISK_VERSION" fi fi if [[ -n "$INSTALLED_VERSION" ]] && version_gt "$INSTALLED_VERSION" "$GUARD_VERSION"; then warn "this installer is ${GUARD_VERSION}, but ${INSTALL_DIR} is already at ${INSTALLED_VERSION}" printf '%s\n' \ " Refusing to downgrade. The database schema has already been migrated by" \ " ${INSTALLED_VERSION}; nothing here migrates it back, so ${GUARD_VERSION}'s code would" \ " meet a schema it does not know about." \ "" \ " This is almost always a stale installer. To do what you meant:" \ "" \ " devolyn update # fetch and run the current release" \ " devolyn reset-admin-password # if that is what you were after" \ "" \ " To deliberately move this host back to ${GUARD_VERSION}, restore the database" \ " backup from before the upgrade first (deploy/scripts/restore.sh)." die "refusing to downgrade ${INSTALLED_VERSION} -> ${GUARD_VERSION}" fi # The release this install is pinned to. Written rather than left to the compose # default so that `docker compose` run BY HAND on this host resolves the same images # the installer pulled -- otherwise a later `compose up` could quietly pull a # different version than the one that was verified here. env_set DEVOLYN_VERSION "$GUARD_VERSION" # And so Settings -> About names the release that is actually running. The setting # defaults to the development version; without this the dashboard reports that # number to every user of every release, which is the one fact that page exists for. env_set NUCLEUS_APP_VERSION "$GUARD_VERSION" # --hosted, written here: before the first `compose` call, so that call already carries # the hosted overlay. Writing it later would validate and start a single-tenant stack and # only then record that the host is multi-tenant. # # Only ever written, never cleared. The mode of a shared server is not something an # update should be able to change by omission -- taking it back is a deliberate edit to # deploy/.env. if [[ "$WANT_HOSTED" == 1 ]]; then if [[ "$(env_get NUCLEUS_DEPLOYMENT_MODE)" == "hosted" ]]; then ok "HOSTED mode (already set in deploy/.env)" else env_set NUCLEUS_DEPLOYMENT_MODE hosted fixed "set NUCLEUS_DEPLOYMENT_MODE=hosted in deploy/.env" fi fi if hosted_mode; then [[ -f "$HOSTED_COMPOSE_FILE" ]] \ || die "NUCLEUS_DEPLOYMENT_MODE=hosted, but deploy/docker-compose.hosted.yml is missing. Without the overlay the runner would start, refuse (exit 78) and be restarted forever." info "HOSTED: the GitHub connect path, the audit export, policy authoring and the runner are withheld" # Before anything is brought up, so the stack is never running with a runner it should # not have. A fresh install has none and this is a no-op; a box being switched over # from SINGLE has one, and the overlay alone would leave it running. withdraw_runner fi # These four end up inside a URL's userinfo section (the Postgres and Redis DSNs), so # they are generated as hex rather than base64. base64 emits `+`, `/` and `=`; a `/` in # the Redis password made redis-py read part of the secret as the port and the backend # died on startup. The DSN builders percent-encode now, which is what actually fixes it # and keeps every existing base64 password in every existing .env working -- this is # defence in depth, so a new install never depends on that encoding being right. # 24 bytes of hex is 48 characters, the same 192 bits of entropy as before. fill_secret POSTGRES_SUPERUSER_PASSWORD rand_hex 24 fill_secret NUCLEUS_DB_PASSWORD rand_hex 24 fill_secret NUCLEUS_DB_MIGRATION_PASSWORD rand_hex 24 fill_secret NUCLEUS_REDIS_PASSWORD rand_hex 24 fill_secret NUCLEUS_SECURITY_SECRET_KEY rand_hex 32 fill_secret NUCLEUS_AUDIT_EXPORT_TOKEN rand_b64 32 # NUCLEUS_VERIFIER_CI_TOKEN is no longer generated. CI credentials are per # organization and live in the database from 0.4.0; `devolyn onboard` mints one # and prints it once. A box-wide token could verify against any repository. # Connect GitHub. Generated whether or not it is used yet: they cost nothing unused, # and generating the encryption key LATER would mean the first person to click Connect # hits a refusal instead of a working flow. # # The encryption key protects the stored GitHub App private key -- the App's identity. # Changing it does not re-encrypt anything; the stored credential simply becomes # unreadable and GitHub has to be reconnected. That is why it is generated ONCE here # and never regenerated: fill_secret only ever fills a blank. fill_secret NUCLEUS_GITHUB_ENCRYPTION_KEY rand_hex 32 fill_secret NUCLEUS_GITHUB_RUNNER_TOKEN rand_b64 32 # Admin identity. The hash needs the backend image (scrypt via the app's own function, so # the format can never drift from what the login check expects) -- so it is filled in # step 6, after the build. Decide the plaintext now. if [[ -z "$ADMIN_EMAIL" ]]; then ADMIN_EMAIL=$(env_get NUCLEUS_DASHBOARD_ADMIN_EMAIL) if [[ -z "$ADMIN_EMAIL" || "$ADMIN_EMAIL" == "admin@example.com" ]]; then # ONLY GUESS WHEN THE GUESS CAN WORK. # # This used to be an unconditional `admin@${DOMAIN}`, and DOMAIN falls back to the # host's IP address and then to `localhost` (see where it is derived). So on a box # reached by IP -- which is how most people try this product for the first time -- # the default admin was `admin@203.0.113.10`, and on a box with no address at all # it was `admin@localhost`. The sign-in form validates with the same library the # whole product uses, and it refuses BOTH: "not within a valid top-level domain" # and "should have a period". The installer therefore finished successfully, # printed the login, and the login could never work. # # The test below is a cheap pre-filter, NOT the real validator -- it exists so the # failure arrives in one second instead of after a container build. The # authoritative check is the Python one, run against the built image further down. if [[ "$DOMAIN" == *.* && ! "$DOMAIN" =~ ^[0-9.]+$ ]]; then ADMIN_EMAIL="admin@${DOMAIN}" else die "this host has no domain name (it resolves to '${DOMAIN}'), so there is no sensible default admin address -- 'admin@${DOMAIN}' is one the sign-in form refuses, and the install would finish with an admin account that can never log in. Pass one: ${C_BOLD}--admin-email you@your-domain.example${C_RST} It only has to be an address you can receive mail at; it is never contacted during the install." fi fi fi env_set NUCLEUS_DASHBOARD_ADMIN_EMAIL "$ADMIN_EMAIL" ADMIN_PASSWORD="" # Set to 1 only after the password has been written to the DATABASE, which is the # credential a login actually checks. The summary refuses to print a password that # has not got that far. ADMIN_PASSWORD_LIVE=0 if [[ "$RESET_ADMIN" == 1 || -z "$(env_get NUCLEUS_DASHBOARD_ADMIN_PASSWORD_HASH)" ]]; then ADMIN_PASSWORD=$(rand_b64 18) fi if [[ ${#GENERATED[@]} -gt 0 ]]; then fixed "generated: ${GENERATED[*]}" fi ok "admin email: ${ADMIN_EMAIL}" ok "public URL: ${PUBLIC_URL}" # Interpolation is checked HERE, before the image pull, because `compose pull` also # interpolates: with a blank required value it fails inside the pull, and the failure # looks exactly like a registry problem. That is what happened on the first clean-host # install -- the installer blamed GHCR and told the operator to go make the packages # public, while the real fault was an unset NUCLEUS_DB_PASSWORD. An error that sends # someone to fix the wrong system costs more than no error at all. # # Nothing in the compose file needs the admin hash, so this is checkable now; the hash # is written after the pull and re-validated below. if ! CONFIG_ERR=$(compose config -q 2>&1); then warn "deploy/.env does not satisfy ${COMPOSE_FILE}" printf '%s\n' "$CONFIG_ERR" | sed 's/^/ /' printf '\n' printf '%s\n' \ " This is a configuration fault, NOT a registry or network problem." \ " A value the compose file requires is missing from deploy/.env." \ "" \ " Check deploy/.env for the key named above. If it is present but blank," \ " delete the line and re-run this installer -- blank values are generated," \ " existing ones are never overwritten." die "docker compose config rejected deploy/.env" fi ok "deploy/.env satisfies ${COMPOSE_FILE} (docker compose config)" # ══════════════════════════════════════════════════════════════════════ # 6. Images # ══════════════════════════════════════════════════════════════════════ step "Images" if [[ "$NO_BUILD" == 1 ]]; then info "--no-build: skipping" elif [[ "$BUILD_FROM_SOURCE" == 1 ]]; then # The escape hatch: no GHCR reachability, an air-gapped host, or local changes. # nginx first -- it is the one most likely to fail for a reason unrelated to the # code, and it is fast. Then the rest; the backend is needed before the admin hash. info "--build: compiling from source (Python wheels + a Next.js production build)" info "this is the slow step; pulling prebuilt images instead is the default" compose build --quiet nginx ok "nginx image (config baked with 644 -- see deploy/nginx/Dockerfile)" compose build --quiet backend ok "backend image" compose build --quiet frontend ok "frontend image" # NOT IN HOSTED. The overlay puts the runner behind a profile so it never starts, and # `compose build runner` names the service explicitly, so the profile does not exclude # it -- a hosted install was pulling the ~1GB ghcr.io/actions/actions-runner base and # compiling an image it will never run. On a from-source install that is the longest # single step of the whole run. # # Measured in tests/e2e/hosted_smoke_e2e.sh, where it was also the slowest thing in the # suite by a wide margin: the Docker-in-Docker host uses the vfs storage driver, which # copies every layer rather than sharing it, and that one base image took the container # past 32GB. if hosted_mode; then info "skipping the runner image: HOSTED withholds the runner, so it is never run" else compose build --quiet runner ok "runner image (self-hosted GitHub Actions runner; idle until a repo is connected)" fi else # The default, and the reason a first install is minutes rather than most of an hour: # download five prebuilt images instead of compiling them. It also takes the build # toolchain out of the list of things that can fail on a stranger's machine. info "pulling prebuilt images (ghcr.io/harshit8588h/devolyn-*:${GUARD_VERSION})" if compose pull --quiet 2>/dev/null || compose pull; then ok "images pulled at ${GUARD_VERSION} (pinned, so this install is reproducible)" else # Reaching here now means the PULL failed, not that .env is malformed: # `compose config` was checked in step 5, so interpolation is already known good. # Without that ordering this message blamed GHCR for a missing secret and sent the # operator off to change package visibility that was never the problem. warn "could not pull from ghcr.io" printf '%s\n' \ " deploy/.env already passed \`docker compose config\`, so this is the" \ " registry or the network -- not a configuration fault." \ "" \ " Likely one of:" \ " - this host cannot reach ghcr.io (proxy/firewall/DNS)" \ " - version ${GUARD_VERSION} was never pushed" \ " - the packages are PRIVATE (they are public today; check only if the" \ " error above says denied or unauthorized:" \ " https://github.com/users/Harshit8588h/packages)" \ "" \ " To build from source instead, re-run with: --build" die "image pull failed" fi fi if [[ -n "$ADMIN_PASSWORD" ]]; then # scrypt hash by the app's own hash_password(). Compose interpolates `$` in .env, so every # `$` in the hash is doubled -- forgetting this is a login that silently fails. # # The image is named explicitly rather than relying on a local `:latest` tag, which # stopped existing when the stack moved to pulled images. The hash is computed on THIS # machine: the password never leaves it, and only the hash is written to .env. BACKEND_IMAGE="ghcr.io/harshit8588h/devolyn-backend:${GUARD_VERSION}" HASH=$(printf '%s' "$ADMIN_PASSWORD" | docker run --rm -i --entrypoint python "$BACKEND_IMAGE" \ -c "import sys; from nucleus_guard.dashboard.credentials import hash_password; print(hash_password(sys.stdin.read()))" \ | tr -d '\n' | sed 's/[$]/$$/g') [[ "$HASH" == scrypt* ]] || die "admin password hashing failed (got: ${HASH:0:40})" env_set NUCLEUS_DASHBOARD_ADMIN_PASSWORD_HASH "$HASH" fixed "admin password generated and hashed" fi # Nothing blank that the stack requires. The compose file's `:?` guards catch the ones it # interpolates; the app's own REQUIRED values are checked here so the failure is a line in # this output rather than a backend in a restart loop. for key in POSTGRES_SUPERUSER_PASSWORD NUCLEUS_DB_PASSWORD NUCLEUS_DB_MIGRATION_PASSWORD \ NUCLEUS_SECURITY_SECRET_KEY NUCLEUS_AUDIT_EXPORT_TOKEN \ NUCLEUS_GITHUB_ENCRYPTION_KEY NUCLEUS_GITHUB_RUNNER_TOKEN \ NUCLEUS_DASHBOARD_ADMIN_EMAIL NUCLEUS_DASHBOARD_ADMIN_PASSWORD_HASH; do [[ -n "$(env_get "$key")" ]] || die "${key} is blank in deploy/.env after generation -- this should not happen; please report it" done compose config -q || die "docker compose config rejected deploy/.env" ok "deploy/.env validated (docker compose config)" # ══════════════════════════════════════════════════════════════════════ # 7. Database roles # ══════════════════════════════════════════════════════════════════════ step "Database" # wait_for SERVICE MODE TIMEOUT : MODE is 'healthy', 'exited0' or 'running'. container_state() { # -> "status health exitcode" for a compose service, or "absent none 0". local id # Captured, then the first line read out. `| head -n1` would let compose die of # SIGPIPE, which pipefail turns into a failure -- reporting a container that # exists as absent. local ids; ids=$(compose ps -q -a "$1" 2>/dev/null || true) read -r id <<<"$ids" || true [[ -n "$id" ]] || { printf 'absent none 0'; return; } docker inspect --format '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}} {{.State.ExitCode}}' "$id" } explain_failure() { local svc="$1" printf '\n%s--- last 40 lines of %s ---%s\n' "$C_DIM" "$svc" "$C_RST" >&2 compose logs --no-color --tail 40 "$svc" >&2 || true printf '%s--- end ---%s\n' "$C_DIM" "$C_RST" >&2 case "$svc" in postgres) warn "postgres: a stale volume with a different superuser password? 'docker volume rm nucleus_postgres_data_prod' DESTROYS DATA -- back up first" ;; migrator) warn "migrator: usually a role/password mismatch between deploy/.env and the database. Re-running this installer repairs the roles" ;; backend) warn "backend: a REQUIRED value in deploy/.env is missing or wrong; the log above names it" ;; frontend) warn "frontend: the Next.js server did not come up; the log above has the reason" ;; worker) warn "worker: it reads the same deploy/.env as the backend; the log above names what it could not reach" ;; nginx) warn "nginx: ports 80/443 already in use on this host? 'ss -ltnp | grep -E \":(80|443) \"'" ;; runner) warn "runner: needs NUCLEUS_GITHUB_RUNNER_TOKEN and a reachable backend; the log above says which" ;; esac } wait_for() { local svc="$1" mode="$2" timeout="$3" start now st status health code last="" start=$(date +%s) while :; do st=$(container_state "$svc"); read -r status health code <<<"$st" case "$mode" in healthy) [[ "$health" == healthy ]] && return 0 ;; exited0) [[ "$status" == exited && "$code" == 0 ]] && return 0 ;; # For a service with no healthcheck. Weaker than 'healthy', and honest about it: it # proves the process started, not that it is doing anything useful. running) [[ "$status" == running ]] && return 0 ;; esac # Hard failures: don't sit out the timeout on something that has already died. if [[ "$status" == exited && "$code" != 0 && "$mode" != exited0 ]]; then explain_failure "$svc"; die "${svc} exited with code ${code}" fi if [[ "$mode" == exited0 && "$status" == exited && "$code" != 0 ]]; then # migrator restarts on failure; give it a couple of attempts before calling it. now=$(date +%s); (( now - start > 90 )) && { explain_failure "$svc"; die "${svc} keeps failing (exit ${code})"; } fi now=$(date +%s) if (( now - start > timeout )); then explain_failure "$svc"; die "${svc} not ${mode} after ${timeout}s"; fi if [[ "$status $health" != "$last" ]]; then info "${svc}: ${status}${health:+ / $health}"; last="$status $health"; fi sleep 3 done } compose up -d --quiet-pull postgres redis >/dev/null 2>&1 || compose up -d postgres redis >/dev/null 2>&1 || true wait_for postgres healthy 180 wait_for redis healthy 60 ok "postgres and redis healthy" # The init script in docker/init runs only on an EMPTY volume, and only if the bind mount # delivered it runnable. Make the roles true regardless. Everything here is idempotent and # it also repairs a password that drifted between deploy/.env and the database. PG_DB=$(env_get NUCLEUS_DB_DATABASE); PG_DB="${PG_DB:-nucleus_guard}" ROLE_SQL=$(cat <<'SQL' DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'nucleus_migrator') THEN CREATE ROLE nucleus_migrator LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS; END IF; IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'nucleus_app') THEN CREATE ROLE nucleus_app LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS; END IF; END $$; ALTER ROLE nucleus_migrator WITH LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS PASSWORD :'migrator_pw'; ALTER ROLE nucleus_app WITH LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS PASSWORD :'app_pw'; ALTER SCHEMA public OWNER TO nucleus_migrator; REVOKE CREATE ON SCHEMA public FROM PUBLIC; REVOKE ALL ON SCHEMA public FROM nucleus_app; GRANT USAGE ON SCHEMA public TO nucleus_app; GRANT CONNECT ON DATABASE :"dbname" TO nucleus_migrator; GRANT CONNECT ON DATABASE :"dbname" TO nucleus_app; SQL ) # `/dev/null 2>&1 || true fi done } # The migrator is a one-shot: `up` re-runs it when it has exited, which is what we want on # every run -- alembic is a no-op, the grants are re-applied, the append-only proof re-runs. compose up -d --quiet-pull migrator >/dev/null 2>&1 || compose up -d migrator >/dev/null 2>&1 || true wait_for migrator exited0 300 ok "migrations applied, grants applied, audit log verified append-only" recreate_failed backend compose up -d --no-deps backend >/dev/null 2>&1 || true wait_for backend healthy "$HEALTH_TIMEOUT"; ok "backend healthy" recreate_failed frontend nginx runner worker compose up -d --quiet-pull >/dev/null 2>&1 || compose up -d >/dev/null 2>&1 || true # The worker does every verification and index build (0.6.4). A stack whose API answers # but whose worker is down accepts pull requests and never checks them, so it is waited # for like the backend rather than assumed. wait_for worker healthy 180; ok "worker healthy" wait_for frontend healthy 180; ok "frontend healthy" wait_for nginx healthy 120; ok "nginx healthy" # The runner, whose EXPECTED STATE depends on the mode -- and getting that backwards is # what made a HOSTED install abort here. # # In HOSTED the overlay withholds the runner, so there is nothing to wait for and waiting # anyway fails: `runner: absent / none` for 120 seconds, then "runner not running after # 120s", on a server where every other service was healthy and absent was the correct # answer. Steps 9 and 10 never ran. # # So the expectation is inverted rather than skipped. Absent is the requirement, and a # runner that IS there is the error -- the opposite of SINGLE, where its absence is. if hosted_mode; then # Removed in step 5, before anything came up. Re-checked here because this is after the # final `up`, which is the moment a mistake in the overlay would show. withdraw_runner if [[ -n "$(runner_container_ids)" ]]; then die "a runner container is present on a HOSTED server. The overlay should have withheld it; something started one anyway, and it executes customer code." fi ok "runner absent, as HOSTED requires" else # No healthcheck: it is a client, not a server, so "the process is up" is the only thing # compose can report. Whether it is SERVING is a question only Guard can answer, which # is why the supervisor reports a heartbeat per repository and `devolyn status` shows it. wait_for runner running 120; ok "runner up (idle until a repo is connected)" fi # ══════════════════════════════════════════════════════════════════════ # 9. Verify # ══════════════════════════════════════════════════════════════════════ step "Verify" READY="" for _ in $(seq 1 20); do READY=$(curl -sk --max-time 5 https://127.0.0.1/health/ready 2>/dev/null || true) [[ "$READY" == *'"status":"healthy"'* ]] && break sleep 3 done [[ "$READY" == *'"status":"healthy"'* ]] || { explain_failure nginx; die "/health/ready is not healthy through nginx: ${READY:-no response}"; } SCHEMA=$(printf '%s' "$READY" | sed -n 's/.*"schema_version":"\([^"]*\)".*/\1/p') # A HOSTED server states no schema on this public route (audit finding F17), so there is # nothing to print: "schema ?" read as a fault (0.7). ok "GET /health/ready -> healthy${SCHEMA:+ (schema ${SCHEMA})} via https://127.0.0.1" # ── the admin password has to reach the DATABASE, not just deploy/.env ──────── # # Writing the env hash (step 6) is enough on a FRESH install: the table is empty, so # the backend's bootstrap_admin copies it in at startup. On an install that already # has accounts, bootstrap_admin returns immediately -- by design, so a boot cannot # clobber a password changed through the dashboard -- and the env value is then read # by nothing a login ever touches. # # So `devolyn reset-admin-password` printed a new password, said it had reset it, and # the dashboard kept accepting only the old one. Silently. To somebody who ran it # BECAUSE they were locked out. # # This runs here, after the stack is verified healthy, for two reasons: the write needs # a reachable database, and the summary must not print a password that is not yet # valid. If this fails the installer stops, and the operator's old password still # works -- a failed reset that changes nothing is recoverable, a printed password that # does not work is not. # THE AUTHORITATIVE EMAIL CHECK, with the real validator rather than a shell # approximation of it. # # The pre-filter earlier only decides whether a DEFAULT can be guessed. An address the # operator passed with --admin-email, or one already in the env file from an older # install, has had nothing but `[[ -n ]]` applied to it -- and an address the sign-in # form refuses produces an admin account that exists and cannot be used. # # Run in the image, because that is where `email_validator` lives and where the login # route's own EmailStr resolves. A shell regex here would be a second validator that # drifts from the first, which is the bug one layer down rather than a fix for it. ADMIN_EMAIL_NOW=$(env_get NUCLEUS_DASHBOARD_ADMIN_EMAIL) if [[ -n "$ADMIN_EMAIL_NOW" ]]; then # The program in a variable so the call below fits one line WITH its `&1); then die "the admin address in .env cannot be used. $(printf '%s' "$EMAIL_OUT" | head -3) Fix it with ${C_BOLD}--admin-email you@your-domain.example${C_RST} and re-run; every step is idempotent. Nothing has been written to the database yet." fi ok "admin email accepted by the same validator the sign-in form uses" fi if [[ -n "$ADMIN_PASSWORD" ]]; then # Through the app's own service layer, so the hash format, the password policy, the # session revocation and the audit entry keep their single definitions. On stdin, so # the plaintext never appears in argv, `ps`, or `docker inspect`. if RESET_OUT=$(printf '%s' "$ADMIN_PASSWORD" \ | compose run --rm --no-deps -T backend \ python scripts/reset_admin_password.py --email "$ADMIN_EMAIL_NOW" 2>&1); then # `head -1` and the newline strip are both load-bearing: RESET_OUT carries the # script's stdout AND stderr, more than one line can match, and a multi-line value # spliced into the message below breaks it across lines mid-sentence. REVOKED=$(printf '%s' "$RESET_OUT" \ | sed -n 's/.*sessions_revoked=\([0-9][0-9]*\).*/\1/p' | head -1 | tr -d '\r\n') ok "admin password set in the database (${REVOKED:-0} session(s) revoked)" ADMIN_PASSWORD_LIVE=1 elif [[ "$RESET_OUT" == *"No such file or directory"* ]]; then # The image predates this script. Only reachable if someone points a new installer # at an old pinned image, which the version ratchet already refuses -- but saying # so beats a stack trace. warn "this backend image has no scripts/reset_admin_password.py" printf '%s\n' \ " The image pinned in deploy/.env predates the database-side reset." \ " Run \`devolyn update\` first, then reset the password again." die "cannot set the admin password in the database with image ${BACKEND_IMAGE:-}" else warn "could not set the admin password in the database" printf '%s\n' "$RESET_OUT" | sed 's/^/ /' printf '%s\n' \ "" \ " Nothing was changed: your existing password still works." \ " deploy/.env was updated, but on an installation that already has accounts" \ " that value is not what the dashboard checks -- so the password below would" \ " not have worked, and it is deliberately not printed." die "admin password reset failed" fi fi # The operator CLI. Same repo, so `devolyn update` can find itself. # # Two names, one file. `devolyn` is the command; `nucleus-guard` is kept as an alias so # that an existing deployment's scripts, cron entries and runbooks keep working across # this rename. `ln -sf` also repoints an old alias that still points at the pre-rename # deploy/nucleus-guard path, which `git pull` has just deleted -- without that, upgrading # would leave a dangling symlink and the operator with no CLI at all. if [[ -f "$INSTALL_DIR/deploy/devolyn" ]]; then chmod +x "$INSTALL_DIR/deploy/devolyn" ln -sf "$INSTALL_DIR/deploy/devolyn" /usr/local/bin/devolyn ln -sf "$INSTALL_DIR/deploy/devolyn" /usr/local/bin/nucleus-guard ok "installed CLI: devolyn (onboard, org create, status, logs, restart, reset-admin-password, update)" ok "kept alias: nucleus-guard -> devolyn (existing scripts keep working)" fi # ══════════════════════════════════════════════════════════════════════ # 10. Summary # ══════════════════════════════════════════════════════════════════════ ELAPSED=$(( $(date +%s) - T0 )) cat <