# How to Build a Docker Image for Colibri: A Complete Guide

> Learn how to build a Docker image for Colibri with this complete guide. Automate the build process from source using the provided Dockerfile for a production-ready image.

- Repository: [Vincenzo Fornaro/colibri](https://github.com/JustVugg/colibri)
- Tags: how-to-guide
- Published: 2026-09-12

---

**Colibri provides a production-ready Dockerfile at `docker/Dockerfile` that automates building the entire project from source inside a Debian-based container, requiring only a single `docker build` command to generate a runnable image.**

The JustVugg/colibri repository includes everything needed to containerize the application. By leveraging the official Dockerfile and its automated build scripts, you can create a Docker image for Colibri that compiles the runtime from source and produces an executable binary ready for deployment.

## Understanding the Colibri Dockerfile Structure

The Dockerfile performs a multi-stage build process starting from a minimal base. According to the source code in `docker/Dockerfile`, the build process follows three distinct phases to ensure a fully compiled environment.

### Base Image and System Dependencies (Lines 1–5)

The container definition starts from `debian:stable-slim` to minimize image size while maintaining compatibility. Lines 1–5 of `docker/Dockerfile` install the essential compilation toolchain, including `git`, `build-essential`, and Python 3 with pip. These dependencies support the subsequent build steps that compile the Colibri binary from source.

### Source Acquisition and Build Execution (Lines 9–14)

Lines 9–12 clone the official repository into `/app` and set the working directory to the cloned source. Line 14 executes the repository's [`setup.sh`](https://github.com/JustVugg/colibri/blob/main/setup.sh) script followed by `./coli build`, which compiles the project and prepares the runtime components. This approach ensures the resulting image contains a fully built Colibri binary located at `/app/c/coli`, ready for immediate execution.

## Step-by-Step: Build the Docker Image for Colibri

Follow these commands to generate your image from the official Dockerfile.

1. **Clone the repository (optional but recommended).**

   ```bash
   git clone https://github.com/JustVugg/colibri.git
   cd colibri
   ```

2. **Execute the Docker build command.**

   Run the build from the repository root to ensure correct context:

   ```bash
   docker build -f docker/Dockerfile -t colibri:latest .
   ```

   - `-f docker/Dockerfile` specifies the path to the Dockerfile.
   - `-t colibri:latest` assigns a tag for easy reference.

3. **Verify the built image.**

   Test that the Colibri binary functions correctly inside the container:

   ```bash
   docker run --rm -it colibri:latest /app/c/coli --help
   ```

## Docker Compose Alternative for Colibri

For orchestration scenarios or when managing multiple services, use the companion [`docker-compose.yml`](https://github.com/JustVugg/colibri/blob/main/docker-compose.yml) file located at [`docker/docker-compose.yml`](https://github.com/JustVugg/colibri/blob/main/docker/docker-compose.yml). From the repository root:

```bash
docker compose -f docker/docker-compose.yml up --build

```

This command builds the image if not already present and starts the container as a defined service. You can customize the compose configuration to mount volumes for model directories, set environment variables, or expose network ports as required by your deployment.

## Summary

- The `docker/Dockerfile` in JustVugg/colibri uses `debian:stable-slim` as its foundation for minimal image size.
- Lines 1–5 install build dependencies including `git` and `build-essential`; lines 9–14 handle repository cloning and compilation via [`setup.sh`](https://github.com/JustVugg/colibri/blob/main/setup.sh) and `./coli build`.
- Build the image using `docker build -f docker/Dockerfile -t colibri:latest .` from the repository root.
- The compiled binary is available at `/app/c/coli` inside the container, accessible via `docker run`.
- Optional orchestration is available through [`docker/docker-compose.yml`](https://github.com/JustVugg/colibri/blob/main/docker/docker-compose.yml) for service management.

## Frequently Asked Questions

### What base image does the Colibri Dockerfile use?

The Dockerfile uses `debian:stable-slim` as its foundation. Lines 1–5 of `docker/Dockerfile` install the compilation toolchain including `git`, `build-essential`, and Python 3 to support the build process.

### How do I run the Colibri binary after building the Docker image?

Execute `docker run --rm -it colibri:latest /app/c/coli --help` to verify the build. Replace `--help` with your desired Colibri commands, and use volume mounts (`-v /host/path:/container/path`) to provide access to external files or models.

### Can I build the Colibri Docker image without cloning the repository locally?

Yes, you can build directly from the GitHub URL using `docker build -t colibri:latest https://github.com/JustVugg/colibri.git#main:docker`, though cloning first allows easier customization of build arguments and inspection of the [`pyproject.toml`](https://github.com/JustVugg/colibri/blob/main/pyproject.toml) dependencies.

### Where is the Colibri CLI entry point defined in the source code?

While the compiled binary resides at `/app/c/coli` in the container according to the Dockerfile build process, the Python source implementation is located at [`colibri/cli.py`](https://github.com/JustVugg/colibri/blob/main/colibri/cli.py), with package metadata and dependencies declared in [`pyproject.toml`](https://github.com/JustVugg/colibri/blob/main/pyproject.toml) at the repository root.