Barrel
FR GitHub

Install

This page tells you what to install for each way of running Barrel: the barrel library from Hex for an Erlang application, the Docker image or a release tarball of barrel_server, the umbrella build when you want the server from source, and a local build of barrel-lite for the browser. Read it before a quickstart if your machine has never run Barrel.

Requirements

What you need depends on the mode you run. Each item below says what it is for, so you can skip what your mode does not use.

  • Erlang/OTP 26 or later, and rebar3. Barrel is written in Erlang, so the library and the server need the Erlang runtime. The browser client does not, but it syncs with a server that does. rebar3 is the Erlang build tool: it fetches dependencies from Hex and compiles them.
  • CMake and a C/C++ compiler. Parts of Barrel are native code that is compiled on your machine: RocksDB (the storage engine that writes documents to disk), the vector store and the ngram index.
  • git, for the server from source: you clone the Barrel repository to build barrel_server. The Docker image and the release tarballs need neither Erlang nor a compiler.
  • Node.js 20 or later and npm, for the browser client: you build barrel-lite with them and add it to your web app.
  • Optional, for local embeddings: Python 3 (the local provider) or a running Ollama. An embedding is the list of numbers that lets Barrel search text by meaning; these compute it on your machine instead of calling a cloud API. See Choose an embedding provider.

Add barrel to an Erlang project

Use this when your application is written in Erlang or Elixir and Barrel runs inside it, the embedded mode. Every library is on Hex, the package registry for Erlang and Elixir. Add barrel to rebar.config:

{deps, [{barrel, "~> 1.14"}]}.

Add it to your application's applications list in src/*.app.src, so it starts with your application, then fetch and build:

rebar3 compile

Add a library on its own when you need only that part, for example {barrel_docdb, "~> 3.1"} for documents and replication without vectors, or {barrel_ngram, "~> 0.11"} for substring search.

Set where data goes, in config/sys.config. data_dir is the directory where documents are written to disk:

[{barrel_docdb, [{data_dir, "data/docdb"}]}].

The default is data/barrel_docdb, relative to the current directory.

Run the server from its image

Use this when clients reach Barrel over HTTP or MCP and you do not want to build it. Each Barrel release publishes a barrel_server image for amd64 and arm64, with the filesystem and S3 attachment backends:

docker run -p 8080:8080 -v barrel-data:/data \
  -e BARREL_AUTH_TOKENS=secret ghcr.io/barrel-db/barrel-server:2026.11.9

Pin a release tag such as 2026.11.9 in production; latest follows the newest release. Run barrel in Docker lists the settings and how to mount your own configuration.

Run the server from a release tarball

Each Barrel release also attaches a barrel_server tarball for Linux x64, Linux arm64 and macOS arm64. It carries its own Erlang runtime:

mkdir barrel && tar xzf barrel_server-2026.11.9-linux-x64.tar.gz -C barrel
barrel/bin/barrel_server foreground

Download it from the release page, or with gh release download v2026.11.9 --repo barrel-db/barrel. See Releases.

Build the server from the umbrella

Use this when you change the server or need a build the releases do not ship. barrel_server is built from the umbrella, the Barrel repository that holds all the libraries. It is behind the server profile, a named build configuration, and is not in the default build.

git clone https://github.com/barrel-db/barrel.git
cd barrel
rebar3 as server compile

To build a release instead, a self-contained directory you can copy to a machine and start:

rebar3 as server,prod release -n barrel_server

Quickstart: server starts it.

Optional parts

These add features most setups do not need. Install them only when you use the feature.

PartHow
FAISS vector backendrebar3 as faiss compile, with a system FAISS library
S3 attachments (barrel_att_s3)rebar3 as s3 compile, or the Hex package
Reranking (barrel_rerank)Python 3 with transformers and torch

Build barrel-lite

Use this when a web app keeps its own copy of the data. barrel-lite is not published to npm, so you build it from the umbrella:

cd barrel/clients/barrel-lite
npm ci
npm run build

Then add it to your web app from that directory:

npm install /path/to/barrel/clients/barrel-lite

Quickstart: browser uses it.

Notes

  • Without vectordb => #{db_path => ...}, a database puts its vector store next to its documents, in <data_dir>/<name>.vectordb. A store created before barrel 1.13.0 in ./priv/barrel_vectordb_<name> under the current directory stays there; set db_path to move it.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open