feat(deploy): T399695 - Initial Deploy config/setup wizard (Web and CLI)

.eslintrc.json

@@ -10,6 +10,8 @@
 		"**/results/result.json",
 		"!.github/**/**",
 		"deploy/config/extensions",
+		"deploy/setup/letsencrypt",
+		"deploy/setup/certs",
 		"cloud-init.yml",
 		"package-lock.json",
 		"pnpm/**/**",

deploy/.gitignore

@@ -0,0 +1 @@
+docker-compose.local.yml

deploy/README.md

@@ -42,11 +42,30 @@ You need two DNS records that resolve to your machine's IP address:
 - Wikibase, e.g., "wikibase.example"
 - QueryService, e.g., "query.wikibase.example"
 
-## Setup
+## Installation
+
+### Option 1: Web-based Setup (Recommended for New Users)
+
+If you're setting up a new instance on a fresh VPS, you can use our web-based installer to simplify the process. This method installs all required dependencies, configures your environment, and launches the full Wikibase Suite via a browser-based setup wizard.
+
+1. **Log in to your VPS as root.**
+2. **Run the following one-liner:**
+
+   ```sh
+   curl -fsSL https://raw.githubusercontent.com/wmde/wikibase-release-pipeline/refs/heads/deploy-setup-script/deploy/setup/start.sh | bash
+   ```
+
+3. **Follow the on-screen instructions.** The setup script will guide you through the rest of the process and provide a link to open the web-based installer in your browser.
+
+Once setup is complete, the installer shuts down automatically and your Wikibase Suite instance will be up and running.
+
+> 💡 This method takes care of installing Docker, Docker Compose, Git, and configuring everything correctly, making it ideal for first-time deployments.
 
 > 💡 If you want to run a quick test on a machine that has no public IP address (such as your local machine), check our [FAQ entry](#can-i-host-wbs-deploy-locally) below.
 
-### Download WBS Deploy
+### Option 2: Manually Setup
+
+#### Download WBS Deploy
 
 Check out the files from Github, move to the subdirectory `deploy`.
 
@@ -55,7 +74,7 @@ git clone https://github.com/wmde/wikibase-release-pipeline
 cd wikibase-release-pipeline/deploy
 ```
 
-### Initial configuration
+#### Configuration
 
 Make a copy of the [configuration template](./template.env) in the `wikibase-release-pipeline/deploy` directory.
 
@@ -65,7 +84,7 @@ cp template.env .env
 
 Follow the instructions in the comments in your newly created `.env` file to set domain names, usernames and passwords.
 
-### Starting
+#### Starting
 
 Run the following command from within `wikibase-release-pipeline/deploy`:
 
@@ -79,6 +98,8 @@ The first start can take a couple of minutes. You can check the status of the st
 
 > 💡 If anything goes wrong, you can run `docker logs <CONTAINER_NAME>` to see some helpful error messages.
 
+## Operating Deploy
+
 ### Stopping
 
 To stop, use
@@ -89,7 +110,7 @@ docker compose stop
 
 ### Resetting the configuration
 
-Most values set in `.env` are written into the respective containers after you run `docker compose up` for the first time.
+Most values set in `.env` are written into the respective containers after you run `docker compose up` for the first time, but will not reflect changes in the containers afterwards without resetting your configuration.
 
 If you want to reset the configuration while retaining your existing data:
 

deploy/setup/README.md

@@ -0,0 +1,60 @@
+# Wikibase Suite Deploy – Setup Script
+
+This script bootstraps a Wikibase Suite Deploy installation handling or guiding you through all of the following steps:
+
+1. **Check for Git** – Installs Git if it is not already available on the system.  
+2. **Clone the repository** – Downloads the Wikibase Suite Deploy code from the official repository.  
+3. **Check for Docker** – Installs Docker if it is not already available on the system.  
+4. **Prompt for configuration** – Collects all required setup values interactively through a web interface.  
+5. **Launch deployment** – Starts the deployment process once configuration is complete and notifies you once your new Suite instance is available.
+
+## Installation
+
+1. Setup on a new VPS instance that meets the following criteria:
+
+  - Meets minimum hardware requirements (see https://github.com/wmde/wikibase-release-pipeline/tree/main/deploy#requirements)
+  - Is running one of these officially supported Linux distributions: Ubuntu (22, 24), Debian (11, 12), Fedora, and CentOS
+  - You have root level SSH access to the instance
+
+2. SSH as root into your new VPS instance and enter the following, following instructions from there:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/wmde/wikibase-release-pipeline/refs/heads/deploy-setup-script/deploy/setup/start.sh | bash
+```
+
+Alternatively, if you already have cloned the repository you can run do start setup running the following commands:
+
+```bash
+cd deploy/setup
+./start.sh --skip-clone
+```
+
+## CLI Options
+
+`start.sh` also has some CLI options available for special cases, debugging, and development:
+
+| Option           | Description |
+|------------------|-------------|
+| `--debug`        | Enable verbose/debug logging for troubleshooting. |
+| `--skip-clone`   | Skip cloning the repository (use an existing checkout). |
+| `--skip-deps`    | Skip dependency installation (assumes Git & Docker are already installed). |
+| `--skip-launch`  | Do not launch services after configuration completes. |
+
+### Dev-only
+
+| Option           | Description |
+|------------------|-------------|
+| `--dev`          | Development mode: skips clone, dependency installs, and launch; uses a relative repo path for local development. |
+| `--local`        | Mark this run as local which launches setup on localhost:8888 and runs the interactive instead of as a background process. Useful only for dev/testing at this stage.|
+
+These options can be applied using the following command formats:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/wmde/wikibase-release-pipeline/refs/heads/deploy-setup-script/deploy/setup/start.sh | bash -s -- [OPTIONS]
+```
+
+Or, from within the deploy/setup directory of an already cloned repository:
+
+```bash
+./setup [OPTIONS]
+```

deploy/setup/scripts/_logging.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# Clean stdout, structured log:
+# - stdout: no timestamps / no [LEVEL]
+# - log   : ISO8601 timestamp + [LEVEL]
+# -----------------------------------------------------------------------------
+
+export LOG_PATH=${LOG_PATH:=/tmp/wbs-deploy-setup.log}
+
+DEBUG=${DEBUG:=false}
+
+# Are we attached to a terminal?
+INTERACTIVE=false
+[ -t 1 ] && INTERACTIVE=true
+
+_timestamp() { date -u +"%FT%TZ"; }
+
+# --- one-shot init that rotates the previous file and starts clean -----------
+log_init() {
+  if [ "${WBS_LOG_INITIALIZED:-}" = "1" ]; then
+    return
+  fi
+  export WBS_LOG_INITIALIZED=1
+
+  mkdir -p "$(dirname "$LOG_PATH")" 2>/dev/null || true
+
+  if [ -f "$LOG_PATH" ] && [ -s "$LOG_PATH" ]; then
+    ts=$(date -u +"%Y%m%d-%H%M%S")
+    backup="${LOG_PATH}.${ts}"
+    # Prefer mv; fall back to cp if moving across devices fails
+    mv -- "$LOG_PATH" "$backup" 2>/dev/null || {
+      cp --preserve=mode,timestamps -- "$LOG_PATH" "$backup" 2>/dev/null || true
+      touch "$LOG_PATH"
+    }
+  fi
+  touch "$LOG_PATH"
+}
+
+# run init immediately
+log_init
+
+# status "Message..."
+# - stdout: "Message..."
+# - log   : "2025-08-12T10:00:00Z [status] Message..."
+status() {
+  printf '%s [status] %s\n' "$(_timestamp)" "$*" >> "$LOG_PATH"
+  if $INTERACTIVE; then
+    printf '%s\n' "$*"
+  fi
+}
+
+# debug "Message..."
+# - stdout: shown only if DEBUG=true (clean)
+# - log   : "2025-08-12T10:00:00Z [debug] Message..."
+debug() {
+  printf '%s [debug] %s\n' "$(_timestamp)" "$*" >> "$LOG_PATH"
+  if [ "$DEBUG" = true ]; then
+    printf '%s\n' "$*"
+  fi
+}
+
+# run "command string"
+# Always logs. Mirrors to stdout only if INTERACTIVE && DEBUG.
+# Log format:
+#   2025-... [debug] $ command string
+#   <raw command output...>
+run() {
+  local cmd="$*"
+  printf '%s [debug] $ %s\n' "$(_timestamp)" "BEGIN RUN: $cmd" >> "$LOG_PATH"
+
+  if $INTERACTIVE && [ "$DEBUG" = true ]; then
+    # output to screen and log
+    bash -c "$cmd" 2>&1 | tee -a "$LOG_PATH"
+  else
+    # log only
+    bash -c "$cmd" >>"$LOG_PATH" 2>&1
+  fi
+  printf '%s [debug] $ %s\n' "$(_timestamp)" "END RUN" >> "$LOG_PATH"
+}

deploy/setup/scripts/install-docker.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# --- Expected Variables ---
+
+export SCRIPTS_DIR
+
+# --- Bootstrap Logging ---
+
+# shellcheck disable=SC1091
+source "$SCRIPTS_DIR/_logging.sh"
+
+# --- Main Script ---
+
+debug "Checking for Docker..."
+
+if command -v docker >/dev/null 2>&1; then
+  exit 0
+fi
+
+debug "Installing Docker..."
+
+if command -v apt-get >/dev/null 2>&1; then
+  # Debian/Ubuntu: install Docker from official Docker APT repo for consistent versioning
+
+  # Detect OS and codename
+  OS_ID="$(. /etc/os-release 2>/dev/null; echo "${ID:-debian}")"
+  CODENAME="$(. /etc/os-release 2>/dev/null; echo "${VERSION_CODENAME:-}")"
+  if [ -z "$CODENAME" ] && command -v lsb_release >/dev/null 2>&1; then
+    CODENAME="$(lsb_release -cs 2>/dev/null || true)"
+  fi
+  if [ -z "$CODENAME" ]; then
+    echo "❌ Could not determine distro codename" >&2
+    exit 1
+  fi
+
+  run "echo 'Using Docker APT repo for $OS_ID ($CODENAME)'"
+  run "apt-get update -y"
+  run "apt-get install -y --no-install-recommends ca-certificates curl gnupg"
+  run "install -m 0755 -d /etc/apt/keyrings"
+  run "curl -fsSL https://download.docker.com/linux/$OS_ID/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg"
+  run "apt-get remove -y docker.io docker-compose docker-compose-v2 2>/dev/null || true"
+  run "echo \"deb [arch=\$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/$OS_ID $CODENAME stable\" | tee /etc/apt/sources.list.d/docker.list >/dev/null"
+  run "apt-get update -y"
+  run "apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin"
+elif command -v dnf >/dev/null 2>&1; then
+  # Distinguish Fedora vs RHEL-family (CentOS Stream, RHEL, Rocky, Alma)
+  OS_ID="$(. /etc/os-release 2>/dev/null; echo "${ID:-}")"
+
+  if [ "$OS_ID" = "fedora" ]; then
+    # Fedora: use Fedora-maintained Moby packages
+    run "dnf -y install moby-engine moby-cli docker-compose-plugin docker-buildx-plugin"
+  else
+    # RHEL-family (CentOS Stream / RHEL / Rocky / Alma): use Docker's official repo
+    run "dnf -y install dnf-plugins-core"
+    run "dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo"
+    run "dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin || \
+         (echo '❌ Docker CE packages not available for this release yet.' >&2; exit 1)"
+  fi
+else
+  status "⚠️ Unsupported package manager. Please install Docker manually."
+  exit 1
+fi
+
+debug "Enabling and starting Docker..."
+run "systemctl enable --now docker"
+status "Docker installation complete."
+run "docker --version" || true
+run "docker compose version" || true

deploy/setup/scripts/launch.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# --- Expected Variables ---
+
+export DEBUG
+export LOCALHOST
+export LOG_PATH
+export DEPLOY_DIR
+export ENV_FILE_PATH
+export SCRIPTS_DIR
+export SETUP_DIR
+export RESET
+
+# --- Bootstrap Logging ---
+
+# shellcheck disable=SC1091
+source "$SCRIPTS_DIR/_logging.sh"
+
+# --- Functions ---
+
+wait_for_env_file() {
+  until [ -s "$ENV_FILE_PATH" ]; do sleep 2; done
+  debug "Configuration saved."
+}
+
+launch_deploy() {
+  pushd "$DEPLOY_DIR" >/dev/null || return 1
+
+  local compose_opts=()
+  local compose_up_opts=(-d)
+
+  if [ -f "docker-compose.local.yml" ]; then
+    compose_opts+=(-f docker-compose.yml -f docker-compose.local.yml)
+  fi
+
+  if ! $DEBUG ; then
+    compose_up_opts+=(--quiet-pull);
+  fi
+
+  if $RESET; then
+    status "Removing config/LocalSettings.php (RESET=true)"
+    run "rm -f config/LocalSettings.php"
+
+    status "Taking down any existing wbs-deploy services and data (RESET=true)"
+    run "docker compose ${compose_opts[*]} down --volumes"
+  fi
+
+  status "Waiting for services to start. Generally takes 2–6 minutes..."
+
+  run "docker compose ${compose_opts[*]} up ${compose_up_opts[*]}"
+
+  popd >/dev/null || return 1
+}
+
+# NOTE: final_message intentionally uses echo+tee for a clean human banner on stdout.
+# The block is also appended to the log via tee, but WITHOUT timestamps/levels.
+final_message() {
+  {
+    echo
+    echo "✅ Setup is Complete!"
+    echo
+    if [[ -f "$ENV_FILE_PATH" ]]; then
+      # shellcheck disable=SC1090
+      source "$ENV_FILE_PATH"
+
+      if [[ -n "${WIKIBASE_PUBLIC_HOST:-}" ]]; then
+        echo "Your Wikibase Suite services can be found at:"
+        echo
+        echo "MediaWiki/Wikibase:"
+        echo "https://$WIKIBASE_PUBLIC_HOST"
+        echo
+        echo "Query Service:"
+        echo "https://${WDQS_PUBLIC_HOST:-query.$WIKIBASE_PUBLIC_HOST}"
+        echo
+        echo "QuickStatements:"
+        echo "https://$WIKIBASE_PUBLIC_HOST/tools/quickstatements"
+        echo
+      else
+        echo "⚠️ Could not determine WIKIBASE_PUBLIC_HOST from .env"
+      fi
+
+      echo
+      echo "The following configuration was saved during setup."
+      echo "Please save these credentials and settings securely:"
+      echo
+      sed 's/^/  /' "$ENV_FILE_PATH"
+      echo
+    else
+      echo "⚠️ .env file not found at $ENV_FILE_PATH"
+      echo
+    fi
+  } | tee -a "$LOG_PATH"
+}
+
+# --- Execution ---
+
+wait_for_env_file
+launch_deploy
+final_message