Installation

Emma is an experimental AI-powered assistant for Infrahub that helps you manage infrastructure schemas and data through an intuitive web interface.

Prerequisites

Before installing Emma, ensure you have:

• Infrahub instance: Emma requires a running Infrahub instance to connect to
• Docker (for containerized deployment) or Python 3.10+ and uv (for local development)

Installation methods

Quick Start (Recommended)

The easiest way to get started is using the Infrahub quickstart with Emma included:

# Download and start Infrahub + Emma with Docker Compose
curl https://infrahub.opsmill.io/latest-emma | docker compose -f - up -d

Or if you want to add Emma on to a specific release of Infrahub:

# Download and start Infrahub + Emma with Docker Compose
curl https://infrahub.opsmill.io/1.7.6-emma | docker compose -f - up -d

This command will:

• Download the latest Infrahub and Emma configuration
• Start both services with proper networking
• Make Emma available at http://localhost:8501
• Make Infrahub available at http://localhost:8000

tip

Update the version number in the URL to the latest Infrahub release for the most recent features.

Docker Compose

To run Emma alongside your existing Infrahub setup:

1. Clone the Emma repository:

git clone https://github.com/opsmill/emma.git
cd emma

2. Start Emma with Docker Compose:

docker compose up --build -d

3. Connect to Infrahub network (if running Infrahub in containers):

# Find your Infrahub network name
docker network ls

# Connect Emma to the Infrahub network
docker network connect <infrahub-network-name> emma-emma-1

Emma will be available at http://localhost:8501

Local Development

For development or custom setups:

1. Clone the repository:

git clone https://github.com/opsmill/emma.git
cd emma

2. Install dependencies with uv:

uv sync

3. Run Emma:

uv run streamlit run main.py

Emma will start on http://localhost:8501

Next steps

After installation, proceed to Configuration to set up your connection to Infrahub.

Troubleshooting

If you encounter issues during installation:

• Port conflicts: Ensure ports 8501 (Emma) and 8000 (Infrahub) are available
• Docker issues: Check Docker is running and you have sufficient resources allocated
• Network connectivity: Verify Emma can reach your Infrahub instance

For more detailed troubleshooting, see the Troubleshooting Guide.