Add macOS installer script and installation guide

PlumoAI-Installer.command

@@ -0,0 +1,124 @@
+#!/bin/bash
+# PlumoAI Installer for macOS - double-clickable bootstrapper.
+#
+# This is the macOS counterpart to PlumoAISetup.exe on Windows: a Mac user
+# downloads this one file, double-clicks it, and it installs PlumoAI.
+#
+# It fetches the PlumoAI repository (or uses a checkout it is sitting inside),
+# then hands off to install-macos.sh, which checks prerequisites, installs
+# Docker Desktop if needed, and starts the stack.
+#
+# Written for the bash 3.2 that ships with macOS.
+
+# Keep the Terminal window open on exit so double-click users see the result.
+trap 'printf "\n  Press Return to close this window."; read -r _' EXIT
+
+REPO_URL="https://github.com/PlumoAI/plumoai.git"
+# Where to clone when this file is run on its own (override for testing).
+INSTALL_DIR="${PLUMOAI_INSTALL_DIR:-$HOME/PlumoAI}"
+
+# ---------- output ----------
+if [ -t 1 ]; then
+  DIM='\033[0;90m'; RED='\033[0;31m'; GRN='\033[0;32m'
+  MAG='\033[0;35m'; CYN='\033[0;96m'; OFF='\033[0m'
+else
+  DIM=''; RED=''; GRN=''; MAG=''; CYN=''; OFF=''
+fi
+
+printf "\n  %sPlumo%sAi%s\n" "$MAG" "$CYN" "$OFF"
+printf "  %sInstaller for macOS%s\n\n" "$DIM" "$OFF"
+
+die() {
+  printf "\n  %s%s%s\n" "$RED" "$1" "$OFF" >&2
+  [ -n "$2" ] && printf "        %s\n" "$2" >&2
+  exit 1
+}
+
+# ---------- locate install-macos.sh ----------
+# Case 1: this .command was distributed inside a repo checkout, next to the
+# installer script. Use that checkout directly.
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -f "$SELF_DIR/install-macos.sh" ] && [ -f "$SELF_DIR/install.sh" ]; then
+  REPO_DIR="$SELF_DIR"
+  printf "  %s..%s    Using installer next to this file: %s\n" "$DIM" "$OFF" "$REPO_DIR"
+else
+  # Case 2: standalone download. We need git to fetch the repo.
+  if ! command -v git >/dev/null 2>&1; then
+    printf "  %s..%s    Git is required and was not found. Requesting the Command Line Tools...\n" "$DIM" "$OFF"
+    xcode-select --install 2>/dev/null || true
+    die "Git (Xcode Command Line Tools) needs to be installed first." \
+        "A system dialog should have opened. Finish that install, then double-click this file again."
+  fi
+
+  if [ -d "$INSTALL_DIR/.git" ]; then
+    printf "  %s..%s    Updating existing PlumoAI at %s ...\n" "$DIM" "$OFF" "$INSTALL_DIR"
+    git -C "$INSTALL_DIR" pull --ff-only 2>/dev/null || \
+      printf "  %swarn%s  could not fast-forward; using the existing copy as-is\n" "$RED" "$OFF"
+  else
+    printf "  %s..%s    Downloading PlumoAI into %s ...\n" "$DIM" "$OFF" "$INSTALL_DIR"
+    git clone "$REPO_URL" "$INSTALL_DIR" || \
+      die "Download failed." "Check your internet connection and try again."
+  fi
+  REPO_DIR="$INSTALL_DIR"
+fi
+
+# ---------- hand off ----------
+cd "$REPO_DIR" || die "Could not enter $REPO_DIR."
+
+# Runs a command, or just prints it when PLUMOAI_DRY_RUN is set (used by tests).
+run_or_echo() {
+  if [ -n "${PLUMOAI_DRY_RUN:-}" ]; then
+    printf "  %s[dry-run]%s would run: %s\n" "$DIM" "$OFF" "$*"
+    return 0
+  fi
+  "$@"
+}
+
+printf "  %sok%s    Ready. Starting the installer...\n\n" "$GRN" "$OFF"
+printf "  %s----------------------------------------------------------%s\n\n" "$DIM" "$OFF"
+
+if [ -f install-macos.sh ]; then
+  # Preferred path: the full macOS installer (checks prerequisites, installs
+  # Docker Desktop if needed, then runs install.sh).
+  chmod +x install-macos.sh 2>/dev/null || true
+  run_or_echo ./install-macos.sh "$@"
+  status=$?
+else
+  # Fallback: this version of the repo predates install-macos.sh (e.g. it has
+  # not been merged yet). Run install.sh directly, after making sure Docker is
+  # up ourselves, since install.sh does not install Docker.
+  printf "  %s..%s    install-macos.sh not present in this version; using install.sh directly.\n" "$DIM" "$OFF"
+
+  if ! docker info >/dev/null 2>&1; then
+    if [ -d /Applications/Docker.app ]; then
+      printf "  %s..%s    Starting Docker Desktop...\n" "$DIM" "$OFF"
+      open -a Docker 2>/dev/null || true
+      w=0
+      while [ "$w" -lt 120 ]; do
+        docker info >/dev/null 2>&1 && break
+        sleep 3; w=$((w + 3))
+      done
+    fi
+  fi
+
+  if ! docker info >/dev/null 2>&1; then
+    die "Docker Desktop is required and is not running." \
+        "Install it from https://www.docker.com/products/docker-desktop/ then double-click this file again."
+  fi
+
+  [ -f install.sh ] || die "install.sh is missing from the download." "The repository may be incomplete; try again."
+  chmod +x install.sh 2>/dev/null || true
+  run_or_echo ./install.sh "$@"
+  status=$?
+fi
+
+printf "\n  %s----------------------------------------------------------%s\n" "$DIM" "$OFF"
+if [ "$status" -eq 0 ]; then
+  printf "  %sDone.%s PlumoAI is installed in %s\n" "$GRN" "$OFF" "$REPO_DIR"
+else
+  printf "  %sThe installer exited with an error (code %s).%s\n" "$RED" "$status" "$OFF"
+  printf "        The output above shows what happened.\n"
+fi
+
+exit "$status"

