Start here

Open-source Core

Deploy open-source Core on a server you control.

This deploys open-source Core on a production server you manage.

You are responsible for deployment, upgrades, configuration, and day-to-day operations across each environment you maintain: dev, staging, production, and beyond.

Deployment guides

Use Docker Compose on a Linux VM you control, such as a Droplet, an EC2 instance, or a GCE or Azure VM.

Provision Postgres and Redis before you start these steps.

Write the configuration

Point Core at your Postgres and Redis, and set a secret key in blnk.json or in environment variables.

More tuning options are in Data stores, and if you keep secrets in a manager, write them into .env on the VM before you start Compose.

{
  "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

Add the Compose file

This file runs the server and the worker against the managed Postgres and Redis from the step above.

version: "3.8"

services:
  server:
    image: ${BLNK_IMAGE:-ghcr.io/blnkfinance/blnk:0.15.6}
    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.6}
    container_name: worker
    restart: on-failure
    entrypoint: ["blnk", "workers"]
    env_file:
      - .env
    ports:
      - "5004:5004"
    volumes:
      - ./blnk.json:/blnk.json

Start Core

From the directory that holds the Compose file:

docker compose up -d
docker ps

The server should be listening on port 5001, and docker ps lists the server and the worker.

Deploy Core on a platform such as Railway, Render, or Fly.io.

Provision managed Postgres and managed Redis in the project, or any databases the platform can reach.

Set the environment variables

Add these to the project. More tuning options are in Data stores.

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

Deploy the server

Create a service from ghcr.io/blnkfinance/blnk:0.15.6.

The start command is blnk migrate up && blnk start, and the port is 5001.

Attach the environment variables from the previous step, publish port 5001, and wait until the logs show that migrations finished.

Deploy the worker

Create a second service from the same image and the same environment variables.

The start command is blnk workers.

The worker does not need a public HTTP port.

Check the server

Send a request to the public URL:

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

A healthy response means Core is up. The worker should be running in its own logs.

Blnk publishes Kubernetes manifests in the repository.

From a clone of that repository, with kubectl pointed at your cluster, apply the manifests.

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

Core comes up from those manifests, including the server and the worker.

Connect to the dashboard

Open-source Core does not include the dashboard. Connect this Core to a Blnk Cloud workspace when you want one.

Create an instance

In the workspace, go to Settings → Instances and click Deploy an instance.

Settings, Instances, with Deploy an instance

Enter the Core details

Instance name: a name you will recognize, such as Production
Core URL: the public URL of this Core, such as https://api.yourcompany.com
Core secret key: the secret_key from the Core configuration. Leave it empty and the dashboard can only read the ledger.

The Core URL has to be reachable from Blnk Cloud. We recommend using a tunnel like ngrok or Cloudflare Tunnel to expose your Core to the internet.

Instance form with name, Core URL, and secret key

Submit the form.

Run the query agent

Go to Settings → Instances, open the instance, and click View setup details. Copy the Docker command. It already includes the connection key.

Replace <YOUR_DATABASE_URL> with data_source.dns from the Core configuration, and set sslmode to match the database.

Query agent setup with the Docker command

Check the connection

When the query agent is running, the instance updates to Connected.

Instance details after the connection is Connected

FAQs

What support is included?

Open-source Core includes community support and the documentation.

If you want Blnk engineers to work with your team on ledger design, integration, and production issues, get Pro Support. That includes a private Slack channel.

Should I use the Compose file in the repository?

No. That file is the local stack, and it starts its own Postgres and Redis. This guide expects Postgres and Redis you provision before the steps.

Does the dashboard connection move my database?

No. The database stays on your network. The query agent is the connection between that database and Blnk Cloud.