Prerequisites

Run through this page once on a fresh machine before Run it locally. Pick the tab for your OS — every step lists what you should see, how to verify it worked, and what to do when the most common error appears.

What you are installing

Tool	Version	Why
Git	latest	Clone the two repos
Node.js	22.x (LTS)	Runs the Next.js app
pnpm	9.15.9	The repo pins this exact version
Docker	24+ with Compose v2	Postgres, Redis, MinIO, Superset, Hub
OpenSSL	any	Generates one-shot secrets for `.env`
Go	1.25+ (optional)	Only if you run `hivecfm-hub` natively instead of in Docker

Windows 10 / 11

Install Git

winget install --id Git.Git -e

Expected: “Successfully installed” within ~30 s.
Verify: open a new PowerShell window and run git --version — prints git version 2.x.x.
If git is not recognised: close and reopen the terminal so PATH is refreshed. Still missing? Reinstall and tick “Add to PATH” in the installer.
search-hint: git not recognized as internal or external command

Install nvm-windows, then Node 22

winget install --id CoreyButler.NVMforWindows -e

Close and reopen the terminal, then:

nvm install 22
nvm use 22

Expected: nvm use 22 prints Now using node v22.x.x (64-bit).
Verify: node -v prints v22.x.x.
If “exit status 1: The system cannot find the path specified”: run the terminal as Administrator once; nvm-windows needs admin to create the nodejs symlink.
If nvm is not recognised: the installer placed it under %APPDATA%\nvm but the env var NVM_HOME wasn’t picked up — log out and back in.
search-hint: nvm-windows exit status 1

Install pnpm 9.15.9

corepack enable
corepack prepare pnpm@9.15.9 --activate

Expected: No output from corepack enable; prepare prints Preparing pnpm@9.15.9 for immediate activation....
Verify: pnpm -v prints 9.15.9 exactly.
If “Unknown command ‘corepack’”: your Node is older than 16.10. Re-run nvm use 22.
If pnpm -v prints a different version: another global pnpm is shadowing corepack. Run npm uninstall -g pnpm and try again.
search-hint: corepack unknown command

Install Docker Desktop

winget install --id Docker.DockerDesktop -e

After install, launch Docker Desktop once and accept the license. It will enable WSL2 automatically.

Expected: Docker tray icon turns from orange to green within ~60 s on first run.
Verify: docker compose version prints Docker Compose version v2.x.x.
If “docker: command not found”: Docker Desktop didn’t add itself to PATH. Sign out and back in, or add C:\Program Files\Docker\Docker\resources\bin to PATH manually.
If WSL2 install fails: enable virtualization in BIOS and run wsl --install in an admin terminal, then reboot.
Memory tip: open Docker Desktop → Settings → Resources and give it at least 8 GB RAM — the Next.js build peaks around 8 GB.
search-hint: docker desktop wsl2 install failed windows

Verify OpenSSL

OpenSSL ships with Git for Windows. Open Git Bash (not PowerShell) and run:

openssl version

Expected: OpenSSL 3.x.x ....
Verify: openssl rand -hex 32 prints a 64-character hex string.
If not found in PowerShell: that is expected — use Git Bash for any openssl command, or install winget install --id ShiningLight.OpenSSL.Light for a PowerShell-native build.
search-hint: openssl windows powershell not recognized

(Optional) Install Go 1.25+

Skip this step if you plan to run the Hub in Docker (the default). Install Go only if you want native hot-reload on the Go service.

winget install --id GoLang.Go -e

Expected: “Successfully installed” within ~30 s.
Verify: go version prints go version go1.25.x windows/amd64.
If go: command not found: reopen the terminal so PATH is refreshed.
search-hint: go version not recognized windows

macOS (Apple Silicon or Intel)

These steps assume Homebrew is installed. If not: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)".

Install Git

brew install git

Expected: ~10 s. Homebrew may report it’s already installed (macOS bundles a Git stub via Xcode Command Line Tools).
Verify: git --version prints git version 2.4x.x (Homebrew) — newer than the bundled Apple one.
If xcode-select: error: ... license has not been accepted: run sudo xcodebuild -license accept.
search-hint: homebrew git xcode command line tools

Install nvm, then Node 22

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
exec $SHELL -l
nvm install 22
nvm use 22