docs/install-macos.md

@@ -0,0 +1,200 @@
+# Install PlumoAI on macOS
+
+PlumoAI runs on macOS as a Docker Compose stack, the same containers used on Linux and Windows.
+There is no separate macOS build and no feature difference between platforms.
+
+Three ways to install:
+
+- **[Double-click installer](#double-click-installer)** - download one file, double-click it. Closest to the Windows `PlumoAISetup.exe` experience.
+- **[Quick install](#quick-install)** - one script that checks prerequisites, installs Docker Desktop if needed, and starts the stack.
+- **[Manual install](#manual-install)** - the same steps run by hand.
+
+---
+
+## Requirements
+
+| | |
+|---|---|
+| macOS | 12 (Monterey) or newer |
+| Chip | Apple Silicon or Intel |
+| Docker | Docker Desktop with Compose v2 |
+| Git | Included with the Xcode Command Line Tools |
+| Disk | About 6 GB for images and volumes |
+
+For **domain mode** you also need an `A`/`AAAA` record pointing at the host and inbound ports **80** and **443** open.
+
+---
+
+## Double-click installer
+
+For users who would rather not touch the command line, `PlumoAI-Installer.command` is a double-clickable bootstrapper - the macOS counterpart to `PlumoAISetup.exe` on Windows.
+
+1. Download `PlumoAI-Installer.command` (or the `.zip` containing it, then unzip).
+2. **Right-click it and choose Open** the first time, then confirm. macOS shows a warning for any downloaded, unsigned file; right-click-Open is how you approve it. A plain double-click works on every launch after that.
+3. A Terminal window opens and the install runs. When it finishes, your browser opens at the running instance.
+
+Behind the scenes it downloads PlumoAI into `~/PlumoAI` (or uses a checkout it is sitting inside), then runs `install-macos.sh`. If that script is not present in the version it fetches, it falls back to running `install.sh` directly.
+
+> The one-time warning is expected. Removing it entirely requires an Apple Developer ID to sign and notarize the file, the same way the Windows installer would need a code-signing certificate to avoid SmartScreen.
+
+## Quick install
+
+```bash
+git clone https://github.com/PlumoAI/plumoai.git
+cd plumoai
+chmod +x install-macos.sh
+./install-macos.sh
+```
+
+The script will:
+
+1. Verify the macOS version and that Git is available.
+2. Check for Docker Desktop, and offer to install it through Homebrew if it is missing.
+3. Start Docker Desktop and wait for the daemon to come up.
+4. Confirm Docker Compose v2 is present.
+5. Hand off to `install.sh`, which creates `.env`, generates secrets, and starts the containers.
+6. Open your browser at the running instance.
+
+### Check without changing anything
+
+To see what the installer would do on this machine without installing or starting anything:
+
+```bash
+./install-macos.sh --check
+```
+
+Example output:
+
+```
+  PlumoAi
+  Self-Hosted - macOS installer
+
+  check mode - nothing will be installed or changed
+
+Checking prerequisites
+  ok    macOS 15.2 (arm64)
+  ok    git 2.50.1
+  ok    Homebrew 4.4.0
+  ok    Docker Desktop found
+  ok    Docker daemon is running
+  ok    Docker Compose v2 (2.31.0)
+
+Repository
+  ok    Using existing checkout: /Users/you/plumoai
+
+  This Mac is ready. Run ./install-macos.sh to install.
+```
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--check` | Report prerequisites only. Installs nothing, starts nothing. |
+| `--fresh` | Passed through to `install.sh`: backs up, then resets the MySQL volume. |
+| `--no-backup` | Passed through to `install.sh`: skip the backup that `--fresh` takes first. |
+| `--no-open` | Do not open the browser when the install finishes. |
+| `--help` | Show usage. |
+
+---
+
+## Manual install
+
+If you would rather not use the wrapper, or Docker Desktop is already set up:
+
+### 1. Install Docker Desktop
+
+```bash
+brew install --cask docker
+open -a Docker
+```
+
+Or download it from [docker.com](https://www.docker.com/products/docker-desktop/). Wait for the whale icon in the menu bar to stop animating, then confirm:
+
+```bash
+docker compose version
+```
+
+### 2. Clone
+
+```bash
+git clone https://github.com/PlumoAI/plumoai.git
+cd plumoai
+```
+
+### 3. Optional: configure `.env`
+
+You can skip this. Step 4 creates `.env` from `.env.example` and prompts for the values it needs when run interactively. For production or non-interactive installs, write it in advance.
+
+**Domain mode (recommended for production):**
+
+```ini
+RUN_MODE=domain
+DOMAIN_NAME=self.example.com
+SSL_EMAIL=admin@example.com
+```
+
+**Localhost mode (HTTP):**
+
+```ini
+RUN_MODE=localhost
+LOCALHOST_PORT=7861
+```
+
+### 4. Install and start
+
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+First run pulls images and initialises the databases, which usually takes 5 to 10 minutes.
+
+When it finishes, PlumoAI is at `http://localhost:7861` in localhost mode, or `https://your-domain` in domain mode.
+
+---
+
+## Managing the stack
+
+```bash
+docker compose ps                       # container status
+docker compose logs --tail 200 -f       # follow logs
+docker compose stop                     # stop, keep data
+docker compose start                    # start again
+docker compose down                     # stop and remove containers, keep volumes
+```
+
+Reset the database and start over, taking a backup first:
+
+```bash
+./install.sh --fresh
+```
+
+---
+
+## Troubleshooting
+
+**`Cannot connect to the Docker daemon`**
+Docker Desktop is installed but not running. Start it with `open -a Docker` and wait for the menu bar icon to settle, then re-run.
+
+**`Docker Compose not found`**
+Docker Desktop bundles Compose v2. If `docker compose version` fails, update Docker Desktop to a current release.
+
+**Port 7861 already in use**
+Something else holds the port. Find it with `lsof -i :7861`, then either stop that process or set a different `LOCALHOST_PORT` in `.env`.
+
+**Docker Desktop asks for a password on first launch**
+Expected. It installs a privileged helper the first time it runs. Complete that prompt before re-running the installer.
+
+**Apple Silicon image warnings**
+Some images may pull an `amd64` build and run under Rosetta emulation. It works, but it is slower. Nothing needs changing.
+
+**Installer says macOS is not supported**
+The script requires macOS 12 or newer, because that is Docker Desktop's own minimum. Check with `sw_vers -productVersion`.
+
+---
+
+## Related
+
+- [Linux install](install-linux.md)
+- [Windows install](install-windows.md)
+- [Architecture](architecture.md)