Deploy the Open-Source Blnk Core

Self-host the open-source Blnk Core in infrastructure your team controls. You are responsible for deployment, upgrades, configuration, and day-to-day operations across each environment you maintain-dev, staging, production, and beyond. To upgrade Core safely across versions, see Upgrade Blnk Core.

0.15.3 and later: use ghcr.io/blnkfinance/blnk:<version>.0.15.2 and earlier: use jerryenebeli/blnk:<version>.

Deployment guide

There are three ways to self-host Blnk Core in your environment:

Single server: Use Docker Compose on a Linux VM you control, e.g. a DO Droplet, EC2, GCE, or Azure VM.
Platform-as-a-Service (PaaS): Use a platform hosting service like Railway, Render, Fly.io, etc.
Kubernetes: Use Kubernetes to deploy Blnk Core.

Single server
PaaS (Railway, etc.)
Kubernetes

Use Docker Compose on a Linux VM you control; for example a DO Droplet, EC2, GCE, or Azure VM.Before you start, make sure you have the following set up (required):

Managed PostgreSQL instance
Managed Redis instance
Docker and Docker Compose installed
Linux server (Ubuntu 20.04 LTS or newer recommended)

Set up your configuration file

This is the configuration file that will be used to start the Blnk Core, it can be the blnk.json file or environment variables.For more options, go to Blnk Configuration.

{
  "project_name": "Blnk",
  "data_source": {
    "dns": "postgres://<user>:<password>@<host>:5432/blnk?sslmode=require"
  },
  "redis": {
    "dns": "redis://:<password>@<host>:6379"
  },
  "server": {
    "secure": true,
    "secret_key": "set-your-master-blnk-key-here",
    "port": "5001"
  },
  "queue": {
    "monitoring_port": "5004"
  }
}

BLNK_PROJECT_NAME=Blnk
BLNK_DATA_SOURCE_DNS='postgres://<user>:<password>@<host>:5432/blnk?sslmode=require'
BLNK_REDIS_DNS='redis://:<password>@<host>:6379'
BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY='set-your-master-blnk-key-here'
BLNK_SERVER_PORT=5001
BLNK_QUEUE_MONITORING_PORT=5004

If you use a secrets manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, etc.), fetch secrets onto the VM and write them to .env before you run docker compose up.

Create a 'docker-compose.yml' file

Add the following configuration to provision the server, worker, and supporting services if needed. You can use the default docker-compose.yml file in the Blnk repository.

For live deployments, we recommend connecting your managed Postgres and Redis databases. This means you can exclude the redis and postgres services from your docker-compose.yaml file.

docker-compose.yaml

version: "3.8"

services:
  server:
    image: ${BLNK_IMAGE:-ghcr.io/blnkfinance/blnk:0.15.3}
    container_name: server
    restart: on-failure
    entrypoint: ["/bin/sh", "-c"]
    command:
      - "blnk migrate up && blnk start"
    environment:
      TZ: ${TZ:-Etc/UTC}
    env_file:
      - .env
    ports:
      - "5001:5001"
      - "80:80"
      - "443:443"
    volumes:
      - ./blnk.json:/blnk.json

  worker:
    image: ${BLNK_IMAGE:-ghcr.io/blnkfinance/blnk:0.15.3}
    container_name: worker
    restart: on-failure
    entrypoint: ["blnk", "workers"]
    env_file:
      - .env
    ports:
      - "5004:5004"
    volumes:
      - ./blnk.json:/blnk.json

Start deployment

Run these commands in your terminal to start and validate your deployment:

# Start all services
docker compose up -d

# Verify deployment status
docker ps

# Monitor service logs
docker logs -f server worker

Blnk should be running and accessible at port 5001 and available for requests.

Deploy Blnk Core on a platform hosting service like Railway, Render, or Fly.io.

Set up Postgres and Redis

In your project, provision a managed PostgreSQL database and a managed Redis instance if you do not already have them.You can also connect to a third-party database if you prefer. Make sure that the database and Redis are reachable from the platform.Copy each connection string from your provider. You will use them in the next step.

If Postgres and Redis run in the same project as Blnk, use the provider’s internal connection URLs for lower latency and to avoid public network egress.

Set environment variables

Add these environment variables to your project. Use your managed Postgres and Redis connection strings.

.env

