Docker Deployment Guide PREMIUM

This guide provides comprehensive instructions for deploying Banclo Business Continuity Suite in production environments, including standard Docker deployments and OpenShift platforms.

Prerequisites

System Requirements

Operating System: Linux (RHEL/CentOS 7+, Ubuntu 18.04+, SLES 12+)
Container Runtime: Docker 20.10+ or Podman 3.0+
Memory: Minimum 1GB RAM (2GB recommended for production)
Storage: Minimum 1GB available disk space
CPU: 2+ cores recommended
Network: Internet access for initial setup and synchronization

Required Access

Access to the private GitHub Container Registry (ghcr.io)
Valid BANK_API_ACCESS_TOKEN from your online Banclo instance (see Creating Offline Instances)
Network connectivity to your online Banclo instance for synchronization

Pre-Installation Setup

1. Container Registry Authentication

Authenticate with the private GitHub Container Registry:

bash

# Login to GitHub Container Registry
docker login ghcr.io
# Enter the GitHub username and personal access token provided by Banclo Tech

Important: Banclo Tech will supply the GitHub Container Registry credentials required to access the private repository. Contact your Banclo representative to obtain the necessary username and personal access token for GHCR authentication.

2. Obtain Bank API Access Token

The BANK_API_ACCESS_TOKEN must be obtained from your online Banclo instance. For detailed instructions on creating offline instances and obtaining access tokens, see Creating Offline Instances.

Quick Overview:

Log into the Agent Portal of your online Banclo instance
Navigate to Settings → System Administration
Access Token Management section
Generate New Offline Instance Token
- Set appropriate permissions for offline synchronization
- Copy the generated token (format: d518e83f6df39f7daf9633b55639aa10f9d2aa5885ffde4211bde9c743ea9537)
- Important: Store this token securely - it will only be displayed once

Required Admin Role: Only users with administrative privileges can generate access tokens.

3. Generate Security Keys

Generate the required cryptographic keys for secure offline operation:

bash

# Generate RSA private key for data encryption
openssl genrsa -out offline_private_key.pem 2048

# Generate RSA key pair for OAuth JWT tokens
openssl genrsa -out oauth_private.pem 2048
openssl rsa -in oauth_private.pem -pubout -out oauth_public.pem

# Generate secure session secrets
PASSPORT_KEY=$(openssl rand -hex 32)
COOKIE_SECRET=$(openssl rand -hex 32)
echo "PASSPORT_KEY: $PASSPORT_KEY"
echo "COOKIE_SECRET: $COOKIE_SECRET"

Installation Methods

Method 1: Docker Compose

1. Create Installation Directory

bash

mkdir -p /opt/banclo-offline
cd /opt/banclo-offline

2. Create Docker Compose Configuration

Create docker-compose.yml:

yaml

version: '3.8'

