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-litewith them and add it to your web app. - Optional, for local embeddings: Python 3 (the
localprovider) 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.
| Part | How |
|---|---|
| FAISS vector backend | rebar3 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; setdb_pathto move it.