Install on Linux

Option 1: Docker Compose on CPU

Install Docker Engine and the Compose plugin for your distribution. The following commands assume your user can access Docker.

git clone https://github.com/dzenplatform/embedder.git
cd embedder
docker compose up -d
docker compose ps -a
docker compose logs -f model-init embedder

Compose downloads the CPU image and model. It is normal for model-init to exit with code 0; embedder starts after that step succeeds. Press Ctrl+C to stop following logs without stopping the container.

The API listens at http://127.0.0.1:8091. The CPU image supports Linux amd64 and arm64. Compose defaults to the versioned tag 0.1.0-cpu; use EMBEDDER_TAG in .env to select another tag.

Option 2: Docker Compose with an NVIDIA GPU

Install a compatible NVIDIA host driver and check that nvidia-smi detects your GPU. Install the NVIDIA Container Toolkit using NVIDIA's instructions, then configure Docker:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
nvidia-smi

Schedule the Docker restart around other running containers. From the repository directory, use the CUDA variant instead of the CPU command:

docker compose -f compose.yaml -f compose.cuda.yaml up -d
docker compose -f compose.yaml -f compose.cuda.yaml logs -f model-init embedder

This uses 0.1.0-cu126 for Linux amd64 and reserves GPU 0. Set, for example, GPU_DEVICE_ID=1 in .env to choose a different card. If you previously set a CPU tag in EMBEDDER_TAG, remove that override or replace it with the CUDA tag.

The image contains PyTorch 2.6.0 with CUDA 12.6. Compatibility depends on the GPU and driver: a CUDA tag does not guarantee support for every NVIDIA card. These images do not provide CUDA arm64 or Jetson variants.

Option 3: Native Python

The preparation commands below target Ubuntu/Debian. On other distributions, install Git, make, and curl through your package manager.

sudo apt-get update
sudo apt-get install -y git make curl
curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal so uv is available on PATH, then run:

uv --version
git clone https://github.com/dzenplatform/embedder.git
cd embedder
DEVICE=cpu make setup
DEVICE=cpu make run

make setup creates venv/, installs dependencies, and downloads the model. On Linux CPU, the setup script installs a CPU-only PyTorch build. Keep the server running in this terminal and use a second terminal to test the API.

For NVIDIA, first check your driver with nvidia-smi, then use these commands instead of the CPU commands:

DEVICE=cuda make setup
DEVICE=cuda make run

The native CUDA setup script installs PyTorch from the cu126 index by default and checks torch.cuda.is_available(). Native inference does not require NVIDIA Container Toolkit.

To persist the device choice, add or update this field in local.yaml at the repository root:

device: cuda

You can then use make setup and make run without an environment override. DEVICE takes precedence over YAML.

Start automatically with systemd

Docker Compose already uses restart: unless-stopped. For native Linux deployments, the repository provides systemd units that expect a checkout at /var/www/dzen-embedder and a user and group named deploy.

An administrator must create deploy if it does not exist and give it ownership of the checkout directory. As that user, clone the repository into /var/www/dzen-embedder, install uv, and run DEVICE=cpu make setup or DEVICE=cuda make setup.

From /var/www/dzen-embedder, install the appropriate unit. The script requires sudo:

# CPU
bash deploy/systemd/install.sh cpu

# For NVIDIA, use this instead:
# bash deploy/systemd/install.sh gpu

sudo systemctl status embedder.service
sudo journalctl -u embedder.service -f

When switching an existing service between CPU and GPU, prepare dependencies, install the new unit, and explicitly run sudo systemctl restart embedder.service. Installing a unit does not restart an already active process. Each unit pins DEVICE independently of local.yaml.

Stop and verify

Use docker compose stop for containers, adding both -f arguments for CUDA as in the start command. Stop a foreground native process with Ctrl+C, or a systemd service with sudo systemctl stop embedder.service.

Check readiness and request your first vector →

Source configuration: Compose, CUDA override, and setup script.