Prerequisites
Before setting up AEGIS locally, you need the following tools installed on your machine.
Required Tools
| Tool | Version | Purpose |
|---|---|---|
| Python | 3.12.x | All 8 Python microservices |
| pyenv | Latest | Python version management |
| Poetry | 1.7+ | Python dependency management |
| Go | 1.21+ | API gateway service |
| Node.js | 18+ | Next.js frontend |
| npm | 9+ | Frontend package management |
| Docker | 24+ | PostgreSQL, Redis, Kafka containers |
| Docker Compose | v2 | Multi-container orchestration |
Installation
Python 3.12 via pyenv
AEGIS pins Python 3.12 at the repository root. Install pyenv and the correct Python version:
macOS
# Install pyenv
brew install pyenv
# Add to your shell profile (~/.zshrc or ~/.bashrc)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
# Reload shell
source ~/.zshrc
# Install Python 3.12
pyenv install 3.12The repository contains a .python-version file that tells pyenv to use Python 3.12 automatically when you cd into the project directory.
Poetry
Poetry manages Python dependencies for each service. Configure it to use pyenv’s Python:
# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -
# Configure Poetry to use the active Python (from pyenv)
poetry config virtualenvs.prefer-active-python trueGo 1.21+
The API gateway is written in Go.
macOS
brew install goNode.js 18+
The frontend is a Next.js 14 application that requires Node.js 18 or later.
macOS
brew install nodeDocker and Docker Compose
AEGIS uses Docker Compose to run PostgreSQL 15 (with pgvector and Apache AGE), Redis 7, and Kafka.
macOS
# Docker Desktop for Mac includes Docker Compose v2
brew install --cask dockerVerification
After installing everything, verify each tool is available:
# Python
python --version
# Expected: Python 3.12.x
# pyenv
pyenv --version
# Expected: pyenv 2.x.x
# Poetry
poetry --version
# Expected: Poetry (version 1.7.x or later)
# Go
go version
# Expected: go1.21.x or later
# Node.js
node --version
# Expected: v18.x.x or later
# npm
npm --version
# Expected: 9.x.x or later
# Docker
docker --version
# Expected: Docker version 24.x.x or later
# Docker Compose
docker compose version
# Expected: Docker Compose version v2.x.xIf python --version does not show 3.12.x after installing pyenv, make sure you have reloaded your shell (source ~/.zshrc or source ~/.bashrc) and that pyenv’s shims directory is in your PATH.
Optional Tools
These tools are helpful for development but not strictly required:
| Tool | Purpose |
|---|---|
| psql | Direct PostgreSQL client access |
| redis-cli | Direct Redis inspection |
| httpie or curl | API testing from the terminal |
| jq | JSON formatting in the terminal |
# macOS
brew install postgresql redis httpie jq
# Verify
psql --version
redis-cli --version