WiKID High Availability (HA) Setup Tutorial

Overview

This tutorial covers setting up a WiKID Enterprise Server deployment in a High Availability (HA) environment with:

Load Balancer: HAProxy for distributing authentication requests across multiple WiKID servers
Multiple WiKID Servers: At least 2-3 instances for redundancy
Remote PostgreSQL Database: A dedicated PostgreSQL server with SSL/TLS encryption

This architecture ensures no single point of failure and allows horizontal scaling of WiKID authentication services.

Architecture

Clients (Token Registration & Authentication)
↓ Port 8388 (wClient Protocol)

HAProxy Load Balancer
192.168.56.4

↓↓↓ Port 80

WiKID Server 1
192.168.56.6

WiKID Server 2
192.168.56.13

WiKID Server 3
192.168.56.14

↓ Port 5432 (SSL/TLS)

PostgreSQL Database
(Remote)
192.168.56.104

Prerequisites

WiKID Enterprise Server 5.9.x installed on all server nodes
HAProxy 1.8 or later
PostgreSQL 14 or later on a dedicated server
All servers on the same network (or routable subnets)
SSH/root access to all machines
SSL certificates for PostgreSQL (TLS 1.2+)

Part 1: Load Balancer Configuration (HAProxy)

1.1 Install HAProxy

sudo yum install -y haproxy
sudo systemctl enable haproxy

1.2 Configure HAProxy

Edit /etc/haproxy/haproxy.cfg:

#---------------------------------------------------------------------
# HAProxy Configuration for WiKID HA Cluster
#---------------------------------------------------------------------

global
    log         127.0.0.1 local2
    chroot      /var/lib/haproxy
    pidfile     /var/run/haproxy.pid
    maxconn     20000
    user        haproxy
    group       haproxy
    daemon
    stats socket /var/lib/haproxy/stats

defaults
    mode                    tcp
    log                     global
    retries                 3
    timeout connect         10s
    timeout client          1m
    timeout server          1m
    timeout check           10s
    maxconn                 3000

#---------------------------------------------------------------------
# WiKID Frontend (Port 8388 for wClient protocol)
#---------------------------------------------------------------------
frontend wikid_frontend
    mode tcp
    bind *:8388
    default_backend wikid_backend

#---------------------------------------------------------------------
# WiKID Backend (Round-robin load balancing)
#---------------------------------------------------------------------
backend wikid_backend
    balance     roundrobin
    mode tcp
    
    # WiKID Server 1 (fiserv_prod)
    server  wikid1 192.168.56.6 check port 80
    
    # WiKID Server 2 (oracle8DVD)
    server  wikid2 192.168.56.13 check port 80
    
    # WiKID Server 3 (FiservProd3)
    server  wikid3 192.168.56.14 check port 80

#---------------------------------------------------------------------
# HAProxy Stats Page (Optional, for monitoring)
#---------------------------------------------------------------------
listen stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 30s
    stats show-legends

1.3 Validate and Start HAProxy

# Check configuration syntax
sudo haproxy -f /etc/haproxy/haproxy.cfg -c

# Start HAProxy
sudo systemctl start haproxy
sudo systemctl status haproxy

Part 2: Remote PostgreSQL Database Configuration

2.1 PostgreSQL Server Setup

On the dedicated PostgreSQL server (192.168.56.104), ensure PostgreSQL 14+ is installed:

sudo yum install -y postgresql-server postgresql-contrib
sudo /usr/pgsql-16/bin/postgresql-16-setup initdb
sudo systemctl enable postgresql-16
sudo systemctl start postgresql-16

2.2 Create WiKID Database and User

# As postgres user
sudo -u postgres psql

-- Create database
CREATE DATABASE wikid;

-- Create user
CREATE USER wikidadmin WITH PASSWORD 'wikidone';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE wikid TO wikidadmin;
ALTER USER wikidadmin CREATEDB;

\q

2.3 PostgreSQL SSL/TLS Configuration

Generate SSL certificates on the PostgreSQL server:

mkdir -p /var/lib/pgsql/16/data
cd /var/lib/pgsql/16/data

# Generate root CA certificate
openssl req -new -x509 -days 3650 -nodes \
  -keyout root.key -out root.crt \
  -subj "/CN=WikidRootCA/O=WiKID/C=US"

# Generate server certificate
openssl req -new -nodes \
  -keyout server.key -out server.csr \
  -subj "/CN=postgresql.wikid.local/O=WiKID/C=US"

# Sign server certificate with root CA
openssl x509 -req -days 3650 -in server.csr \
  -CA root.crt -CAkey root.key -CAcreateserial \
  -out server.crt

# Generate client certificate
openssl req -new -nodes \
  -keyout client.key -out client.csr \
  -subj "/CN=wikidclient/O=WiKID/C=US"

