Blnk is a modern financial software designed for scalability and reliability. This guide outlines deployment strategies for operations of all sizes, ranging from development setups to full-scale production systems.

​
System architecture

Blnk operates as a distributed system with three core components:
  1. API Server: Manages incoming HTTP requests and API operations.
  2. Worker: Processes background jobs and handles asynchronous tasks.
  3. Migration Service: Oversees database schema updates and management.
Supporting Infrastructure:
  • PostgreSQL: Primary database.
  • Redis: Used for caching and message queues.
  • Typesense: Provides search functionality.
  • Jaeger (optional): Enables distributed tracing.

​
Deployment options

This guide covers two primary deployment strategies, each suited to different operational needs.
  1. Single server deployment:
    • Development environments
    • Small to medium-scale production deployments
    • Teams with limited operational overhead
    • Quick setup requirements
  2. Kubernetes deployment:
    • Large-scale production environments
    • High availability requirements
    • Teams with existing Kubernetes expertise
    • Systems requiring sophisticated scaling capabilities

​
1. Single Server Deployment

1

Prerequisites

Ensure you have the following available or installed:
  • Linux server (Ubuntu 20.04 LTS or newer recommended)
  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Managed PostgreSQL instance
  • Managed Redis instance
2

Configuration

Create or update your blnk.json configuration file. Learn more: Advanced configuration
blnk.json
{
  "project_name": "Blnk",
  "data_source": {
    "dns": "postgres://<user>:<password>@<host>:5432/blnk?sslmode=require"
  },
  "redis": {
    "dns": "redis://:<password>@<host>:6379"
  },
  "typesense": {
    "dns": "http://typesense:8108"
  },
  "server": {
    "port": "5001",
    "ssl": false,
    "domain": "your-domain.com"
  },
  "queue": {
    "monitoring_port": "5004"
  }
}
3

Create a "docker-compose.yml" file

Copy and paste the following configuration into your file to get started. This setup includes the API server, worker, and migration services for seamless deployment.
docker-compose.yml
version: "3.8"

services:
  server:
    image: ${BLNK_IMAGE:-jerryenebeli/blnk:0.10.2}
    container_name: server
    restart: on-failure
    entrypoint: ["/bin/sh", "-c"]
    command:
      - "blnk migrate up && blnk start"
    environment:
      TZ: ${TZ:-Etc/UTC}
      OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4318
    ports:
      - "5001:5001"
      - "80:80"
      - "443:443"
    depends_on:
      - redis
      - postgres
      - jaeger
    volumes:
      - ./blnk.json:/blnk.json

  worker:
    image: ${BLNK_IMAGE:-jerryenebeli/blnk:0.10.2}
    container_name: worker
    restart: on-failure
    entrypoint: ["blnk", "workers"]
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4318
    depends_on:
      - redis
      - postgres
      - jaeger
    volumes:
      - ./blnk.json:/blnk.json

  redis:
    image: redis:7.2.4
    container_name: redis

  postgres:
    image: ${POSTGRES_IMAGE:-postgres:16}
    container_name: ${POSTGRES_CONTAINER:-postgres}
    restart: on-failure
    ports:
      - "${POSTGRES_OUTER_PORT:-5432}:5432"
    environment:
      TZ: ${TZ:-Etc/UTC}
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password}
      POSTGRES_DB: ${POSTGRES_DB:-blnk}
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER:-postgres}"]
      interval: 10s
      timeout: 5s
      retries: 5

  typesense:
    image: typesense/typesense:0.23.1
    container_name: typesense
    command:
      ["--data-dir", "/data", "--api-key=blnk-api-key", "--listen-port", "8108"]
    volumes:
      - typesense_data:/data
    logging:
      driver: "none"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8108/health"]
      interval: 30s
      timeout: 10s
      retries: 5

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

volumes:
  pg_data:
  typesense_data:
4

Start deployment

Run the following docker commands:
# Initialize services
docker-compose up -d

# Execute database migration
docker-compose run --rm migration

# Verify deployment status
docker-compose ps

# Monitor service logs
docker-compose logs -f

​
2. Kubernetes Deployment

Blnk provides comprehensive Kubernetes manifests for streamlined deployment and management in containerized environments. These manifests help you quickly set up, scale, and manage Blnk in production or development clusters. You can find the official manifests and instructions here:

infrastructure/k8s-manifests

Blnk Kubernetes Manifests

​
Production considerations

​
1. Security

  1. Network Security
    • Enable SSL/TLS for all external connections
    • Implement proper network policies
    • Use secret management solutions
    • Regular security updates
  2. Access Control
    • Implement proper authentication
    • Use role-based access control
    • Regular audit of access patterns

​
2. Monitoring

  1. System Metrics
    • CPU utilization
    • Memory usage
    • Disk I/O
    • Network traffic
  2. Application Metrics
    • Request latency
    • Error rates
    • Queue depths
    • Processing times

​
3. Backup and Recovery

  1. Database Backups
    • Regular automated backups
    • Point-in-time recovery capability
    • Backup testing procedures
  2. Configuration Management
    • Version control for configurations
    • Documentation of deployment procedures
    • Disaster recovery planning

​
Troubleshooting guide

Here are common issues to check for if you encounter any problems during deployment:
  1. Database Connectivity
    • Verify network security groups
    • Check connection strings
    • Validate database credentials
  2. Worker Processing
    • Monitor Redis connectivity
    • Check worker logs
    • Verify queue configuration
  3. Migration Issues
    • Verify database permissions
    • Check migration logs
    • Validate schema versions

​
Support resources

  1. Log Analysis
    • Check application logs (docker-compose logs or kubectl logs)
    • Review system logs
    • Monitor error tracking systems
  2. Performance Issues
    • Review resource utilization
    • Check database performance
    • Monitor network latency
  3. Additional Support
    • Technical documentation
    • Community forums
    • Support channels

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.