A Comprehensive Guide to Self-Hosting Blnk

Documentation Index

Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt

Use this file to discover all available pages before exploring further.

​

System architecture

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.

• PostgreSQL: Primary database.
• Redis: Used for caching and message queues.
• Typesense: Provides search functionality.
• Jaeger (optional): Enables distributed tracing.

​

Deployment options

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

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

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:

# Start all services
docker-compose up -d

# Verify deployment status
docker-compose ps

# Monitor service logs
docker-compose logs -f

​

2: Kubernetes deployment

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

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?