selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

ballerine logo

Self-host ballerine

hotfix-workflow-service@v0.6.733
BetaOpen SourceOther
Docker ComposeCompose file & guide
docker-compose up -d
Updatedlast year
LanguageTypescript
Setup difficultyAdvanced
MobileResponsive
ThemeDark mode
Stars
2 450
CPU
2 vCPU
RAM
4GB
Storage
10GB
Port
5137 (Back Office), 5201 (KYB App), 5200 (Workflows Dashboard), 3000 (Workflow Service)
Requires
PostgreSQL
Docker
ghcr.io/ballerine-io/backoffice:dev
ballerine screenshot 1ballerine screenshot 2ballerine screenshot 3ballerine screenshot 4

What is ballerine?

ballerine alternatives

Should you self-host ballerine?

ballerine scores 54/100 on selfhost.directory (how scoring works) and ranks #3 of 8 in Compliance. It has 2 450 GitHub stars, +15 in the last 30 days.

There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.

Setup is advanced: plan for several services and some ongoing maintenance. An official Docker image is available. It is Other-licensed and written mostly in Typescript.

Its closest alternative on selfhost.directory is probo (63/100, 1 508 stars). It scores higher overall, so compare the two before you pick. See ballerine vs probo side by side.

Features

  • AI
  • API
  • Authentication
  • Compliance
  • Dashboard
  • Fraud Detection
  • KYB
  • KYC
  • Multi-user
  • No-code builderCurrently in WIP
  • Plugin System
  • Rule Engine
  • Workflow Engine

ballerine README

How to install ballerine

Install ballerine with Docker Compose

Docker Engine 20.10+, Docker Compose 1.29+, Node.js 21, PNPM
Environment variables
### Back Office
- `VITE_DOMAIN`: Domain for the Back Office
- `VITE_API_KEY`: API key for the Back Office
- `VITE_AUTH_ENABLED`: Enable authentication
- `VITE_MOCK_SERVER`: Enable mock server
- `VITE_ENVIRONMENT_NAME`: Environment name
- `VITE_POLLING_INTERVAL`: Polling interval
- `VITE_ASSIGNMENT_POLLING_INTERVAL`: Assignment polling interval
- `VITE_FETCH_SIGNED_URL`: Fetch signed URL

### KYB App
- `VITE_DOMAIN`: Domain for the KYB App
- `VITE_ENVIRONMENT_NAME`: Environment name
- `VITE_KYB_DEFINITION_ID`: KYB definition ID

### Workflow Service
- `BCRYPT_SALT`: Salt for bcrypt
- `SESSION_EXPIRATION_IN_MINUTES`: Session expiration time
- `DB_URL`: PostgreSQL database URL
- `API_KEY`: API key
- `NODE_ENV`: Node environment
- `COMPOSE_PROJECT_NAME`: Compose project name
- `DB_PORT`: Database port
- `DB_USER`: Database user
- `DB_PASSWORD`: Database password
- `SESSION_SECRET`: Session secret
- `BACKOFFICE_CORS_ORIGIN`: Back Office CORS origin
- `WORKFLOW_DASHBOARD_CORS_ORIGIN`: Workflow Dashboard CORS origin
- `PORT`: Port for the Workflow Service
- `KYB_EXAMPLE_CORS_ORIGIN`: KYB Example CORS origin
- `APP_API_URL`: App API URL
- `EMAIL_API_TOKEN`: Email API token
- `EMAIL_API_URL`: Email API URL
- `UNIFIED_API_URL`: Unified API URL
- `UNIFIED_API_TOKEN`: Unified API token
- `UNIFIED_API_SHARED_SECRET`: Unified API shared secret
- `ENVIRONMENT_NAME`: Environment name
- `HASHING_KEY_SECRET`: Hashing key secret
- `HASHING_KEY_SECRET_BASE64`: Hashing key secret in base64
- `NOTION_API_KEY`: Notion API key

### Workflows Dashboard
- `VITE_DOMAIN`: Domain for the Workflows Dashboard
- `VITE_ENVIRONMENT_NAME`: Environment name
- `MODE`: Mode (development/production)
- `VITE_IMAGE_LOGO_URL`: Image logo URL

Prerequisites

  • Docker
  • Docker Compose
  • Node.js (v21)
  • PNPM

Installation

  1. Clone the repository:

    git clone https://github.com/ballerine-io/ballerine.git
    cd ballerine
    
  2. Install dependencies:

    pnpm install
    pnpm monorepo:init
    
  3. Run the example:

    pnpm kyb-manual-review-example
    
  4. Access the services:

Docker Compose

Alternatively, you can use Docker Compose to deploy Ballerine:

