Skip to main content

Installation Guide

Detailed installation instructions for Billerang.

System Requirements​

Kubernetes Cluster​

  • Kubernetes 1.27+
  • 3+ worker nodes (4 CPU, 16GB RAM each)
  • Block storage provisioner
  • Ingress controller (nginx recommended)

Local Development​

  • Docker Desktop or Rancher Desktop
  • Java 21
  • Maven 3.9+
  • Node.js 20+

Production Deployment​

1. Prerequisites​

# Install CloudNativePG operator
kubectl apply -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.22/releases/cnpg-1.22.0.yaml

# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.0/cert-manager.yaml

# Verify installations
kubectl get pods -n cnpg-system
kubectl get pods -n cert-manager

2. Create Namespaces​

kubectl create namespace billerang-prod
kubectl create namespace billerang-auth
kubectl create namespace billerang-cache
kubectl create namespace billerang-db
kubectl create namespace billerang-jobs

3. Deploy Redis​

kubectl apply -f infrastructure/kubernetes/redis/

4. Deploy Keycloak​

# Create Keycloak database
kubectl apply -f infrastructure/kubernetes/keycloak/postgres.yaml

# Deploy Keycloak
kubectl apply -f infrastructure/kubernetes/keycloak/keycloak.yaml

5. Deploy Provider Databases​

# For each provider
kubectl apply -f infrastructure/kubernetes/providers/pluxee-fr/postgres.yaml
kubectl apply -f infrastructure/kubernetes/providers/pluxee-de/postgres.yaml

6. Run Database Migrations​

# Create job to run Liquibase
kubectl apply -f infrastructure/kubernetes/migrations/liquibase-job.yaml

# Check status
kubectl logs -f job/liquibase-migration -n billerang-db

7. Deploy Backend​

kubectl apply -f infrastructure/kubernetes/backend/

8. Configure Ingress​

kubectl apply -f infrastructure/kubernetes/ingress/

Local Development​

1. Clone Repository​

git clone https://github.com/billerang/billerang.git
cd billerang

2. Start Dependencies​

cd billerang-backend/billerang-environment
docker compose up -d postgres keycloak

3. Build Backend​

cd billerang-backend
mvn install -DskipTests

4. Run Backend​

cd opencell-admin/web/target
java -jar opencell.war

5. Start Frontend​

cd billerang-frontend
npm install
npm run dev

Verification​

Health Checks​

# API health
curl https://api.billerang.com/health

# Keycloak health
curl https://auth.billerang.com/health

Smoke Test​

# Get token
export TOKEN=$(curl -s -X POST "${KEYCLOAK_URL}/realms/billerang/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=billerang-api" \
  -d "client_secret=${CLIENT_SECRET}" | jq -r '.access_token')

# List customers
curl -H "Authorization: Bearer ${TOKEN}" \
  https://api.billerang.com/api/rest/v2/account/customer/list

Troubleshooting​

Pod Not Starting​

kubectl describe pod <pod-name> -n billerang-prod
kubectl logs <pod-name> -n billerang-prod

Database Connection Issues​

# Check CloudNativePG cluster status
kubectl get clusters -n billerang-db

# Check service endpoints
kubectl get endpoints -n billerang-db

Keycloak Issues​

# Check Keycloak logs
kubectl logs -f deployment/keycloak -n billerang-auth