Quick Start Guide

This guide will help you get started with ALMA.

Installation

# Clone the repository
git clone <repository-url>
cd alma

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Initialize Database

# The database will be automatically initialized when you first run the API
# For SQLite (default), no additional setup is needed

Start the API Server

# Start the development server
ALMA serve --reload

# Or using uvicorn directly
uvicorn alma.api.main:app --reload

The API will be available at http://localhost:8000 API documentation: http://localhost:8000/docs

Deploy Your First Blueprint

Using the CLI

# Create a new project
ALMA init my-infrastructure

# Deploy the example blueprint
cd my-infrastructure
ALMA deploy blueprints/example.yaml

# Dry-run (validation only)
ALMA deploy blueprints/example.yaml --dry-run

Using the API

# Create a blueprint
curl -X POST "http://localhost:8000/api/v1/blueprints/" \
  -H "Content-Type: application/json" \
  -d @examples/blueprints/simple-web-app.yaml

# Deploy the blueprint
curl -X POST "http://localhost:8000/api/v1/blueprints/1/deploy" \
  -H "Content-Type: application/json" \
  -d '{"blueprint_id": 1, "dry_run": false}'

Example Blueprint

Create a file my-blueprint.yaml:

version: "1.0"
name: "my-first-infrastructure"
description: "My first ALMA blueprint"

resources:
  - type: compute
    name: web-server
    provider: fake
    specs:
      cpu: 2
      memory: 4GB
      storage: 50GB

  - type: network
    name: load-balancer
    provider: fake
    specs:
      type: http
      backends:
        - web-server
    dependencies:
      - web-server

Deploy it:

ALMA deploy my-blueprint.yaml

Check Infrastructure Status

# Using CLI
ALMA status

# Using API
curl http://localhost:8000/api/v1/blueprints/

Run Tests

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/unit/test_fake_engine.py

# Run with verbose output
pytest -v

Next Steps

• Read the Architecture Guide
• Learn about Engines
• Explore Advanced Features
• Check out Example Blueprints

Troubleshooting

Database Issues

If you encounter database issues, try:

# Remove the database file
rm alma.db

# Restart the API server
ALMA serve --reload

Import Errors

Make sure you've installed the package in editable mode:

pip install -e ".[dev]"

Pre-commit Hook Failures

If pre-commit hooks fail, you can run them manually:

# Run all hooks
pre-commit run --all-files

# Run specific hook
black .
ruff check .
mypy alma

Getting Help

• Check the documentation
• Open an issue on GitHub