Expected: nvm use 22 prints Now using node v22.x.x.
Verify: node -v prints v22.x.x; which node resolves under ~/.nvm/versions/node/v22....
If nvm: command not found after install: your shell rc file (~/.zshrc on modern macOS) wasn’t sourced. Open a new terminal or run source ~/.zshrc.
search-hint: nvm command not found mac zsh

Install pnpm 9.15.9

corepack enable
corepack prepare pnpm@9.15.9 --activate

Expected: Silent on enable; one-line print on prepare.
Verify: pnpm -v prints 9.15.9 exactly.
If corepack: command not found: Node < 16.10 or corepack was disabled. Re-run nvm use 22.
search-hint: corepack pnpm mac

Install Docker Desktop

brew install --cask docker

Then launch Docker from /Applications (or Spotlight) once to accept the license.

Expected: Docker whale icon appears in the menu bar and turns from yellow to white when ready (~60 s on first launch).
Verify: docker compose version prints Docker Compose version v2.x.x.
Memory tip: Docker → Settings → Resources → give it at least 8 GB RAM. The Next.js build peaks around 8 GB.
If Apple Silicon issues with x86 images: enable Rosetta 2 emulation under Docker → Settings → General. Most HiveCFM images are multi-arch so this is rarely needed.
search-hint: docker desktop mac apple silicon rosetta

Verify OpenSSL

macOS ships LibreSSL by default; Homebrew Git pulls in OpenSSL too.

openssl version

Expected: LibreSSL 3.x.x or OpenSSL 3.x.x ....
Verify: openssl rand -hex 32 prints a 64-character hex string.
If you want the Homebrew OpenSSL 3.x explicitly: brew install openssl@3 && export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH" (Apple Silicon) or /usr/local/opt/openssl@3/bin (Intel).
search-hint: mac libressl vs openssl

(Optional) Install Go 1.25+

brew install go

Verify: go version prints go version go1.25.x darwin/arm64 (or darwin/amd64).
If your brew version is stale and only ships Go 1.24: brew update && brew upgrade go.
search-hint: homebrew install latest go

Linux / AWS EC2 (Ubuntu 22.04+ or Amazon Linux 2023)

This is the path for running HiveCFM on a remote EC2 instance you SSH into. The flow is identical between Ubuntu and AL2023; only the package manager differs (apt vs dnf).

Before you SSH in — pick the right EC2 instance

Resource	Minimum	Recommended
Instance type	`t3.large` (2 vCPU, 8 GB RAM)	`t3.xlarge` (4 vCPU, 16 GB) or `m6i.xlarge`
EBS root volume	30 GB gp3	50 GB gp3
Security group	SSH 22 inbound (from your IP)	Same — all app ports stay localhost-only and are reached via SSH tunnel
AMI	Ubuntu 22.04 LTS or Amazon Linux 2023	Same
User	`ubuntu` (Ubuntu) or `ec2-user` (AL2023)	Same — use sudo when noted

⚠️

Do not open app ports (3001, 4100, 5433, 8090) in the security group. They bind to 127.0.0.1 inside the instance — exposing them would skip authentication. Use SSH tunneling instead (covered in Run it locally).

One-time instance prep

# Ubuntu
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl ca-certificates gnupg lsb-release build-essential
 
# Amazon Linux 2023
sudo dnf update -y
sudo dnf install -y curl ca-certificates gnupg tar gzip make gcc-c++

Expected: A few hundred MB of updates on first run.
Verify: curl --version and gcc --version both succeed.
If Could not get lock /var/lib/dpkg/lock-frontend: unattended-upgrades is running. Wait 60 s and retry.
search-hint: ubuntu apt could not get lock dpkg

Add swap (only if instance has < 16 GB RAM)

The Next.js build peaks around 8 GB. On a t3.large (8 GB) the OOM-killer will hit pnpm build without swap.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Expected: swapon prints nothing on success.
Verify: free -h shows Swap: 4.0Gi in the totals row.
If fallocate: cannot insert into ext4: fall back to sudo dd if=/dev/zero of=/swapfile bs=1M count=4096.
search-hint: aws ec2 add swap ubuntu

Install Git

# Ubuntu
sudo apt install -y git
 
# Amazon Linux 2023
sudo dnf install -y git

Expected: ~5 s.
Verify: git --version prints git version 2.x.x.
If the bundled Git is older than 2.34: add the PPA — sudo add-apt-repository ppa:git-core/ppa && sudo apt update && sudo apt install git (Ubuntu only).
search-hint: ubuntu install latest git ppa