BLNK_PROJECT_NAME=Blnk
BLNK_DATA_SOURCE_DNS='postgres://<user>:<password>@<host>:5432/blnk?sslmode=require'
BLNK_REDIS_DNS='redis://:<password>@<host>:6379'
BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY='set-your-master-blnk-key-here'
BLNK_SERVER_PORT=5001
BLNK_QUEUE_MONITORING_PORT=5004

You can add more environment variables later as you need, go to Blnk Configuration.

Use the direct Postgres connection string, not a pooled URL, if your provider offers both.

Deploy the server

Create a service from the Blnk Docker image:

Docker image: ghcr.io/blnkfinance/blnk:0.15.3
Start command: blnk migrate up && blnk start
Port: 5001

Connect this service to the environment variables from the previous step, or copy them into the service settings.Point the server public URL to port 5001 to make it accessible from outside the project.Deploy the server and wait for migrations to finish in the logs.

Deploy the worker

Create a second service using the same Docker image and the same environment variables as the server.

Docker image: ghcr.io/blnkfinance/blnk:0.15.3
Start command: blnk workers

The worker does not need a public HTTP port. Optionally, point its public URL to port 5004 if you want to access the monitoring dashboard.Deploy the worker once you’re done.

Verify deployment

Check the server logs for a successful migration and startup. Send a request to your service URL:

curl https://<your-server-url>/health

Confirm the worker service is running in its logs.

Blnk should now be running and accessible on your platform’s public URL.

Blnk provides Kubernetes manifests to help you deploy and operate Blnk in containerized environments.Use the official manifests and instructions:

infrastructure/k8s-manifests

Official manifests and deploy steps.

After kubectl is installed, run:

kubectl

kubectl apply -f infrastructure/k8s-manifests/namespace.yaml
kubectl apply -f infrastructure/k8s-manifests

Back-office management

Once your Blnk Core is deployed in your own environment, you can connect it to a Blnk Cloud account to operate your ledger from a back-office dashboard.

Connect Core to Blnk Cloud

Self-hosted Core connected to Cloud.

Monitoring

Use Blnk Cloud for monitoring

Setting up monitoring

We recommend connecting to Blnk Cloud to set up monitoring for your Core in less than 5 minutes. See Quick setup: Blnk Cloud. To manually export logs, traces, and metrics for your local deployment:

Enable observability in Core

Enable observability in your configuration file:

BLNK_ENABLE_OBSERVABILITY=true

{
  "enable_observability": true
}

Restart server and worker after you finish the compose changes below.

Add Prometheus config

Create prometheus.yml beside your compose file:

prometheus.yml

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'blnk-server'
    authorization:
      type: Bearer
      credentials: '<metrics-bearer-token>'
    static_configs:
      - targets: ['server:5001']
  - job_name: 'blnk-worker'
    authorization:
      type: Bearer
      credentials: '<metrics-bearer-token>'
    static_configs:
      - targets: ['worker:5004']

Add Jaeger and Prometheus services

Update your docker-compose.yaml to include Jaeger and Prometheus. This example extends the base compose with trace export on server and worker:

docker-compose.yaml

version: "3.8"

services:
  server:
    image: ${BLNK_IMAGE:-ghcr.io/blnkfinance/blnk:0.15.3}
    container_name: server
    restart: on-failure
    entrypoint: ["/bin/sh", "-c"]
    command:
      - "blnk migrate up && blnk start"
    environment:
      TZ: ${TZ:-Etc/UTC}
      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: http://jaeger:4318/v1/traces
    env_file:
      - .env
    ports:
      - "5001:5001"
      - "80:80"
      - "443:443"
    depends_on:
      - jaeger
    volumes:
      - ./blnk.json:/blnk.json

  worker:
    image: ${BLNK_IMAGE:-ghcr.io/blnkfinance/blnk:0.15.3}
    container_name: worker
    restart: on-failure
    entrypoint: ["blnk", "workers"]
    environment:
      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: http://jaeger:4318/v1/traces
    env_file:
      - .env
    ports:
      - "5004:5004"
    depends_on:
      - jaeger
    volumes:
      - ./blnk.json:/blnk.json

  jaeger:
    image: jaegertracing/all-in-one:latest
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4318:4318"
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:16686"]
      interval: 10s
      timeout: 5s
      retries: 3

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    profiles:
      - monitoring
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    depends_on:
      - server
      - worker

