Skip to main content

One-click install

The fastest way to a running AiSOC dashboard, with zero assumed prerequisites, is the bootstrap installer. It works against a freshly-imaged machine — no Docker, Node, pnpm, git, or even Homebrew required up front. It detects your OS, installs everything idempotently, clones the repo, starts the CORE stack, creates the first administrator, and then pushes one real event through the pipeline to prove the deployment works.

If you already have Docker + Node + pnpm and you want to run the same three commands yourself, see the Quick start. If you are deploying to production, see Deployment options.

TL;DR​

# Linux + macOS (one-liner):
curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh | bash

# Windows (PowerShell, as your normal user — winget elevates per package):
iwr -useb https://raw.githubusercontent.com/beenuar/AiSOC/main/install.ps1 | iex

When the installer finishes, the CORE stack is running at http://localhost:3000, an administrator exists whose generated password was printed once during the run, and one real event has been pushed through the pipeline and read back out of the API as an alert.

Requirements​

What CORE (make up) actually needs, and what each figure was measured against rather than estimated from.

COREWhy
Docker memory8 GBSteady-state RSS across the sixteen CORE containers is well under this. The headroom is for the bundled local model, whose process grows to roughly the model size (~2 GB) while a request is in flight.
Docker disk20 GBImages plus the ~2 GB model plus room for Kafka, Postgres and Qdrant volumes to grow. Below roughly 2 GB free, Kafka corrupts its log directory and still passes its healthcheck — make doctor fails on this before it can happen.
python33.9+make up runs scripts/ensure_env.py on the host to create .env and generate its secrets, and make smoke — the headline proof — is a host-side Python script. CI runs 3.11.
bashanyEvery script under scripts/ has a bash shebang. macOS's bundled 3.2 is sufficient.
docker composev2The v1 docker-compose binary is not supported; profiles and service_completed_successfully both need v2.

make up-full adds ClickHouse, Neo4j, OpenSearch and the enrichment and connector services, and wants ~12 GB of memory.

None of this needs a credential. There is no account to create, no API key to obtain, and no paid service in the default path.

The six most common failures​

SymptomCauseFix
port is already allocatedSomething else on 5432/6379/9092/3000make doctor names the process or container holding it; stop it, or change the host port
Kafka reports healthy but nothing flowsDocker VM out of disk — Kafka corrupts its log dir and its healthcheck still passesdocker system prune -af, then make clean && make up
make smoke fails at "became an alert"fusion is down or not consumingdocker compose logs fusion | tail -60
Console loads but is emptyNo data yet — this is correctmake smoke, or make demo
Services restart-loop on 8 GB machinesNot enough memory for fullUse make up (CORE)
credential vault unavailable on saving a connectorAISOC_CREDENTIAL_KEY in .env is set to something that is not a valid Fernet keymake env generates a real one, then docker compose up -d api

Supported platforms​

OSPackage managerTested versions
Ubuntu / Debianapt22.04, 24.04, Debian 12
Fedora / RHEL / Rocky / AlmadnfFedora 39+, RHEL 9, Rocky 9, Alma 9
Arch / Manjaropacmanrolling
openSUSE Leap / Tumbleweedzypper15.5+, Tumbleweed
Alpineapk3.19+
macOSbrew (auto-installed)13 Ventura, 14 Sonoma, 15 Sequoia (Apple Silicon + Intel)
Windows 10 / 11wingetPro, Home, Enterprise

The installer auto-detects the OS and picks the correct package manager. Re-running is safe: every step is idempotent and short-circuits if the target component is already installed at a sufficient version.

What gets installed​

Linux + macOS (install.sh)​

  1. git — required to clone the repo. Skipped if already on PATH.
  2. Docker Engine + Docker Compose v2 (Linux) or Docker Desktop (macOS via Homebrew cask). On Linux the script enables and starts the docker service, then adds the invoking user to the docker group with a one-shot sg docker -c … so you don't have to log out and back in for the same install run.
  3. Node.js 22 LTS via the official NodeSource APT repo, the Fedora NodeJS module, the relevant native package on Arch / openSUSE / Alpine, or brew install node@22 on macOS.
  4. pnpm 8+ via corepack enable && corepack prepare pnpm@latest.
  5. Homebrew (macOS only) — bootstrapped non-interactively if it isn't already installed.
  6. The AiSOC repo itself — cloned to $HOME/aisoc (override with AISOC_DIR=/path/to/clone). On a re-run the installer does git fetch && git pull instead.
  7. pnpm install --frozen-lockfile at the repo root to materialise the workspace.
  8. make up — checks the ports, brings up the CORE stack from the root docker-compose.yml, waits for every container to report healthy, and creates the first administrator, printing its generated password once.
  9. make smoke — posts one real event to the ingest API and follows it through Kafka, detection, correlation and Postgres, then reads the resulting alert back out of the public API. If that fails, the install has failed, whatever the containers say.

Windows (install.ps1)​

  1. winget must be present (it ships with Windows 10 21H2+ and all Windows 11 builds; the script tells you what to install if your machine is older than that).
  2. git via winget install --id Git.Git.
  3. WSL2 — if Docker Desktop isn't already installed, the script enables the Microsoft-Windows-Subsystem-Linux and VirtualMachinePlatform features and sets WSL2 as the default version. A reboot is required after WSL2 is first enabled; the script tells you exactly when to reboot and which command to re-run after sign-in.
  4. Docker Desktop via winget install --id Docker.DockerDesktop. The script waits for the Docker Engine socket to come up before proceeding.
  5. Node.js 22 LTS via winget install --id OpenJS.NodeJS.LTS.
  6. pnpm 8+ via corepack enable && corepack prepare pnpm@latest.
  7. The AiSOC repo — cloned to $env:USERPROFILE\aisoc (override with -CloneDir 'C:\path\to\clone').
  8. pnpm install --frozen-lockfile, then the same three stages make up and make smoke perform on Linux and macOS. Windows has no make, so install.ps1 runs them natively — the port pre-check, docker compose up -d with a wait for every container to report healthy, docker compose run --rm -T api python -m app.scripts.bootstrap_admin, and the golden-pipeline runner. Same stack, same administrator, same proof.