Install nvm, then Node 22

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
exec $SHELL -l
nvm install 22
nvm use 22
nvm alias default 22

Expected: Installer prints “Now using node v22.x.x”. default alias makes future shells pick Node 22 automatically.
Verify: node -v prints v22.x.x. New SSH session: node -v still prints v22.x.x.
If nvm: command not found after install: the installer appends to ~/.bashrc but didn’t source it. Run source ~/.bashrc or open a new SSH session.
If your shell is sh not bash: SSH in with bash -l or set chsh -s /bin/bash.
search-hint: nvm linux ec2 command not found

Install pnpm 9.15.9

corepack enable
corepack prepare pnpm@9.15.9 --activate

Expected: Silent then one-line print.
Verify: pnpm -v prints 9.15.9.
If corepack: permission denied: corepack tries to write to the Node install directory. With nvm-installed Node this should “just work” because the dir is owned by you; if not, sudo chown -R $USER ~/.nvm.
search-hint: pnpm corepack linux permission denied

Install Docker Engine + Compose plugin

EC2 instances run headless — use Docker Engine (the daemon + CLI), not Docker Desktop. Docker Desktop is a GUI app for laptops.

Ubuntu:

# Add Docker's official GPG key and repo
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Amazon Linux 2023:

sudo dnf install -y docker
# AL2023 doesn't bundle the compose plugin — install it manually:
DOCKER_CONFIG=${DOCKER_CONFIG:-/usr/local/lib/docker}
sudo mkdir -p $DOCKER_CONFIG/cli-plugins
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
  -o $DOCKER_CONFIG/cli-plugins/docker-compose
sudo chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Then enable the daemon and add yourself to the docker group:

sudo systemctl enable --now docker
sudo usermod -aG docker $USER
# log out and back in (or: newgrp docker) so the group takes effect
exit

After reconnecting via SSH:

Expected: docker ps works without sudo.
Verify: docker compose version prints Docker Compose version v2.x.x. docker info | grep "Storage Driver" shows overlay2.
If permission denied while trying to connect to the Docker daemon socket: you didn’t log out/in after usermod. Disconnect SSH fully and reconnect.
If docker: command not found on Ubuntu after install: the repo line didn’t take. Re-check cat /etc/apt/sources.list.d/docker.list.
search-hint: docker permission denied ec2 ubuntu

Verify OpenSSL

OpenSSL is preinstalled on both distros.

openssl version

Expected: OpenSSL 3.x.x ....
Verify: openssl rand -hex 32 prints a 64-character hex string.
search-hint: openssl rand hex linux

(Optional) Install Go 1.25+

Skip this if you’ll run the Hub in Docker (the default).

# Pick latest 1.25.x tarball from https://go.dev/dl/
GO_VERSION=1.25.0
curl -OL https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go${GO_VERSION}.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

Verify: go version prints go version go1.25.x linux/amd64.
If on ARM (Graviton t4g/m7g): swap linux-amd64 for linux-arm64 in the URL and tarball name.
search-hint: install go linux tarball

Authenticate with Azure DevOps so you can clone the repos

The three HiveCFM repos live on Azure DevOps, not GitHub:

https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-core
https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-hub
https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-dev-hub

A bare git clone over HTTPS will prompt for credentials. On a headless EC2 instance you need a non-interactive way to provide them. Pick one of the two paths below.

⚠️

