Skip to main content
Blnk can be installed and running in minutes using Docker Compose. This guide walks through setting up a complete Blnk environment with all dependencies.

​
Prerequisites

Before installing Blnk, ensure you have the following installed:

Docker

Docker Engine 20.10+ for container runtime

Docker Compose

Docker Compose v2.0+ for orchestration
Verify your installation: 
docker --version
docker compose version
Some Docker installations use docker-compose (with hyphen) instead of docker compose. Adjust commands accordingly based on your setup.

​
Installation Steps

1

Clone the Repository

Clone the Blnk repository to your local machine:
git clone https://github.com/blnkledger/blnk && cd blnk
2

Create Configuration File

Create a blnk.json configuration file in the project root:
blnk.json
{
  "project_name": "Blnk",
  "data_source": {
    "dns": "postgres://postgres:password@postgres:5432/blnk?sslmode=disable"
  },
  "redis": {
    "dns": "redis:6379"
  },
  "server": {
    "port": "5001"
  }
}
The default configuration works out of the box with the provided docker-compose.yaml. Customize the values for your environment as needed.
3

Start Blnk Server

Launch all services using Docker Compose:
docker compose up
This starts the following services:
  • server - Blnk API server (port 5001)
  • worker - Background job processor (port 5004)
  • postgres - PostgreSQL database (port 5432)
  • redis - Redis queue backend (port 6379)
  • typesense - Search engine (port 8108)
  • jaeger - Distributed tracing (port 16686)
Add the -d flag to run in detached mode: docker compose up -d
4

Verify Installation

Once all containers are running, verify the API is accessible:
curl http://localhost:5001/
You should see:
"server running..."
Check service health:
docker compose ps
All services should show status as “Up” or “healthy”.

​
Docker Compose Configuration

The docker-compose.yaml file defines the complete Blnk stack:
docker-compose.yaml
version: "3.8"

services:
  server:
    image: jerryenebeli/blnk:0.13.2
    container_name: server
    restart: on-failure
    command: ["/bin/sh", "-c", "blnk migrate up && blnk start"]
    ports:
      - "5001:5001"
      - "80:80"
      - "443:443"
    depends_on:
      - redis
      - postgres
    volumes:
      - ./blnk.json:/blnk.json

  worker:
    image: jerryenebeli/blnk:0.13.2
    container_name: worker
    restart: on-failure
    entrypoint: ["blnk", "workers"]
    ports:
      - "5004:5004"
    depends_on:
      - redis
      - postgres
    volumes:
      - ./blnk.json:/blnk.json

  postgres:
    image: postgres:16
    container_name: postgres
    restart: on-failure
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: blnk
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7.2.4
    container_name: redis
    restart: on-failure

volumes:
  pg_data:
  • server: Runs database migrations and starts the API server
  • worker: Processes queued transactions, webhooks, and background jobs
  • postgres: Stores all ledger data with persistence via Docker volumes
  • redis: Manages job queues and caching
  • typesense: Enables fast search across balances, transactions, and ledgers
  • jaeger: Provides distributed tracing for observability (optional)

​
Environment Variables

Blnk supports configuration via environment variables. Create a .env file based on .env.example:
.env
# Docker Compose Configuration
COMPOSE_FILE=docker-compose.yaml
COMPOSE_PROJECT_NAME=blnk

# Blnk Configuration
BLNK_PROJECT_NAME=Blnk

# Server Settings
BLNK_SERVER_PORT=5001
BLNK_SERVER_SSL=false

# Database Connection
BLNK_DATA_SOURCE_DNS=postgres://postgres:password@postgres:5432/blnk?sslmode=disable

# Redis Connection
BLNK_REDIS_DNS=redis:6379

# PostgreSQL Settings
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=blnk
Security Notice: Always change default passwords in production. Use strong, randomly generated passwords for PostgreSQL and secure your Redis instance.

​
Configuration File vs Environment Variables

Blnk supports two configuration methods:
  1. Configuration File (blnk.json) - Recommended for structured configuration
  2. Environment Variables - Override file settings or configure without a file
Environment variables take precedence over blnk.json settings. All configuration file options have corresponding environment variable equivalents prefixed with BLNK_.

​
Port Reference

ServicePortDescription
API Server5001Main REST API endpoint
Workers5004Worker monitoring port
PostgreSQL5432Database connection
Redis6379Queue backend
Typesense8108Search API
Jaeger UI16686Tracing dashboard

​
Common Installation Issues

If you see errors about ports already being in use:
  1. Check what’s using the port: 
    lsof -i :5001
  2. Either stop the conflicting service or change Blnk’s port in blnk.json: 
    {
  "server": {
    "port": "5002"
  }
}
If the server can’t connect to PostgreSQL:
  1. Ensure PostgreSQL container is running: 
    docker compose ps postgres
  2. Check the database DNS in blnk.json matches your PostgreSQL container name and credentials
  3. Wait for PostgreSQL to fully initialize (can take 10-30 seconds on first start)
If you encounter permission issues with volumes:
# Linux/macOS: Ensure proper permissions
sudo chown -R $USER:$USER .

​
Next Steps

Now that Blnk is installed and running:

Quick Start

Create your first ledger, balance, and transaction

Configuration

Explore advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us