Getting Started

Table of contents

1. Quick Start (with Docker Compose)
2. Local Setup (with uv)

---

Welcome! This guide will help you get up and running with the Aqueduct AI Gateway project.

Quick Start (with Docker Compose)

The recommended way to get Aqueduct running locally is with Docker Compose. This will start the Django app, a PostgreSQL database, Celery with Redis as the broker, Tika for text extraction from files, and a local mock OIDC provider (Dex) for authentication.

1. Clone the repository

   git clone https://github.com/tu-wien-datalab/aqueduct.git
   cd aqueduct
   

2. Set the necessary environment variables Most of the necessary environment variables are provided in the .example.env file. You only need to set the OPENAI_API_KEY:

   export OPENAI_API_KEY="your-openai-api-key"
   

   This variable is used by the sample router configuration, provided in the example_router_config.yaml file. Adjust it if you want to use other models.

3. Start the services

   docker compose up --build
   

   This will build and start all required services using the provided .example.env and example_router_config.yaml files for environment variables and the router configuration. For example, you could use vLLM to run a model locally.

4. Access the application

   • The web UI will be available at http://localhost:8000
   • The local OIDC provider (Dex) will be running at http://localhost:5556/dex
   • Default login credentials for Dex are:
     • Username: you@example.com
     • Password: 1234

You can now access the admin UI and start exploring the gateway features.

NOTE: This starts Django in debug mode and is not suitable for production deployments. Change the necessary settings for a production deployment.

---

Local Setup (with uv)

If you prefer to run Aqueduct directly on your machine (for development), you can use uv:

1. Install uv
   If you don’t have uv installed, you can install it via pip:

   pip install uv
   

2. Clone the repository

   git clone https://github.com/tu-wien-datalab/aqueduct.git
   cd aqueduct
   

3. Create a virtual environment and install dependencies

   uv venv
   source .venv/bin/activate
   uv sync
   

4. Run the Django development server

   uv run aqueduct/manage.py runserver
   

Note: You will need to have Dex running locally, or adjust your environment variables accordingly to use an existing OIDC provider.

---