# Open-source Core

Self-host the open-source Blnk Core on a single server, a platform, or Kubernetes.

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.

<Version>
From 0.15.3, pull `ghcr.io/blnkfinance/blnk`. The current release is `0.15.6`. Releases through 0.15.2 use `jerryenebeli/blnk`.
</Version>

## Deployment guides

<Tabs>
<Tab title="Single server">

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.

<Steps titleSize="h3">
<Step title="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](/operating/configuration/data-stores), and if you keep secrets in a manager, write them into `.env` on the VM before you start Compose.

<CodeGroup>

```json blnk.json
{
  "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"
  }
}
```

```bash .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
```

</CodeGroup>

</Step>

<Step title="Add the Compose file">

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

<Note>The Compose file in the [Blnk repository](https://github.com/blnkfinance/blnk/blob/main/docker-compose.yaml) is the local stack, and it starts its own Postgres and Redis image.</Note>

```yaml docker-compose.yaml wrap
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
```

</Step>

<Step title="Start Core">

From the directory that holds the Compose file:

```bash Start Core
docker compose up -d
docker ps
```

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

</Step>
</Steps>
</Tab>

<Tab title="PaaS">

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.

<Tip>
Use the provider's internal connection URL when Postgres and Redis run in the same project. Use the direct Postgres URL, not a pooled one, when the provider offers both.
</Tip>

<Steps titleSize="h3">
<Step title="Set the environment variables">

Add these to the project. More tuning options are in [Data stores](/operating/configuration/data-stores).

```bash .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
```

</Step>

<Step title="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.

</Step>

<Step title="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.

</Step>

<Step title="Check the server">

Send a request to the public URL:

```bash Check Core
curl https://<your-server-url>/health
```

A healthy response means Core is up. The worker should be running in its own logs.
</Step>
</Steps>

</Tab>

<Tab title="Kubernetes">

Blnk publishes Kubernetes manifests in the [repository](https://github.com/blnkfinance/blnk/tree/main/infrastructure/k8s-manifests). 

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

```bash Apply 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.

</Tab>
</Tabs>

## Connect to the dashboard

Open-source Core does not include the dashboard. Connect this Core to a [Blnk Cloud](/deploy/blnk-cloud) workspace when you want one. 

<Note>Your database stays on your network. Blnk Cloud reaches the ledger through the query agent that acts as an intermediary between your Core and the ledger.</Note>

<Steps titleSize="h3">
<Step title="Create an instance">

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

![Settings, Instances, with Deploy an instance](img/deploy/cloud-open-instance-form.gif)

</Step>

<Step title="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.

<Info>If your query agent is hosted on a private network, add our Cloud IP to your allowlist: `161.35.166.95` and `161.35.171.250`.</Info>

![Instance form with name, Core URL, and secret key](img/deploy/cloud-instance-form.gif)

Submit the form.

</Step>

<Step title="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](img/deploy/query-agent-copy-command.gif)

</Step>

<Step title="Check the connection">

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

![Instance details after the connection is Connected](img/deploy/cloud-instance-details.gif)

</Step>
</Steps>

## FAQs

<AccordionGroup>
  <Accordion title="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](https://blnkfinance.com/contact/us?utm_source=blnk_docs&utm_medium=documentation&utm_campaign=deploy%2Fopen-source). That includes a private Slack channel.

  </Accordion>
  <Accordion title="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.

  </Accordion>
  <Accordion title="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.

  </Accordion>
</AccordionGroup>

<RelatedTopics
  items={[
    { title: "Data stores", href: "/operating/configuration/data-stores" },
    { title: "Enterprise", href: "/deploy/enterprise" },
    { title: "Blnk Cloud", href: "/deploy/blnk-cloud" },
  ]}
/>