# Sign client certificate
openssl x509 -req -days 3650 -in client.csr \
  -CA root.crt -CAkey root.key \
  -out client.crt

# Create PKCS12 keystore for WiKID clients
openssl pkcs12 -export -in client.crt -inkey client.key \
  -name wikidclient -out client.p12 \
  -passout pass:wikid

# Set permissions
sudo chown postgres:postgres /var/lib/pgsql/16/data/*
sudo chmod 600 /var/lib/pgsql/16/data/server.key
sudo chmod 600 /var/lib/pgsql/16/data/root.key
sudo chmod 644 /var/lib/pgsql/16/data/*.crt

2.4 PostgreSQL Configuration

Edit /var/lib/pgsql/16/data/postgresql.conf:

listen_addresses = '*'
port = 5432
ssl = on 
ssl_ca_file = '/var/lib/pgsql/16/data/root.crt'
ssl_cert_file = '/var/lib/pgsql/16/data/server.crt'
ssl_key_file = '/var/lib/pgsql/16/data/server.key'
ssl_passphrase_command = 'echo "wikid"'

# Performance tuning for HA
shared_buffers = 256MB
effective_cache_size = 1024MB
work_mem = 64MB
maintenance_work_mem = 64MB

Edit /var/lib/pgsql/16/data/pg_hba.conf:

# Local connections
local   all             all                                     trust

# IPv4 localhost
host    all             all             127.0.0.1/32           scram-sha-256

# IPv6 localhost
host    all             all             ::1/128                scram-sha-256

# Replication
local   replication     all                                     peer
host    replication     all             127.0.0.1/32          scram-sha-256
host    replication     all             ::1/128               scram-sha-256

# SSL connections from WiKID servers
hostssl         all     all     192.168.56.6/32         scram-sha-256 clientcert=verify-ca
hostssl         all     all     192.168.56.13/32        scram-sha-256 clientcert=verify-ca
hostssl         all     all     192.168.56.14/32        scram-sha-256 clientcert=verify-ca

# SSL connections from HAProxy (if needed)
hostssl         all     all     192.168.56.4/32         scram-sha-256 clientcert=verify-ca

2.5 Restart PostgreSQL

sudo systemctl restart postgresql-16

# Verify SSL is enabled
sudo -u postgres psql -c "SHOW ssl;"

2.6 Distribute Client Certificates

# From PostgreSQL server, copy certificates to WiKID servers
scp /var/lib/pgsql/16/data/root.crt root@192.168.56.6:/opt/WiKID/private/
scp /var/lib/pgsql/16/data/root.crt root@192.168.56.13:/opt/WiKID/private/
scp /var/lib/pgsql/16/data/root.crt root@192.168.56.14:/opt/WiKID/private/

scp /var/lib/pgsql/16/data/client.p12 root@192.168.56.6:/opt/WiKID/private/
scp /var/lib/pgsql/16/data/client.p12 root@192.168.56.13:/opt/WiKID/private/
scp /var/lib/pgsql/16/data/client.p12 root@192.168.56.14:/opt/WiKID/private/

# Fix permissions on WiKID servers
ssh root@192.168.56.6 "chmod 600 /opt/WiKID/private/*.p12 /opt/WiKID/private/*.crt"
ssh root@192.168.56.13 "chmod 600 /opt/WiKID/private/*.p12 /opt/WiKID/private/*.crt"
ssh root@192.168.56.14 "chmod 600 /opt/WiKID/private/*.p12 /opt/WiKID/private/*.crt"

Part 3: WiKID Server Configuration

3.1 Create postgres.properties

On each WiKID server, create /opt/WiKID/conf/postgres.properties:

#PostgreSQL Remote Database Configuration
#WiKID HA Environment

# Database Connection
postgres.protocol=jdbc:postgresql
postgres.server=192.168.56.104
postgres.port=5432
postgres.database=wikid
postgres.user=wikidadmin
postgres.password=wikidone
postgres.driver=org.postgresql.Driver

# Database Management
postgres.version=16
postgres.service=postgresql-16
postgres.home=/var/lib/pgsql/16
wikid.create=true
wikid.update=true

# SSL/TLS Configuration
ssl=true
sslmode=verify-ca
sslkey=/opt/WiKID/private/client.p12
sslpassword=wikid
sslrootcert=/opt/WiKID/private/root.crt
sslhostnameverifier=com.wikidsystems.db.NoOpJdbcHostNameVerifier

# Debugging (disable in production)
debug.ssl=false

3.2 Verify Database Connection

# On each WiKID server, start the service
/opt/WiKID/bin/wikidctl start

# Check logs for connection errors
tail -50 /opt/WiKID/log/catalina.out
tail -50 /opt/WiKID/log/wikidpg.log

Last Updated: April 27, 2026
Build Tested: WiKID 5.9.16.b3102
PostgreSQL: Version 16
HAProxy: Version 1.8+