Skip to main content
Blnk can run on your own infrastructure, but you can also skip self-hosting and deploy faster with Blnk Cloud.
If you want the simplest path to production, use Blnk Cloud instead of managing your own infrastructure.
Use this guide when you need full control over infrastructure, networking, and runtime configuration. It covers practical deployment paths for development and production environments.

​
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

Choose the deployment model that matches your scale and operational needs:
  1. Single-server deployment
    • Best for development and smaller production workloads
    • Lower operational overhead
    • Faster setup and maintenance
  2. Kubernetes deployment
    • Best for large-scale production workloads
    • High availability and horizontal scaling
    • Teams with existing Kubernetes experience

​
1: Single-server deployment

1

Prerequisites

Make sure you have the following:
  • 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 file. For configuration details, see 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

Add the following configuration. It includes the API server, worker, and supporting services.
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 these commands to start and validate your deployment:
# Start all services
docker-compose up -d

# Verify deployment status
docker-compose ps

# Monitor service logs
docker-compose logs -f

​
2: Kubernetes deployment

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

infrastructure/k8s-manifests

Blnk Kubernetes Manifests
 After kubectl is installed, run:
kubectl
kubectl apply -f infrastructure/k8s-manifests/namespace.yaml
kubectl apply -f infrastructure/k8s-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

If you run into deployment issues, check these areas first:
  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.
Tip: Connect to Blnk Cloud to see your Core data.You can view your transactions, manage identities, create custom reports, invite other team members to collaborate, and perform operations on your Core — all in one dashboard.Check out Blnk Cloud →