version: '3'
services:
  ballerine-case-managment:
    container_name: backoffice
    image: ghcr.io/ballerine-io/backoffice:dev
    platform: linux/amd64
    ports:
      - "5137:80"
    depends_on:
      - ballerine-workflow-service
    restart: on-failure
    environment:
      VITE_DOMAIN: http://localhost:3000
      VITE_API_KEY: secret
      VITE_AUTH_ENABLED: "true"
      VITE_MOCK_SERVER: "false"
      VITE_ENVIRONMENT_NAME: local
      VITE_POLLING_INTERVAL: "10"
      VITE_ASSIGNMENT_POLLING_INTERVAL: "5"
      VITE_FETCH_SIGNED_URL: "false"

  ballerine-kyb-app:
    container_name: kyb-app
    platform: linux/amd64
    image: "ghcr.io/ballerine-io/kyb-app:dev"
    ports:
      - "5201:80"
    depends_on:
      - ballerine-workflow-service
    restart: on-failure
    environment:
      VITE_DOMAIN: http://localhost:3000
      VITE_ENVIRONMENT_NAME: local
      VITE_KYB_DEFINITION_ID: kyb_parent_kyc_session_example

  ballerine-workflow-service:
    container_name: workflow-service
    platform: linux/amd64
    image: "ghcr.io/ballerine-io/workflows-service:dev"
    command:
      - /bin/sh
      - -c
      - |
        npm run db:init
        npm run seed
        dumb-init npm run prod
    ports:
      - "3000:3000"
    environment:
      BCRYPT_SALT: 10
      SESSION_EXPIRATION_IN_MINUTES: 60
      DB_URL: postgres://admin:admin@postgres:5432
      API_KEY: secret
      NODE_ENV: development
      COMPOSE_PROJECT_NAME: ballerine-x
      DB_PORT: 5432
      DB_USER: admin
      DB_PASSWORD: admin
      SESSION_SECRET: iGdnj4A0YOhj8dHJK7IWSvQKEZsG7P70FFehuddhFPjtg/bSkzFejYILk4Xue6Ilx9y3IAwzR8pV1gg7
      BACKOFFICE_CORS_ORIGIN: http://localhost:5137
      WORKFLOW_DASHBOARD_CORS_ORIGIN: http://localhost:5200
      PORT: 3000
      KYB_EXAMPLE_CORS_ORIGIN: http://localhost:5201
      APP_API_URL: http://localhost:3000
      EMAIL_API_TOKEN: ''
      EMAIL_API_URL: https://api.sendgrid.com/v3/mail/send
      UNIFIED_API_URL: 'http://localhost:3001'
      UNIFIED_API_TOKEN: ''
      UNIFIED_API_SHARED_SECRET: ''
      ENVIRONMENT_NAME: 'development'
      HASHING_KEY_SECRET: "$2b$10$FovZTB91/QQ4Yu28nvL8e."
      HASHING_KEY_SECRET_BASE64: JDJiJDEwJFRYNjhmQi5JMlRCWHN0aGowakFHSi4=
      NOTION_API_KEY: secret
    depends_on:
      ballerine-postgres:
        condition: service_healthy
    restart: on-failure

  ballerine-workflows-dashboard:
    container_name: workflows-dashboard
    platform: linux/amd64
    image: ghcr.io/ballerine-io/workflows-dashboard:dev
    ports:
      - "5200:80"
    environment:
      VITE_DOMAIN: http://localhost:3000
      VITE_ENVIRONMENT_NAME: local
      MODE: development
      VITE_IMAGE_LOGO_URL: ""
    depends_on:
      - ballerine-workflow-service
    restart: on-failure

  ballerine-postgres:
    container_name: postgres
    image: sibedge/postgres-plv8:15.3-3.1.7
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin
    volumes:
      - postgres15:/var/lib/postgresql/data
    healthcheck:
      test:
        - CMD
        - pg_isready
        - -U
        - admin
      timeout: 45s
      interval: 10s
      retries: 10

volumes:
  postgres15: ~

Run the services

cd deploy
docker-compose up -d

Access the services

Ansible

You can also deploy Ballerine using Ansible:

  1. Install Ansible on your control node.
  2. Clone the repository and navigate to the Ansible playbook directory:
    git clone https://github.com/ballerine-io/ballerine.git
    cd deploy/ansible/ballerine_playbook
    
  3. Create an inventory file with your server details:
    touch inventory
    
  4. Edit the inventory file to include your server's hostname, port, and user:
    all ansible_host=<SERVER_HOST> ansible_port=<SERVER_PORT> ansible_user=<SERVER_USER>
    
  5. Configure the necessary variables in deploy/ansible/ballerine_playbook/roles/setup-ballerine/defaults/main.yml.
  6. Run the Ansible playbook:
    ansible-playbook -i inventory.txt ballerine-playbook.yml --skip-tags packer
    
  7. Access Ballerine using the configured URLs.

How to configure ballerine

  • VITE_DOMAINhttp://localhost:3000Domain for the Back Office

    values: Any valid URL

  • VITE_API_KEYsecretAPI key for the Back Office

    values: Any string

  • VITE_AUTH_ENABLEDtrueEnable authentication

    values: true, false

  • VITE_MOCK_SERVERfalseEnable mock server

    values: true, false

  • VITE_ENVIRONMENT_NAMElocalEnvironment name

    values: Any string

ballerine releases & version history

@ Every self-hosted release, weekly

One Monday email with the week's stable releases across the directory.

FAQ

Does Ballerine support integrations with third-party services?

Yes, Ballerine supports integrations with third-party services such as SendGrid, Notion, Salesforce, and AWS S3.

What are the system requirements for Ballerine?

Ballerine requires at least 2 vCPUs, 4GB of RAM, and 10GB of storage for a basic deployment. For production environments, higher specifications are recommended.

Is Ballerine suitable for small businesses?

Ballerine is primarily designed for enterprises, fintechs, and payment companies. However, it can be adapted for smaller businesses with the necessary technical expertise.

How can I deploy Ballerine?

You can deploy Ballerine using Docker Compose or Ansible. Follow the installation instructions in the [README](https://github.com/ballerine-io/ballerine#readme) or the [Ansible playbook documentation](https://github.com/ballerine-io/ballerine/tree/dev/deploy/ansible/ballerine_playbook).

What is Ballerine?

Ballerine is an open-source risk management infrastructure for automating KYC/KYB, underwriting, and transaction monitoring. It provides a workflow engine, rule engine, plugin system, and a no-code builder for creating custom risk decisioning processes.

More in Compliance

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…