services:
  # Banclo Offline Application
  banclo-offline:
    image: ghcr.io/banclo/banclo-offline:latest
    ports:
      - "8083:8081"  # External access port (avoids conflicts with 8080-8082)
    environment:
      # Database Connection
      DB_CONNECTION_STR: postgresql://banclo:banclopassword@postgres:5432/banclo?sslmode=disable
      DB_DIALECT: postgres
      
      # Security Settings (Replace with your generated values)
      PASSPORT_KEY: your-very-long-passport-secret-key-for-offline-mode
      COOKIE_SECRET: your-very-long-cookie-secret-key-for-offline-mode
      SESSION_MAX_AGE: 86400000
      
      # Base URL Configuration
      BASE_URL: http://your-server-hostname:8083
      
      # API Access Token (Obtain from Agent Portal)
      BANK_API_ACCESS_TOKEN: your-bank-api-access-token-here
      
      # File Storage
      FILE_STORAGE_PATH: ./app/uploads
      
      # S3 Configuration (Optional - for scalable cloud file storage)
      S3_ENABLED: "false"  # Set to "true" to enable S3 storage
      S3_ENDPOINT: "https://s3.amazonaws.com"  # AWS S3 endpoint
      S3_REGION: "us-east-1"  # AWS region
      S3_BUCKET: "banclo-offline-files"  # S3 bucket name
      S3_ACCESS_KEY_ID: "your-aws-access-key"  # AWS access key
      S3_SECRET_ACCESS_KEY: "your-aws-secret-key"  # AWS secret key
      S3_FORCE_PATH_STYLE: "false"  # Set to "true" for LocalStack/MinIO
      
      # Online Instance Connection
      BANK_API_URL: https://console.banclo.com/~
      
      # Internal API Configuration  
      PORT: 3000  # Internal API port, nginx proxies to this
      
      # Logging
      OFFLINE_API_LOG_FILE: /app/logs/app.log
      
      # Synchronization Settings
      SYNC_CRON_EXPRESSION: "0 */6 * * *"  # Sync every 6 hours
      
      # Encryption Key (Replace with your generated key)
      OFFLINE_PRIVATE_KEY: |
        -----BEGIN RSA PRIVATE KEY-----
        [Your generated offline RSA private key here]
        -----END RSA PRIVATE KEY-----
        
      # OAuth JWT Keys for API authentication (Replace with your generated keys)
      OAUTH_JWT_PRIVATE_KEY: |
        -----BEGIN PRIVATE KEY-----
        [Your generated OAuth RSA private key here]
        -----END PRIVATE KEY-----
      OAUTH_JWT_PUBLIC_KEY: |
        -----BEGIN PUBLIC KEY-----
        [Your generated OAuth RSA public key here]
        -----END PUBLIC KEY-----
        
    volumes:
      - banclo-uploads:/app/uploads
      - banclo-logs:/app/logs
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - banclo-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  # PostgreSQL Database
  postgres:
    image: postgres:15-alpine
    ports:
      - "5433:5432"  # Avoid conflicts with existing PostgreSQL
    environment:
      POSTGRES_DB: banclo
      POSTGRES_USER: banclo
      POSTGRES_PASSWORD: banclopassword  # Change in production
    volumes:
      - banclo-postgres-data:/var/lib/postgresql/data
      - ./postgres-init:/docker-entrypoint-initdb.d
    networks:
      - banclo-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U banclo"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  banclo-network:
    driver: bridge

volumes:
  banclo-postgres-data:
  banclo-uploads:
  banclo-logs:

3. Deploy the Application

bash

# Pull the latest images
docker-compose pull

# Start the services
docker-compose up -d

# Verify deployment
docker-compose ps
docker-compose logs -f banclo-offline

Method 2: OpenShift Deployment

1. Create OpenShift Project

bash

oc new-project banclo-offline

2. Create Secret for Registry Access

bash

oc create secret docker-registry ghcr-secret \
  --docker-server=ghcr.io \
  --docker-username=your-github-username \
  --docker-password=your-github-token \
  [email protected]

3. Create Configuration Secret

bash

# Create environment configuration
cat > banclo-config.env << EOF
DB_CONNECTION_STR=postgresql://banclo:banclopassword@postgres:5432/banclo?sslmode=disable
DB_DIALECT=postgres
PASSPORT_KEY=your-very-long-passport-secret-key-for-offline-mode
COOKIE_SECRET=your-very-long-cookie-secret-key-for-offline-mode
SESSION_MAX_AGE=86400000
BASE_URL=https://your-openshift-route
BANK_API_ACCESS_TOKEN=your-bank-api-access-token-here
FILE_STORAGE_PATH=./app/uploads
BANK_API_URL=https://console.banclo.com/~/
PORT=9091
OFFLINE_API_LOG_FILE=/app/logs/app.log
SYNC_CRON_EXPRESSION=0 */6 * * *
S3_ENABLED=false
S3_ENDPOINT=https://s3.amazonaws.com
S3_REGION=us-east-1
S3_BUCKET=banclo-offline-files
S3_ACCESS_KEY_ID=your-aws-access-key
S3_SECRET_ACCESS_KEY=your-aws-secret-key
S3_FORCE_PATH_STYLE=false
EOF

oc create secret generic banclo-config --from-env-file=banclo-config.env

4. Create Private Key Secret

bash

oc create secret generic banclo-private-key --from-file=private-key=offline_private_key.pem

5. Deploy PostgreSQL

yaml

