Installation

Arcana requires PostgreSQL with the pgvector extension and an Nx backend for local embeddings. This guide covers installation with Igniter (recommended) and manual setup.

Prerequisites

Elixir 1.14+ and Phoenix 1.7+
PostgreSQL 12+ with pgvector extension
An Nx backend (EXLA, EMLX, or Torchx) for local embeddings

Installation Methods

With Igniter (Recommended)
Manual Installation

Install with Igniter

The easiest way to install Arcana is using Igniter, which automatically configures your application:

mix igniter.install arcana
mix ecto.migrate

This command will:

Add the arcana dependency to mix.exs
Create database migrations for documents and chunks
Configure Postgrex types for pgvector
Set up your repo configuration
Optionally mount the LiveView dashboard

You’ll still need to set up PostgreSQL with pgvector and configure an Nx backend (see below).

Manual Installation

If you prefer manual setup or don’t use Igniter:

Add dependency

Add arcana to your mix.exs dependencies:

mix.exs

def deps do
  [
    {:arcana, "~> 1.0"}
  ]
end

Then fetch dependencies:

mix deps.get

Run installer

Run the Arcana installer to generate migrations:

mix arcana.install
mix ecto.migrate

Configure Postgrex types

Create a Postgrex types module to support pgvector:

lib/my_app/postgrex_types.ex

Postgrex.Types.define(
  MyApp.PostgrexTypes,
  [Pgvector.Extensions.Vector] ++ Ecto.Adapters.Postgres.extensions(),
  []
)

Add it to your repo configuration:

config/config.exs

config :my_app, MyApp.Repo,
  types: MyApp.PostgrexTypes

(Optional) Mount dashboard

To use the LiveView dashboard, mount it in your router:

lib/my_app_web/router.ex

scope "/arcana" do
  pipe_through [:browser]
  forward "/", ArcanaWeb.Router
end

In production, protect the dashboard with authentication by adding an :admin or :require_authenticated_user pipe.

Database Setup

PostgreSQL with pgvector

Arcana requires PostgreSQL with the pgvector extension for vector similarity search.

Start PostgreSQL with pgvector

The easiest way is using Docker with the official pgvector image:

docker-compose.yml

services:
  postgres:
    image: pgvector/pgvector:pg16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp_dev
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Start the database:

docker compose up -d

Run migrations

The Arcana installer creates migrations for:

arcana_documents - Stores document metadata and content
arcana_chunks - Stores text chunks with embeddings
arcana_collections - Organizes documents into named collections
pgvector extension activation

Apply them:

mix ecto.migrate

(Optional) Install pgvector locally

For local PostgreSQL installations without Docker:

brew install pgvector

Then enable it in your database:

CREATE EXTENSION IF NOT EXISTS vector;

Supervision Tree Setup

Add Arcana components to your application’s supervision tree:

lib/my_app/application.ex

