Skip to content

Installation Guide

Aegis Stack can be used in multiple ways depending on your needs and preferences.

System Requirements

Before installing Aegis Stack, ensure you have the following:

Required

  • Python 3.11 or higher - Core runtime for Aegis Stack and generated projects
  • Docker & Docker Compose - Required for generated projects' development workflow

Why Docker?

Generated projects use Docker for:

  • Consistent development environments - Same setup across all machines
  • Service dependencies - Redis for worker component, health monitoring infrastructure
  • Standard workflow - The make serve command uses docker compose under the hood
  • Production parity - Development closely mirrors production deployment

Docker Alternatives

While the standard workflow uses Docker, generated projects are standard Python applications. Advanced users can manually run components (uvicorn for backend, direct Redis installation, etc.), but this workflow is currently undocumented and unsupported.

Installing Docker

Installation

Choose the method that works best for your workflow:

The fastest way to use Aegis Stack without any installation:

# Create a new project
uvx aegis-stack init my-project

# Get help
uvx aegis-stack --help

# Create with specific components
uvx aegis-stack init my-api --components worker,scheduler

Benefits:

  • No installation required
  • Always uses latest version
  • Zero setup, works immediately
  • Isolated execution environment
  • Perfect for trying Aegis Stack or one-off usage

Best for: Quick start, experimentation, CI/CD, one-off usage

Install Aegis Stack as a persistent CLI tool with uv:

# Install persistently
uv tool install aegis-stack

# Use the installed version
aegis init my-project
aegis --help
aegis components

Benefits:

  • Fastest subsequent runs (pre-installed)
  • Simple aegis command
  • Easy to upgrade with uv tool upgrade aegis-stack
  • Persistent installation

Best for: Daily development work, regular CLI usage

Install Aegis Stack with pip:

# Install from PyPI
pip install aegis-stack

# Use the installed version
aegis init my-project
aegis --help
aegis components

Benefits:

  • Works in any Python environment
  • Familiar to all Python developers
  • Compatible with existing workflows

Best for: Traditional workflows, existing pip-based setups

For contributing, customizing, or working with the latest development version:

# Clone the repository
git clone https://github.com/lbedner/aegis-stack
cd aegis-stack

# Install with all development dependencies
uv sync --all-extras

# Use development version
.venv/bin/aegis init my-project

# Run tests
.venv/bin/pytest

# Build documentation
.venv/bin/mkdocs serve

Benefits:

  • Latest unreleased features
  • Full development environment
  • Ability to modify and test changes
  • Access to development tools

Best for: Contributing, customizing, latest features