Never embed your PAT directly in the remote URL (e.g. https://user:PAT@dev.azure.com/...). It leaks every time you run git remote -v, gets baked into .git/config, and ends up in CI logs and shell history. Use one of the patterns below instead.

Option A — Personal Access Token (PAT) + git credential store (recommended for EC2)

Generate a PAT in Azure DevOps

Sign in to https://dev.azure.com/istnetworksrnd from your laptop browser.
Click your avatar (top right) → Personal access tokens → + New Token.
Name: ec2-dev-<your-initials> so you can identify it later.
Organization: istnetworksrnd. Expiration: 90 days (rotate it; do not pick “Custom defined” → 1 year).
Scopes: Click Custom defined → tick Code (Read & write) only. Don’t grant Full Access.
Click Create and copy the token immediately — Azure DevOps shows it once.

Expected: A 52-character base32-ish string starting with letters/digits.
Verify: Store it in 1Password / your password manager before leaving the page.
If you closed the page: revoke the token and create a new one. There is no way to see it again.
search-hint: azure devops personal access token create

Configure git on the EC2 box to use the PAT

git config --global credential.helper store
git config --global user.email "you@istnetworks.com"
git config --global user.name  "Your Name"

credential.helper store writes credentials to ~/.git-credentials in plain text on disk. That is fine for a dedicated dev instance you own; do not use it on a shared box. For shared instances use credential.helper cache --timeout=28800 (in-memory, 8 hours).

Verify: git config --global --list | grep credential shows credential.helper=store.
search-hint: git credential helper store linux

(VS Code Remote-SSH only) Disable the broken askpass helper

⚠️

Skip this step if you’re SSH’d in from a plain terminal (PuTTY, Windows Terminal, iTerm). It only matters if you opened the EC2 box through VS Code → Remote-SSH and you’re using VS Code’s integrated terminal.

VS Code Remote-SSH injects a credential helper (GIT_ASKPASS) into every terminal session. The helper tries to phone home to a Unix socket on your laptop (/run/user/<uid>/vscode-git-<hash>.sock) — that socket does not exist on the EC2 box, so git fails before it ever shows you a password prompt.

If you see this on a git clone:

Error: connect ECONNREFUSED /run/user/1000/vscode-git-<hash>.sock
fatal: Authentication failed for 'https://dev.azure.com/...'

…it is not a bad PAT. It is the VS Code helper.

One-shot fix for the current shell — paste this as one line:

unset GIT_ASKPASS VSCODE_GIT_ASKPASS_NODE VSCODE_GIT_ASKPASS_MAIN VSCODE_GIT_ASKPASS_EXTRA_ARGS VSCODE_GIT_IPC_HANDLE SSH_ASKPASS

Expected: No output. Git will now fall back to the terminal password prompt as designed.
Verify: echo "$GIT_ASKPASS" prints an empty line.
If you opened a new tab and got the error again: the unset only lives in the shell you ran it in. Use the permanent fix below.

Permanent fix — append to ~/.bashrc so every new shell is clean:

printf '\n# Disable VS Code Remote-SSH git askpass (socket isn'"'"'t reachable on EC2)\nunset GIT_ASKPASS VSCODE_GIT_ASKPASS_NODE VSCODE_GIT_ASKPASS_MAIN VSCODE_GIT_ASKPASS_EXTRA_ARGS VSCODE_GIT_IPC_HANDLE SSH_ASKPASS 2>/dev/null\n' >> ~/.bashrc

Then reload in the current shell:

source ~/.bashrc

Expected: Last two non-empty lines of ~/.bashrc are the comment and the unset line.
Verify: tail -3 ~/.bashrc shows them.
If you use zsh instead of bash: append the same lines to ~/.zshrc.
search-hint: vscode remote ssh git askpass ECONNREFUSED

Make a working directory

Run this on the EC2 box:

mkdir -p ~/AG-DEV
cd ~/AG-DEV

Both lines together create the folder (no error if it already exists) and move into it. After this your prompt should end in AG-DEV$.

Trigger the first clone — git will ask once and remember

⚠️

A URL is not a command. Always type or paste git clone in front of the URL. Pasting just https://dev.azure.com/... at the prompt makes bash say No such file or directory.

git clone https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-core

Git will then prompt interactively. Type your Azure DevOps email when it asks for username; paste your PAT when it asks for password (right-click in PuTTY, or Shift+Insert in most Linux terminals):

Cloning into 'hivecfm-core'...
Username for 'https://dev.azure.com': Ahmed.Genidy@istnetworks.com
Password for 'https://Ahmed.Genidy@istnetworks.com@dev.azure.com': <paste your PAT here, then Enter>

The PAT itself is invisible while you type/paste — that’s normal. Just paste and press Enter.

Expected: Clone completes in ~30 s. Subsequent clones (hivecfm-hub, hivecfm-dev-hub) won’t prompt — ~/.git-credentials already has the entry.
Verify (run after clone):
```
ls ~/AG-DEV/hivecfm-core
```
You should see directories like apps, packages, scripts.
Verify the credential was saved:
```
ls -l ~/.git-credentials
```
The file exists and is mode -rw------- (600).
If Error: connect ECONNREFUSED /run/user/.../vscode-git-*.sock immediately followed by fatal: Authentication failed: this is not a bad PAT. VS Code Remote-SSH’s askpass helper is hijacking the prompt. Go back to the Disable the broken askpass helper step above, then retry the clone.
If fatal: Authentication failed: the PAT was mistyped, expired, or lacks Code (Read & write) scope. Regenerate in dev.azure.com → avatar → Personal access tokens.
If TF401019: The Git repository ... does not exist or you do not have permissions: your Azure DevOps account isn’t a member of the HiveCFM project — ask the team lead to add you.
If bash says No such file or directory and prints the URL: you forgot git clone in front. Re-run with the command.
If your paste arrived split across lines (you see fatal: You must specify a repository to clone. followed by bash: https://...: No such file or directory): your terminal broke the long command on a newline. Either type git clone <url> manually as one line, or set URL=https://dev.azure.com/.../hivecfm-core first then run git clone "$URL" — two short lines instead of one long one.
search-hint: azure devops git clone authentication failed TF401019

(Optional) Clone a specific branch

By default git clone checks out the repo’s default branch (usually main). To clone directly onto a different branch — e.g. the active migrator branch:

git clone -b AG-hiveCoreMigrtorTool https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-core

The -b <branch-name> flag picks the branch at clone time. To see what branches exist before cloning:

git ls-remote --heads https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-core

This prints one line per branch (e.g. refs/heads/main, refs/heads/AG-hiveCoreMigrtorTool, refs/heads/develop). Pick the one you want and pass it to -b.

Clone the other two repos

Once the credentials are stored, the remaining repos clone without prompting:

cd ~/AG-DEV
git clone https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-hub
git clone https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-dev-hub

Verify:
```
ls ~/AG-DEV
```
Output should list three directories: hivecfm-core, hivecfm-hub, hivecfm-dev-hub.

Option B — SSH key (use this if you already manage SSH keys for other services)

Generate an SSH key on the EC2 box

ssh-keygen -t ed25519 -C "ec2-dev-<your-initials>" -f ~/.ssh/azuredevops_ed25519 -N ""

Expected: Two files created: ~/.ssh/azuredevops_ed25519 (private) and ~/.ssh/azuredevops_ed25519.pub (public).
Verify: ls -l ~/.ssh/azuredevops_ed25519* — private key should be -rw------- (600).

Add the public key to Azure DevOps

cat ~/.ssh/azuredevops_ed25519.pub

Copy the output, then in browser: dev.azure.com → avatar → SSH public keys → + New Key → paste → save.

Tell SSH which key to use for dev.azure.com

Append this to ~/.ssh/config on the EC2 box (create the file if missing):

Host ssh.dev.azure.com
  IdentityFile ~/.ssh/azuredevops_ed25519
  IdentitiesOnly yes

Clone using the SSH URL (note the different format)

git clone git@ssh.dev.azure.com:v3/istnetworksrnd/HiveCFM/hivecfm-core

Expected: First connect prompts you to accept the host key — type yes.
Verify: git -C hivecfm-core remote -v shows the SSH URL (no PAT, no password).
If “Permission denied (publickey)”: the public key wasn’t accepted by Azure DevOps (paste error?) or ~/.ssh/config isn’t pointing to the right IdentityFile. Test with ssh -T git@ssh.dev.azure.com — it should respond with a welcome line, not “permission denied”.
search-hint: azure devops git clone ssh permission denied publickey

Use tmux so your dev server survives SSH disconnects

When you run pnpm dev or docker compose up, closing the SSH session kills the process unless it’s inside a persistent terminal multiplexer.

# Ubuntu
sudo apt install -y tmux
# AL2023
sudo dnf install -y tmux
 
tmux new -s hive
# inside: pnpm dev, docker compose up, etc.
# detach: Ctrl-B then D
# reattach later: tmux attach -t hive

Verify: tmux ls lists your hive session even after you log out and log back in.
If you prefer screen: sudo apt install screen then screen -S hive / Ctrl-A D to detach / screen -r hive to reattach.
search-hint: tmux attach detach cheat sheet

Ready to clone and start the stack? → Run it locally covers the SSH tunneling commands you’ll need to actually open the app in your laptop’s browser.

Done — what’s next

You are ready to clone the repos and start the stack.

→ Continue to Run it locally.

If you also want to set up your editor first (recommended for laptop dev; skip on EC2): IDE setup.

Tech Stack (for .NET devs)Secrets & Environment

Was this page helpful?