def start(_type, _args) do
  children = [
    MyApp.Repo,
    MyAppWeb.Endpoint,
    Arcana.TaskSupervisor,  # Required for dashboard async operations
    Arcana.Embedder.Local   # Only if using local Bumblebee embeddings
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

Arcana.TaskSupervisor is required if you’re using the dashboard’s Ask or Maintenance features
Arcana.Embedder.Local is only needed when using local Bumblebee embeddings (the default)
For OpenAI or other cloud embeddings, you can skip Arcana.Embedder.Local

Nx Backend Configuration

For local embeddings, Arcana needs an Nx backend to run neural network models. Choose one based on your platform:

EXLA (Recommended)
EMLX (Apple Silicon)
Torchx

EXLA - Google’s XLA Compiler

Best performance on most platforms (Linux, macOS, Windows).

Add dependency

mix.exs

def deps do
  [
    {:arcana, "~> 1.0"},
    {:exla, "~> 0.9"}
  ]
end

Configure Nx

config/config.exs

config :nx,
  default_backend: EXLA.Backend,
  default_defn_options: [compiler: EXLA]

Install dependencies

mix deps.get

First run will download and compile XLA (may take a few minutes).

EMLX - Apple’s MLX Framework

Optimized for macOS with Apple Silicon (M1/M2/M3).

Add dependency

mix.exs

def deps do
  [
    {:arcana, "~> 1.0"},
    {:emlx, "~> 0.1"}
  ]
end

Configure Nx

config/config.exs

config :nx,
  default_backend: EMLX.Backend,
  default_defn_options: [compiler: EMLX]

Install dependencies

mix deps.get

EMLX only works on macOS with Apple Silicon. For Intel Macs, use EXLA.

Torchx - PyTorch Backend

No compilation required, uses eager execution.

Add dependency

mix.exs

def deps do
  [
    {:arcana, "~> 1.0"},
    {:torchx, "~> 0.9"}
  ]
end

Configure Nx

config/config.exs

# For CPU
config :nx,
  default_backend: {Torchx.Backend, device: :cpu}

# For Apple Silicon GPU acceleration
config :nx,
  default_backend: {Torchx.Backend, device: :mps}

Install dependencies

mix deps.get

Embedding Provider Configuration

Arcana supports multiple embedding providers. Choose based on your needs:

Local Embeddings (Default)

Use Bumblebee for local embeddings - no API keys required:

config/config.exs

# Default - BGE Small (384 dimensions, 133MB)
config :arcana, embedder: :local

# Or specify a model
config :arcana, embedder: {:local, model: "BAAI/bge-base-en-v1.5"}

Local embeddings require an Nx backend (configured above).

Available Local Models

Model	Dimensions	Size	Use Case
`BAAI/bge-small-en-v1.5`	384	133MB	Default, good balance
`BAAI/bge-base-en-v1.5`	768	438MB	Better accuracy
`BAAI/bge-large-en-v1.5`	1024	1.3GB	Best accuracy
`intfloat/e5-small-v2`	384	133MB	Alternative to BGE
`intfloat/e5-base-v2`	768	438MB	E5 medium size
`intfloat/e5-large-v2`	1024	1.3GB	E5 best accuracy
`thenlper/gte-small`	384	67MB	Smallest, fastest

E5 models require special query:/passage: prefixes. Arcana handles this automatically.

OpenAI Embeddings

Use OpenAI’s embedding API:

config/config.exs

config :arcana, embedder: :openai

# Or specify a model
config :arcana, embedder: {:openai, model: "text-embedding-3-large"}

Set your API key:

export OPENAI_API_KEY="sk-..."

When using OpenAI embeddings, you don’t need an Nx backend or Arcana.Embedder.Local in your supervision tree.

Custom Embeddings

Implement the Arcana.Embedder behaviour for custom providers (Cohere, Voyage, etc.):

lib/my_app/cohere_embedder.ex

defmodule MyApp.CohereEmbedder do
  @behaviour Arcana.Embedder

  @impl true
  def embed(text, _opts) do
    # Call Cohere API
    case Req.post("https://api.cohere.ai/v1/embed", 
      json: %{texts: [text], model: "embed-english-v3.0"}) do
      {:ok, %{body: %{"embeddings" => [embedding]}}} ->
        {:ok, embedding}
      {:error, reason} ->
        {:error, reason}
    end
  end

  @impl true
  def dimensions(_opts), do: 1024
end

Configure it:

config/config.exs

config :arcana, embedder: MyApp.CohereEmbedder

Verify Installation

Test your installation in an IEx session:

iex -S mix

# Test ingestion
{:ok, doc} = Arcana.ingest("Elixir is a functional programming language.", repo: MyApp.Repo)

# Test search
{:ok, results} = Arcana.search("functional programming", repo: MyApp.Repo)

IO.inspect(results, label: "Search results")

You should see search results with similarity scores.

Optional: GraphRAG Setup

If you want to use GraphRAG features (entity extraction, knowledge graphs):

mix arcana.graph.install
mix ecto.migrate

This creates additional tables for entities, relationships, and communities. Enable GraphRAG during ingestion:

Arcana.ingest("Your content", repo: MyApp.Repo, graph: true)

Next Steps

Quickstart Tutorial

Build your first RAG application with a complete example

Configure Chunking

Learn how to optimize text chunking for your use case

LLM Integration

Connect Arcana to OpenAI, Anthropic, or custom LLMs

Dashboard Setup

Set up the LiveView dashboard for document management

Troubleshooting

pgvector extension not found

If you see errors about the vector extension:

Make sure you’re using the pgvector/pgvector Docker image, or
Install pgvector on your local PostgreSQL installation
Run CREATE EXTENSION IF NOT EXISTS vector; in your database

Nx backend compilation errors

If EXLA fails to compile:

Make sure you have build tools installed (gcc, make)
On macOS: xcode-select --install
On Ubuntu: sudo apt install build-essential
Try Torchx as an alternative: {:torchx, "~> 0.9"}

Model download is slow

First time using local embeddings downloads models from HuggingFace:

BGE Small: ~133MB
BGE Base: ~438MB
BGE Large: ~1.3GB

Subsequent runs use cached models. The download only happens once.

Postgrex types error

If you see errors about vector types not being recognized:

Ensure you created the PostgrexTypes module
Added it to your repo config: types: MyApp.PostgrexTypes
Restarted your application after config changes

Getting Started

Core Concepts

Guides

Configuration

Installation

Installation

Prerequisites

Installation Methods

Install with Igniter

Manual Installation

Database Setup

PostgreSQL with pgvector

Supervision Tree Setup

Nx Backend Configuration

EXLA - Google’s XLA Compiler

EMLX - Apple’s MLX Framework

Torchx - PyTorch Backend

Embedding Provider Configuration

Local Embeddings (Default)

Available Local Models

OpenAI Embeddings

Custom Embeddings

Verify Installation

Optional: GraphRAG Setup

Next Steps

Quickstart Tutorial

Configure Chunking

LLM Integration

Dashboard Setup

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Configuration

​Installation

​Prerequisites

​Installation Methods

​Install with Igniter

​Manual Installation

​Database Setup

​PostgreSQL with pgvector

​Supervision Tree Setup

​Nx Backend Configuration

​EXLA - Google’s XLA Compiler

​EMLX - Apple’s MLX Framework

​Torchx - PyTorch Backend

​Embedding Provider Configuration

​Local Embeddings (Default)

​Available Local Models

​OpenAI Embeddings

​Custom Embeddings

​Verify Installation

​Optional: GraphRAG Setup

​Next Steps

Quickstart Tutorial

Configure Chunking

LLM Integration

Dashboard Setup

​Troubleshooting

Build docs developers (and LLMs) love

Installation

Prerequisites

Installation Methods

Install with Igniter

Manual Installation

Database Setup

PostgreSQL with pgvector

Supervision Tree Setup

Nx Backend Configuration

EXLA - Google’s XLA Compiler

EMLX - Apple’s MLX Framework

Torchx - PyTorch Backend

Embedding Provider Configuration

Local Embeddings (Default)

Available Local Models

OpenAI Embeddings

Custom Embeddings

Verify Installation

Optional: GraphRAG Setup

Next Steps

Troubleshooting