# postgres-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:15-alpine
        env:
        - name: POSTGRES_DB
          value: banclo
        - name: POSTGRES_USER
          value: banclo
        - name: POSTGRES_PASSWORD
          value: banclopassword
        ports:
        - containerPort: 5432
        volumeMounts:
        - name: postgres-storage
          mountPath: /var/lib/postgresql/data
        livenessProbe:
          exec:
            command:
            - pg_isready
            - -U
            - banclo
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          exec:
            command:
            - pg_isready
            - -U
            - banclo
          initialDelaySeconds: 5
          periodSeconds: 5
      volumes:
      - name: postgres-storage
        persistentVolumeClaim:
          claimName: postgres-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
spec:
  selector:
    app: postgres
  ports:
  - port: 5432
    targetPort: 5432

6. Deploy Banclo Offline Application

yaml

# banclo-offline-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: banclo-offline
spec:
  replicas: 1
  selector:
    matchLabels:
      app: banclo-offline
  template:
    metadata:
      labels:
        app: banclo-offline
    spec:
      imagePullSecrets:
      - name: ghcr-secret
      containers:
      - name: banclo-offline
        image: ghcr.io/banclo/banclo-offline:latest
        ports:
        - containerPort: 8081
        - containerPort: 3000
        envFrom:
        - secretRef:
            name: banclo-config
        env:
        - name: OFFLINE_PRIVATE_KEY
          valueFrom:
            secretKeyRef:
              name: banclo-private-key
              key: private-key
        volumeMounts:
        - name: uploads-storage
          mountPath: /app/uploads
        - name: logs-storage
          mountPath: /app/logs
        livenessProbe:
          httpGet:
            path: /health
            port: 9091
          initialDelaySeconds: 60
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 9091
          initialDelaySeconds: 30
          periodSeconds: 10
        resources:
          requests:
            memory: "2Gi"
            cpu: "500m"
          limits:
            memory: "4Gi"
            cpu: "2"
      volumes:
      - name: uploads-storage
        persistentVolumeClaim:
          claimName: uploads-pvc
      - name: logs-storage
        persistentVolumeClaim:
          claimName: logs-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: uploads-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: logs-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
---
apiVersion: v1
kind: Service
metadata:
  name: banclo-offline
spec:
  selector:
    app: banclo-offline
  ports:
  - name: web
    port: 8081
    targetPort: 8081
  - name: api
    port: 3000
    targetPort: 3000
---
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: banclo-offline
spec:
  to:
    kind: Service
    name: banclo-offline
  port:
    targetPort: web
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect

7. Apply OpenShift Configurations

bash

# Deploy PostgreSQL
oc apply -f postgres-deployment.yaml

# Deploy Banclo Offline
oc apply -f banclo-offline-deployment.yaml

# Verify deployment
oc get pods
oc get routes

Post-Installation Configuration

1. Initial Setup

Access the Application:
- Docker Compose: http://your-server:8083
- OpenShift: Use the route URL from oc get routes
Complete Setup Wizard:
- Create administrative user account
- Configure synchronization settings
- Test connectivity to online instance

Configuration Reference

Environment Variables