Start or restart the stack

Run docker compose --profile monitoring up -d to start Core, Jaeger, and Prometheus together.Open Jaeger at http://localhost:16686 and Prometheus at http://localhost:9090 to confirm data is flowing.To learn more, see Monitoring in Blnk.

Troubleshooting

Use this guide to troubleshoot your deployment when Blnk fails to start or you experience errors in your deployment.

Server fails to start or cannot reach PostgreSQL

Common symptoms: Connection refused or timeout errors in server logs; messages referencing data_source or BLNK_DATA_SOURCE_DNS.

Verify your connection string

Confirm BLNK_DATA_SOURCE_DNS (or data_source.dns in blnk.json) includes the correct host, port, database name, user, and password.Set sslmode to match your provider; most managed Postgres instances require sslmode=require.

Many hosted Postgres providers expose two URLs: a direct connection and a pooled connection.If Blnk keeps timing out or disconnecting under load, confirm you are using the direct connection string for BLNK_DATA_SOURCE_DNS.

See Database settings.

Check network access

Allow inbound traffic from your Blnk host to PostgreSQL. Review security groups, firewall rules, and private networking (VPC peering, subnet routing) between the container host and your database.

If Postgres is only reachable on a private network, running psql from your laptop may succeed or fail independently of the container. Test from the same network context as the Blnk server.

Test the connection

From a host on the same network as Blnk, run:

psql "$BLNK_DATA_SOURCE_DNS" -c "SELECT 1"

A successful response confirms credentials and reachability.

Migrations fail on startup

Common symptoms: The server container exits immediately; logs show errors from blnk migrate up.The Docker Compose example runs migrations before starting the API (blnk migrate up && blnk start). Migration failures prevent the server from listening on port 5001.

Confirm database permissions

The database user must be able to create and alter tables in the target database. Read-only or restricted roles cause migration failures.

Grant the application user CREATE and ALTER privileges on the blnk database (or your chosen database name).

Inspect migration logs

Read the server container output:

docker logs server

Look for the first migration error-later messages often repeat the same root cause.

Run migrations manually

Re-run migrations in the foreground to capture the full error:

docker compose run --rm server blnk migrate up

Transactions stay queued or workers are idle

Common symptoms: The API accepts requests but transactions remain QUEUED; the worker container restarts or logs Redis connection errors.Workers depend on Redis for queueing and coordination. The server and worker must share the same Redis and queue configuration.

Verify Redis connectivity

Confirm BLNK_REDIS_DNS (or redis.dns in blnk.json) points at your managed Redis instance. Include the password in the URL when required:

redis://:<password>@<host>:6379

For TLS-enabled Redis, use rediss:// and review Redis configuration.

Confirm the worker is running

Both server and worker services must be up:

docker ps
docker logs -f worker

On Kubernetes, check worker pod status and logs alongside the server deployment.

Check queue health

If you configured BLNK_QUEUE_MONITORING_PORT (default 5004), open the monitoring dashboard or probe the endpoint:

curl -s http://localhost:5004/monitoring

See Queue monitoring for dashboard details and metrics.

API is unreachable or containers keep restarting

Common symptoms: docker ps shows a restarting server or worker container; requests to port 5001 time out.

Review container status

List all containers, including stopped ones:

docker ps -a
docker logs -f server worker

Restart loops usually point to configuration, migration, or dependency errors in the logs.

Confirm port exposure

Verify port 5001 is published in docker-compose.yaml and allowed through your host firewall and cloud security groups.

curl http://localhost:5001/health (or your health endpoint) should respond when the server is healthy.

Validate configuration is loaded

When using blnk.json, confirm the file is mounted into both server and worker containers. When using environment variables, set them on both services-mismatched config between server and worker causes subtle queue issues.See Blnk configuration.

For PaaS deployments (Railway, Render, Fly.io), run the server and worker as separate services with identical configuration and the correct start commands for each.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Deployment guide

infrastructure/k8s-manifests

Back-office management

Connect Core to Blnk Cloud

Monitoring

Setting up monitoring

Troubleshooting

​Deployment guide

infrastructure/k8s-manifests

​Back-office management

Connect Core to Blnk Cloud

Monitoring

​Setting up monitoring

​Troubleshooting

Deployment guide

Back-office management

Setting up monitoring

Troubleshooting