> ## 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.

# A Comprehensive Guide to Self-Hosting Blnk

> Learn how to self-host Blnk on your infrastructure with Docker or Kubernetes.

Blnk can run on your own infrastructure, but you can also skip self-hosting and deploy faster with Blnk Cloud.

<Tip>
  If you want the simplest path to production, use [Blnk Cloud](https://cloud.blnkfinance.com) instead of managing your own infrastructure.
</Tip>

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

<Steps titleSize="h3">
  <Step title="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
  </Step>

  <Step title="Configuration">
    Create or update your `blnk.json` file. For configuration details, see the [configuration overview](/advanced/configuration/overview).

    ```json blnk.json theme={"system"}
    {
      "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"
      }
    }
    ```
  </Step>

  <Step title="Create a &#x22;docker-compose.yml&#x22; file">
    Add the following configuration. It includes the API server, worker, and supporting services.

    ```yaml docker-compose.yml [expandable] theme={"system"}
    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:
    ```
  </Step>

  <Step title="Start deployment">
    Run these commands to start and validate your deployment:

    ```shell theme={"system"}
    # Start all services
    docker-compose up -d

    # Verify deployment status
    docker-compose ps

    # Monitor service logs
    docker-compose logs -f
    ```
  </Step>
</Steps>

***

## 2: Kubernetes deployment

Blnk provides Kubernetes manifests to help you deploy and operate Blnk in containerized environments.

Use the official manifests and instructions:

<Card href="https://github.com/blnkfinance/blnk/tree/main/infrastructure/k8s-manifests" icon="folder-git" title="infrastructure/k8s-manifests">
  Blnk Kubernetes Manifests
</Card>

After `kubectl` is installed, run:

```bash kubectl theme={"system"}
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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).

***

<Tip>
  **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 →](https://www.blnkfinance.com/products/cloud)
</Tip>