Common cases​

"I already have everything installed"​

That's fine. The installer is idempotent — it detects existing sufficient versions and skips them. The end state is the same: a running CORE stack that has demonstrably processed an event.

"I want to install into a different directory"​

# Linux/macOS — clone to ~/work/aisoc instead of ~/aisoc:
curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh -o install.sh
bash install.sh --clone-dir "$HOME/work/aisoc"
# Windows — clone to D:\src\aisoc instead of $HOME\aisoc:
iwr -useb https://raw.githubusercontent.com/beenuar/AiSOC/main/install.ps1 -OutFile $env:TEMP\aisoc-install.ps1
& $env:TEMP\aisoc-install.ps1 -CloneDir 'D:\src\aisoc'

"I want to run the script after reading it"​

Recommended for production-adjacent machines. Both scripts live at the repo root and are short enough to read in one sitting:

curl -fsSLO https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh
less install.sh         # read it
shellcheck install.sh   # optional: confirm it's lint-clean
bash install.sh
iwr -useb https://raw.githubusercontent.com/beenuar/AiSOC/main/install.ps1 -OutFile install.ps1
notepad install.ps1     # read it
.\install.ps1

"I want to skip the launch and just install dependencies"​

# Linux/macOS:
bash install.sh --no-launch

# Windows:
.\install.ps1 -NoLaunch

The repo is still cloned and pnpm install still runs, but the stack is not started, no administrator is created and the pipeline check does not run — so you can configure .env / secrets / connectors before the first startup. Both scripts print the commands to run afterwards.

"I want to redirect the stack to a different host or port"​

Edit .env after the clone step. The relevant variables are documented inline in .env.example and in Deployment → Environment variables.

Uninstall​

Both installers ship with a matching uninstaller, also at the repo root (uninstall.sh and uninstall.ps1). They are graduated — by default they only stop the stack and drop its named volumes, leaving Docker Desktop, Node, pnpm, and the repo untouched. Pass flags to escalate.

ActionLinux / macOSWindows
Stop stack + drop volumes./uninstall.sh.\uninstall.ps1
Also remove pulled images (~3 GB)./uninstall.sh --images.\uninstall.ps1 -Images
Also delete node_modules./uninstall.sh --node-modules.\uninstall.ps1 -NodeModules
Also delete the repo clone./uninstall.sh --repo.\uninstall.ps1 -Repo
Everything except shared deps./uninstall.sh --all.\uninstall.ps1 -All
Skip confirmation prompts./uninstall.sh --all --yes.\uninstall.ps1 -All -Yes

The uninstaller intentionally does not remove Docker, Docker Desktop, Node, pnpm, Homebrew, WSL2, or git — those are general-purpose tools that other apps on your machine likely depend on. Remove them manually if you really want a clean wipe.

Troubleshooting​

curl: command not found (fresh Alpine container)​

apk add --no-cache curl bash

Then re-run the one-liner.

"Cannot connect to the Docker daemon" on the first run (Linux)​

The installer has just added you to the docker group, but the current shell still uses your old group set. The installer works around this by running its own follow-up Docker commands through sg docker -c …. For your next interactive shell to pick up the new group, log out and back in (or newgrp docker).

"Hyper-V is not enabled" on Windows Home​

Windows Home doesn't include Hyper-V; Docker Desktop relies on the WSL2 backend instead. The installer enables WSL2 automatically and Docker Desktop will use it. If Docker Desktop still complains, open Settings → General and confirm "Use the WSL 2 based engine" is ticked, then wsl --update and restart Docker Desktop.

I can't sign in​

There are no default credentials. The installer creates admin@aisoc.internal with a password generated on your machine and printed once, at the end of the run — it is stored nowhere. If the terminal has already scrolled away, mint a new one:

make bootstrap ARGS=--reset-password
docker compose run --rm -T api python -m app.scripts.bootstrap_admin --reset-password

The stack is already running​

Both installers are idempotent — re-running one against a healthy stack starts nothing new and reports the administrator that already exists. To get a fully clean start:

make clean   # stop the stack and delete all volumes
make up      # bring it back up
docker compose down -v
.\install.ps1 -NoInstall

Anything else​

The troubleshooting page has runbooks for the most common stack-level failure modes (healthchecks red, Postgres OOM, Kafka cluster-id drift, …). For installer-specific bugs, file an issue with the installer's full output — github.com/beenuar/AiSOC/issues.

Security notes​

  • Both installers run as your user, not root. They invoke sudo only for package-manager calls on Linux. macOS Homebrew prompts for a password the first time it touches /opt/homebrew or /usr/local.
  • The Linux script does not disable SELinux, AppArmor, or your firewall. The stack binds only to 127.0.0.1, so nothing is exposed to your LAN by default.
  • The Windows script enables WSL2 and starts Docker Desktop. It does not join AD, change Defender settings, or reconfigure Windows Update.
  • The Docker images pulled by the demo (ghcr.io/beenuar/aisoc-*) are signed with Cosign; the Docker deployment page documents the signature verification workflow.
  • The demo seeds synthetic data only. No real customer data, IOCs, or telemetry is shipped with the installer.
  • The repo is cloned over HTTPS from github.com/beenuar/AiSOC — there is no opaque "phone home" URL involved.

What's next​