From Zero to Production: Running Uteke in Docker

From Zero to Production: Running Uteke in Docker

Uteke runs as a single binary, but for production deployments you want containerization. Docker gives you reproducible builds, easy scaling, and clean separation from the host system. This guide covers what we learned deploying Uteke to production.

Why Docker for a Single Binary

Even though Uteke is a self-contained binary, Docker provides several practical benefits: pinned runtime versions, consistent behavior across environments, easy health checks via HTTP endpoints, and straightforward orchestration with Docker Compose or Kubernetes.

Basic Dockerfile

The official Uteke Docker image is available on GitHub Container Registry. It uses a minimal base image (debian-slim) with just enough dependencies to run the binary. The image is typically under 50MB.

If you need a custom build, start from the binary release and add it to a scratch or distroless base image. The Uteke binary has no dynamic dependencies beyond libc.

Configuration

Uteke reads configuration from environment variables. The key ones for production are the API token for authentication, the data directory path for persistent storage, and the host/port binding.

• UTKE_TOKEN: API authentication token
• UTKE_DATA_DIR: persistent storage path (mount a volume)
• UTKE_HOST: bind address (0.0.0.0 for Docker)
• UTKE_PORT: HTTP port (default 8767)

Docker Compose Setup

A typical Docker Compose file mounts a persistent volume for the data directory, sets the API token from an environment file, and exposes the health check endpoint. Keep the token out of the compose file itself — use .env or your secrets manager.

Health Checks

Uteke exposes a health endpoint that returns OK when the server is ready. Configure your container orchestrator to poll this endpoint. A typical health check interval is 10 seconds with a 3-second timeout.

Persistence

The SQLite database and HNSW index files live in the data directory. Mount this as a Docker volume to persist data across container restarts. Without a volume mount, all memories are lost when the container is recreated.

What We Learned

Start with generous memory limits — HNSW indices grow with your dataset. Monitor disk usage on the data volume. And always back up the data directory before upgrading Uteke versions.

Docker images and deployment examples are in the Uteke GitHub repository.