Variable	Description	Required	Default
`DB_CONNECTION_STR`	PostgreSQL connection string	Yes	-
`DB_DIALECT`	Database dialect	Yes	`postgres`
`PASSPORT_KEY`	Session encryption key (32 character)	Yes	-
`COOKIE_SECRET`	Cookie signing secret (32 character)	Yes	-
`SESSION_MAX_AGE`	Session timeout in milliseconds	No	`86400000`
`BASE_URL`	External URL of the offline instance	Yes	-
`BANK_API_ACCESS_TOKEN`	API token from online instance	Yes	-
`BANK_API_URL`	URL of online Banclo instance	Yes	-
`SYNC_CRON_EXPRESSION`	Sync schedule (cron format)	No	`0 /6 * *`
`OFFLINE_PRIVATE_KEY`	RSA private key for encryption	Yes	-
`OAUTH_JWT_PRIVATE_KEY`	RSA private key for OAuth JWT signing	Yes	-
`OAUTH_JWT_PUBLIC_KEY`	RSA public key for OAuth JWT verification	Yes	-
`OAUTH_TOKEN_EXPIRY`	OAuth token expiry time in seconds	No	`3600`
`OAUTH_ISSUER`	JWT issuer claim	No	`https://console.banclo.com`
`OAUTH_AUDIENCE`	JWT audience claim	No	`https://console.banclo.com/~/api/v1`
`OAUTH_KEY_ID`	JWT key identifier (kid)	No	`banclo-offline`
`FILE_STORAGE_PATH`	File upload directory	No	`./app/uploads`
`S3_ENABLED`	Enable S3 storage for files	No	`false`
`S3_ENDPOINT`	S3 service endpoint URL	No	`https://s3.amazonaws.com`
`S3_REGION`	AWS S3 region	No	`us-east-1`
`S3_BUCKET`	S3 bucket name for file storage	No	`banclo-offline-files`
`S3_ACCESS_KEY_ID`	AWS S3 access key ID	No	-
`S3_SECRET_ACCESS_KEY`	AWS S3 secret access key	No	-
`S3_FORCE_PATH_STYLE`	Use path-style URLs (required for LocalStack/MinIO)	No	`false`
`PORT`	Internal API port	No	`9091`
`OFFLINE_API_LOG_FILE`	Log file path	No	`/app/logs/app.log`

Synchronization Settings

The sync cron expression controls how frequently the offline instance synchronizes with the online instance:

0 */6 * * * - Every 6 hours (default)
0 */2 * * * - Every 2 hours
0 * * * * - Every hour

Note: More frequent synchronization increases network usage and system load. Banclo's API will always return any Loan Requests which have had an update in the last 48 hours.

File Storage Configuration

The offline instance supports two file storage modes:

Local File Storage (Default)

By default, files are stored locally on the server filesystem:

yaml

S3_ENABLED: "false"
FILE_STORAGE_PATH: "./app/uploads"

Files are stored in the local filesystem and served directly by the application. This is suitable for smaller deployments or when S3 is not available.

S3 Cloud Storage (Recommended for Production)

For scalable, distributed file storage, enable S3 support:

yaml

S3_ENABLED: "true"
S3_ENDPOINT: "https://s3.amazonaws.com"
S3_REGION: "us-east-1"
S3_BUCKET: "banclo-offline-files"
S3_ACCESS_KEY_ID: "your-aws-access-key"
S3_SECRET_ACCESS_KEY: "your-aws-secret-key"
S3_FORCE_PATH_STYLE: "false"

Benefits of S3 Storage:

Scalability: No local storage limits
Durability: Built-in redundancy and backup
Performance: CDN integration and geographic distribution
Cost-effective: Pay only for storage used

S3-Compatible Services

The system supports S3-compatible services like MinIO, LocalStack, or other object storage providers:

yaml

# LocalStack (for development/testing)
S3_ENABLED: "true"
S3_ENDPOINT: "http://localhost:4566"
S3_REGION: "us-east-1"
S3_BUCKET: "banclo-offline-files"
S3_ACCESS_KEY_ID: "test"
S3_SECRET_ACCESS_KEY: "test"
S3_FORCE_PATH_STYLE: "true"  # Required for LocalStack/MinIO

yaml

# MinIO
S3_ENABLED: "true"
S3_ENDPOINT: "http://your-minio-server:9000"
S3_REGION: "us-east-1"
S3_BUCKET: "banclo-offline-files"
S3_ACCESS_KEY_ID: "your-minio-access-key"
S3_SECRET_ACCESS_KEY: "your-minio-secret-key"
S3_FORCE_PATH_STYLE: "true"  # Required for MinIO

OAuth API Access

The offline instance provides OAuth 2.0 Client Credentials authentication for external systems:

1. Create OAuth Client

Navigate to Settings → OAuth Clients in the admin interface and create a new OAuth client. The system will generate secure credentials automatically.

2. Obtain Access Token

bash

curl -X POST http://your-server:8083/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "scope": "loans:read documents:read"
  }'

3. Use Access Token

bash

curl -X GET http://your-server:8083/api/v1/loan-requests \
  -H "Authorization: Bearer your-access-token"

Available OAuth Scopes

