Installation

Aludel can run embedded in an existing Phoenix app, as a standalone dashboard, or through the repository Docker setup.

Prerequisites

• Elixir 1.17+
• PostgreSQL 12+
• ImageMagick (optional, for PDF conversion)
• A provider API key for each hosted provider you use; Ollama does not require one

Aludel depends on PostgreSQL-specific features, including JSONB, percentile_disc(), and DATE()-based aggregations. SQLite and MySQL are not supported.

Embedded Phoenix App

Use this path when you want Aludel mounted inside an existing Phoenix application.

1. Add the dependency

def deps do
  [
    {:aludel, "~> 0.6.1"}
  ]
end

mix deps.get

2. Configure the repo

config :aludel, repo: YourApp.Repo

3. Install and run migrations

mix aludel.install
mix ecto.migrate

4. Mount the dashboard

use YourAppWeb, :router
import Aludel.Web.Router

if Mix.env() == :dev do
  scope "/dev" do
    pipe_through :browser
    aludel_dashboard "/aludel"
  end
end

aludel_dashboard/2 also supports :as, :aludel_name, :resolver, :on_mount, :socket_path, :transport, :logo_path, and :csp_nonce_assign_key. See Embedding and Access for examples.

5. Configure provider keys

In config/runtime.exs:

config :aludel, :llm,
  openai_api_key: System.get_env("OPENAI_API_KEY"),
  anthropic_api_key: System.get_env("ANTHROPIC_API_KEY"),
  google_api_key: System.get_env("GOOGLE_API_KEY"),
  xai_api_key: System.get_env("XAI_API_KEY"),
  groq_api_key: System.get_env("GROQ_API_KEY"),
  openrouter_api_key: System.get_env("OPENROUTER_API_KEY")

6. Configure document storage

Development can use the local adapter:

config :aludel, Aludel.Storage,
  adapter: Aludel.Interfaces.Storage.Adapters.Local,
  backends: [{Aludel.Interfaces.Storage.Adapters.Local, []}]

Production requires ALUDEL_STORAGE_BACKEND and a supported cloud backend:

export ALUDEL_STORAGE_BACKEND=aws
export AWS_S3_BUCKET=aludel-uploads
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

export ALUDEL_STORAGE_BACKEND=gcs
export GCS_BUCKET=aludel-uploads
export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json

If your GCS bucket requires requester-pays access, also set GCS_USER_PROJECT.

7. Optional: route execution through your app

Native mode is the default, but embedded installs can also hand runs and suites to the host app so Aludel exercises the same orchestration path you use in production.

config :aludel,
  execution_mode: :callback,
  executor: MyApp.AludelExecutor

Your executor must implement Aludel.Executor and return at least an output field. input_tokens, output_tokens, latency_ms, cost_usd, and metadata are optional, so callback mode can represent workflows that do not emit every metric.

Standalone Application

Use this path when you want Aludel running by itself.

1. Clone the Repository

git clone https://github.com/ccarvalho-eng/aludel.git
cd aludel/standalone

2. Install Dependencies

mix deps.get

3. Create and migrate the database

mix ecto.create
mix ecto.migrate

To load deterministic prompts, all seven providers, datasets, suites, runs, artifacts, failures, and 60 days of analytics:

mix aludel.seed

4. Start the server

mix phx.server

Access at http://localhost:4000.

The standalone release supports optional HTTP Basic Authentication and read-only access:

export BASIC_AUTH_USER=admin
export BASIC_AUTH_PASS=change-me
export READ_ONLY=true

Docker Deployment

1. Clone Repository

git clone https://github.com/ccarvalho-eng/aludel.git
cd aludel

2. Create Environment File

Create .env with the values expected by docker-compose.yaml:

DATABASE_URL=postgres://postgres:postgres@db:5432/aludel_dash
SECRET_KEY_BASE=your_secret_key_here
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
XAI_API_KEY=...
GROQ_API_KEY=...
OPENROUTER_API_KEY=...
PHX_HOST=localhost

3. Start Services

docker compose up -d

This builds the standalone app image from standalone/Dockerfile, starts PostgreSQL, runs migrations, and launches the dashboard at http://localhost:4000.

Environment Variables

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...
export XAI_API_KEY=...
export GROQ_API_KEY=...
export OPENROUTER_API_KEY=...
# Ollama: no API key required

Verification

mix test
mix precommit

Next Steps

• Quick Start
• Providers
• Embedding and Access
• Documents and Storage
• Architecture