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.

Production releases require HTTP Basic Authentication. Generate a strong password and optionally enable read-only access:

export BASIC_AUTH_USER=admin
export BASIC_AUTH_PASS="$(openssl rand -base64 32)"
export READ_ONLY=true

Production startup rejects missing, partial, or blank credentials. Local development remains unauthenticated and listens only on loopback. READ_ONLY=true keeps the dashboard visible while server-side authorization blocks mutations and model requests.

Serve Basic Authentication over TLS. If a reverse proxy terminates TLS, preserve the Authorization header and keep the backend port private so clients cannot bypass the proxy.

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:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=use-a-strong-generated-password
POSTGRES_DB=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=...
BASIC_AUTH_USER=admin
BASIC_AUTH_PASS=use-a-strong-generated-password
PHX_HOST=localhost

Generate the database password with openssl rand -hex 32. Compose rejects a missing or blank value. PostgreSQL is reachable only by services on the Compose network and does not publish a host port. Standalone deployments outside Compose can continue to configure DATABASE_URL instead.

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.

Upgrading an existing Compose database

PostgreSQL applies POSTGRES_PASSWORD only when creating a new data volume. Existing deployments must rotate the current database role password through their established database-administration and secret-management process before switching to this version, then set the same value as POSTGRES_PASSWORD in the new .env.

Back up the database before the upgrade. Do not delete the pgdata volume because it contains the existing Aludel data.

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