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 OpenAI, Anthropic, or Google Gemini if you are not using only Ollama

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.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 options such as :resolver, :on_mount, :socket_path, :transport, and :logo_path if your host app needs custom auth or routing behavior.

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")

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.

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 sample prompts, providers, and suites:

mix aludel.seed

4. Start the server

mix phx.server

Access at http://localhost:4000.

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=...
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=...
# Ollama: no API key required

Verification

mix test
mix precommit

Next Steps

• Quick Start
• Providers
• Architecture