loans:read - Access loan requests and bids
documents:read - Access documents and files
users:read - Access user information
tasks:read - Access task information
analysis:read - Access analysis reports
messages:read - Access messaging
reports:read - Access reports
audit:read - Access audit logs

Health Checks

The application provides several health check endpoints:

GET https://your-domain/~/health - General application health
GET https://your-domain/~/ready - Readiness check

Health Check Response

json

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "2.0.1",
  "database": "connected",
  "sync": "active",
  "uptime": "2h 15m"
}

Monitoring and Troubleshooting

Container Monitoring

Monitor your Docker container using standard Docker commands:

bash

# View container logs
docker logs banclo-offline

# Monitor resource usage
docker stats banclo-offline  

# Check container health
docker inspect banclo-offline | grep Health

# Access container shell for troubleshooting
docker exec -it banclo-offline /bin/bash

Common Issues

Container won't start:

Check Docker logs: docker logs banclo-offline
Verify environment variables are set correctly
Ensure PostgreSQL database is accessible
Check disk space and memory availability

Sync failures:

Verify network connectivity to Banclo Cloud
Check BANK_API_ACCESS_TOKEN validity
Review sync logs for specific error messages
Confirm OAuth keys are properly configured

Database connection errors:

Check PostgreSQL container status
Verify connection string format
Ensure database user has proper permissions
Check network connectivity between containers

Security Considerations

Network Security

Configure firewall rules to restrict access to necessary ports
Use HTTPS/TLS for external access
Implement IP whitelisting where appropriate
Regular security updates for base images

Data Protection

Use strong passwords for database access
Rotate OAuth keys regularly
Implement proper backup encryption
Monitor access logs for unusual activity

For detailed support or advanced deployment scenarios, contact Banclo technical support with your specific requirements and environment details.

Docker Deployment Guide PREMIUM ​

Prerequisites ​

System Requirements ​

Required Access ​

Pre-Installation Setup ​

1. Container Registry Authentication ​

2. Obtain Bank API Access Token ​

3. Generate Security Keys ​

Installation Methods ​

Method 1: Docker Compose ​

1. Create Installation Directory ​

2. Create Docker Compose Configuration ​

3. Deploy the Application ​

Method 2: OpenShift Deployment ​

1. Create OpenShift Project ​

2. Create Secret for Registry Access ​

3. Create Configuration Secret ​

4. Create Private Key Secret ​

5. Deploy PostgreSQL ​

6. Deploy Banclo Offline Application ​

7. Apply OpenShift Configurations ​

Post-Installation Configuration ​

1. Initial Setup ​

Configuration Reference ​

Environment Variables ​

Synchronization Settings ​

File Storage Configuration ​

Local File Storage (Default) ​

S3 Cloud Storage (Recommended for Production) ​

S3-Compatible Services ​

OAuth API Access ​

1. Create OAuth Client ​

2. Obtain Access Token ​

3. Use Access Token ​

Available OAuth Scopes ​

Health Checks ​

Health Check Response ​

Monitoring and Troubleshooting ​

Container Monitoring ​

Common Issues ​

Security Considerations ​

Network Security ​

Data Protection ​

Docker Deployment Guide PREMIUM

Prerequisites

System Requirements

Required Access

Pre-Installation Setup

1. Container Registry Authentication

2. Obtain Bank API Access Token

3. Generate Security Keys

Installation Methods

Method 1: Docker Compose

1. Create Installation Directory

2. Create Docker Compose Configuration

3. Deploy the Application

Method 2: OpenShift Deployment

1. Create OpenShift Project

2. Create Secret for Registry Access

3. Create Configuration Secret

4. Create Private Key Secret

5. Deploy PostgreSQL

6. Deploy Banclo Offline Application

7. Apply OpenShift Configurations

Post-Installation Configuration

1. Initial Setup

Configuration Reference

Environment Variables

Synchronization Settings

File Storage Configuration

Local File Storage (Default)

S3 Cloud Storage (Recommended for Production)

S3-Compatible Services

OAuth API Access

1. Create OAuth Client

2. Obtain Access Token

3. Use Access Token

Available OAuth Scopes

Health Checks

Health Check Response

Monitoring and Troubleshooting

Container Monitoring

Common Issues

Security Considerations

Network Security

Data Protection