Skip to main content

​
Overview

Blnk Cloud requires a running Blnk Core instance to work. You can host your own Core instance or deploy a managed Core instance from Blnk. For self-hosted instances, Blnk uses a Query Agent to establish a connection between your Core instance and Blnk Cloud.
The Query Agent is packaged in a docker container that you run on your machine or infrastructure.
  • Enhanced security: No need to expose database credentials or configure complex firewall rules.
  • Read-only access: Agent only requires SELECT permissions, ensuring data integrity.
  • Simplified setup: Eliminates network configuration complexity.
  • Reliable connection: Automatic reconnection and health monitoring.

​
Connect your self-hosted Core

1

Create an instance on Cloud

  1. In your Blnk Cloud workspace, go to Settings > Instances;
  2. Click Connect new instance;
  3. You’ll see the instance creation form.
Settings > Instances page showing the Connect new instance button
2

Provide instance details

Fill in your instance information:
  1. Instance name: Choose a descriptive name (e.g., “Production”, “Staging”). This is the only required field;
  2. Core URL: Your Blnk Core instance URL (e.g., https://api.yourcompany.com):
    • Make sure it is publicly accessible on the internet. If locally hosted, use a tunnel service like ngrok: ngrok http 5001 to create a public URL.
    • If hosted on a private network, make sure to whitelist our IP addresses so that Cloud can communicate with your ledger:
      • 161.35.166.95
      • 161.35.171.250
  3. Core secret key: Your Blnk Core API secret key set in your blnk.json configuration file. You can leave this empty if you don’t have a secret key.
Instance creation form with instance name, Core URL, and secret key fields
We use your Core URL and secret key to process actions in your workspace. Without them, your instance will be limited to read-only access.
Once done, submit the form.
3

Set up the Query Agent

Next, you run the following docker command in your terminal to set up your Query Agent.
bash
docker run -d \
  -p 9090:9090 \
  -e DB_URL="postgres://user:pass@host:port/db?sslmode=require" \
  -e CONNECTION_KEY="sk_live_..." \
  blnkfinance/query-agent:latest
  1. To get your CONNECTION_KEY:
    • Go to Settings > Instances and view your instance details.
    • Copy your Connection key from your instance info.
    Instance details page showing where to find the connection key
  2. Replace the placeholder database URL with your actual connection string.
4

Verify connection

Return to your Blnk Cloud workspace:
  1. Check connection status: Navigate back to Settings > Instances;
  2. Verify agent status: Your instance should show as “Connected” with a green indicator.
Instance connection status showing Connected with green indicator

​
Connecting to your database running inside your Docker container

To connect to your database running inside your Docker container:
1

Check the network of the postgres container

First, you need to identify which Docker network your database container is running on.
docker inspect postgres | grep NetworkMode
This command will show you the network name that your PostgreSQL container is using.
2

Run the Query Agent on the same network

Next, run the Query Agent container on the same network as your database container. Replace the placeholders with your actual values.
docker run -d \
  -p 9090:9090 \
  --network <network-name> \
  --name <container-name> \
  -e DB_URL="postgres://blnk_readonly:secure_password@db.example.com:5432/blnk?sslmode=require" \
  -e CONNECTION_KEY="sk_live_..." \
  blnkfinance/query-agent:latest
Make sure to replace:
  • <network-name> with the network name from the previous step.
  • <container-name> with your preferred container name.
  • Update the DB_URL with your actual database connection details. You can find it in your default blnk.json configuration file.
  • Replace sk_live_... with your actual connection key from the connection setup page on Cloud.

​
Managing your query agent

​
Monitor connection health

To see how your connection is doing:
bash
# View real-time logs
docker logs -f <container-name>

# Check container resource usage
docker stats <container-name>

# Health check endpoint (returns 200 OK when live)
curl -X GET http://localhost:9090/live

​
Update the Query Agent

To upgrade the Query Agent to the latest version:
bash
# Pull latest version
docker pull blnkfinance/query-agent:latest

# Stop and remove current container
docker stop <container-name>
docker rm <container-name>

# Restart with updated image (use your original configuration)
docker run -d \
      -p 9090:9090 \
      --name <container-name> \
      -e DB_URL="postgres://blnk_readonly:secure_password@db.example.com:5432/blnk?sslmode=require" \
      -e CONNECTION_KEY="sk_live_..." \
      blnkfinance/query-agent:latest

​
Stop the Query Agent

To terminate your Query Agent:
bash
# Stop the container
docker stop <container-name>

# Remove the container
docker rm <container-name>

​
FAQs

  • If you’re running PostgreSQL inside Docker (on a Mac/Linux), use host.docker.internal as the host in your database URL.
  • For Windows, run the Query Agent container on the same network as your database container. Learn more****
  • If you’re running PostgreSQL directly on your machine, use localhost as the host in your database URL.
  • Ensure PostgreSQL is running and accessible.
  • Check that the port (default: 5432) is correct.
  • Verify your database credentials are correct.
  • Verify the database URL format is correct.
  • Ensure the database host is accessible from your Docker host.
  • Check that the database user has proper read permissions.
  • Verify network connectivity allows database connections.
  • Ensure SSL mode is correctly configured.
  • Verify Docker is running: docker --version
  • Check if port conflicts exist: docker ps
  • Ensure environment variables are properly formatted.
  • Review Docker logs: docker logs blnk-agent --tail 50
  • Verify the instance URL is accessible and responding.
  • Verify the instance secret key is correctly copied.
  • Ensure SSL certificate is valid if using HTTPS.
  • Confirm the instance is running and accepting connections.
  • Test instance connectivity: curl -H "Authorization: Bearer YOUR_SECRET_KEY" https://your-instance-url/health

​
Need help?

If you’re having trouble with Blnk Cloud, don’t hesitate to send us a message via email at support@blnkfinance.com or send us a message here.