Web App Deployment Guide

This guide details how to deploy the IBM i AI Platform Web Application in a production environment. It assumes you have already completed Setup & Connectivity to configure your AI provider and IBM i access.

1. Server Prerequisites

Before deploying, ensure the following are installed on the host server:

Runtime

  • Node.js 24+: The runtime for the Hono web server.
  • npm: For dependency management and execution.

Databases & Drivers

  • IBM i Access ODBC Driver: Required for IBM i connectivity. Ensure it is registered in the system's ODBC configuration (e.g., odbcinst.ini on Linux).
  • PostgreSQL 15+: Used for the control plane (user management, session storage, and approval logs).

Network

  • Inbound: Port 3000 (default) or your configured NODE_SERVER_PORT.
  • Outbound:
    • IBM i ODBC/SQL: Ports 449, 8470-8476, 9470-9476.
    • IBM i SSH: Port 22.
    • PostgreSQL: Port 5432.
    • AI Provider: Outbound HTTPS to your provider's API.

2. Environment Configuration

Create a .env file in the application root. Use the provided .env.example as a template.

Essential Variables

Control Plane (Postgres)

PG_CONNECTION_STRING=postgres://user:password@host:5432/ibmi_ai

Authentication (Better Auth)

BETTER_AUTH_URL=https://your-domain.com
BETTER_AUTH_SECRET=a-very-long-random-string
ENCRYPTION_SECRET=another-long-random-string

IBM i Connectivity

DB2_HOST=your-ibmi-hostname
DB2_USER=your-service-user
DB2_PASSWORD=your-service-password
DB2_SCHEMA=YOUR_SCHEMA

AI Provider

Configure your chosen provider as described in Setup & Connectivity. You will typically set AI_API_KEY, AI_BASE_URL (if local), and AI_MODEL.

3. Database Setup

The web application requires initial migrations and optional seeding for the control plane.

Run Migrations

Execute the following command to create the necessary tables in your PostgreSQL instance:

npm run cli -- db migrate

Seed Initial Data (Optional)

To populate the database with initial roles or demo users:

npm run cli -- db seed

4. Build and Execution

Build the Application

Compile the client-side React code and the server-side Hono code:

npm run build

This will generate a dist directory containing the production-ready assets.

Start the Production Server

Use a process manager like PM2 to ensure the application stays running:

NODE_ENV=production node dist/server/index.js

5. Security and Governance

Reverse Proxy

Run the application behind a reverse proxy like Nginx or Apache to provide:

  • SSL/TLS Termination: Ensure all traffic is encrypted via HTTPS.
  • Port Forwarding: Map port 80/443 to the application's internal port.
  • Compression: Gzip or Brotli compression for faster asset delivery.

Secrets Management

Ensure that BETTER_AUTH_SECRET and ENCRYPTION_SECRET are rotated periodically and stored in a secure secrets manager (e.g., AWS Secrets Manager, Azure Key Vault). Never commit secrets to source control.

Audit Logs

The application logs critical events to the PostgreSQL database. Regularly review the approval_logs and session_logs to ensure compliance with your organization's security policies.