Skip to content
Kafka Mobility Intelligence

Air-Gapped Deployment (Docker Compose)

This page provides step-by-step instructions for deploying KMI in air-gapped (offline) environments. The air-gap package contains all necessary Docker images and configuration files for deployment in environments without internet access.

Minimum System Requirements

Section titled “Minimum System Requirements”

Hardware

Section titled “Hardware”
ResourceMinimumRecommended
CPU2 cores4 cores
RAM4 GB8 GB
Disk10 GB free20 GB free

CPU Architecture

Section titled “CPU Architecture”

The suite is available for both amd64 and arm64 architectures. Make sure you are using the bundle that matches your host architecture.

Software

Section titled “Software”
SoftwareVersion
Docker Engine20.10 or later
Docker Composev2.0 or later

Verify your Docker installation:

Terminal window
docker --version
docker compose version

Network Ports

Section titled “Network Ports”

The following ports must be available on the host:

PortServicePurpose
3000FrontendWeb UI access
27017MongoDBDatabase (internal)
18002BackendData Replicator API
18003BackendMonitoring Service API
18004BackendWebSocket connections
9310-9399Metrics CollectorsDynamic port range for collectors

Prerequisites

Section titled “Prerequisites”

Before starting the installation:

  1. Ensure Docker is installed and running.
  2. Ensure the current user has permissions to run Docker commands.
  3. Ensure all required ports are available.
  4. Transfer the air-gap package to the target server.

Package Contents

Section titled “Package Contents”

The air-gap package contains:

Docker bundle (kmi-airgap-docker-vX.x-<arch>.tar.gz):
  deploy.sh           # Deployment script
  docker-compose.yml  # Container orchestration
  .env.example        # Configuration template
  mongo-init.sh       # Database initialization script
  images.tar.gz       # Pre-built Docker images
  README.md           # This guide


Kubernetes bundle (kmi-airgap-kubernetes-vX.x-amd64.tar.gz):
  k8s-deploy.sh       # Deployment script for K8s
  k8s-deploy-package/ # Helm charts for K8s
  .env.example        # Configuration template
  mongo-init.sh       # Database initialization script
  images.tar.gz       # Pre-built Docker images
  README.md           # This guide

Installation Steps

Section titled “Installation Steps”

  1. Extract the package.

    Terminal window
    tar -xzf kmi-airgap-docker-vX.x-amd64.tar.gz -C /path/to/deploy
    cd /path/to/deploy

  2. Create the configuration file.

    Copy the example configuration and edit it:

    Terminal window
    cp .env.example .env

    Open .env in your preferred editor and configure all required values. See the Configuration Reference below for details.

  3. Generate secrets.

    Generate secure values for JWT_SECRET and AES_KEY:

    Terminal window
    # Generate JWT secret (16 bytes hex)
    openssl rand -hex 16
    

    # Generate AES key (32 bytes hex)
    openssl rand -hex 32

    Copy these values into your .env file.

  4. Run the deployment script.

    Terminal window
    ./deploy.sh

    The script loads Docker images from images.tar.gz, creates the Docker network, and starts all services.

  5. Verify the deployment.

    Wait approximately 30-60 seconds for all services to initialize, then verify:

    Terminal window
    docker ps

    You should see these containers running:

    • kmi-mongodb
    • kmi-frontend
    • kmi-backend

  6. Access the application.

    Open your browser and navigate to:

    http://<server-ip>:3000

    Log in with the admin credentials you configured in the .env file.

Configuration Reference

Section titled “Configuration Reference”

MongoDB Credentials

Section titled “MongoDB Credentials”
Terminal window
MONGO_USERNAME=your_mongo_username
MONGO_PASSWORD=your_mongo_password

These credentials are used internally by the application to connect to MongoDB. Choose strong, unique values.

Admin User

Section titled “Admin User”
Terminal window
ADMIN_USER_ID=admin
ADMIN_EMAIL=admin@yourcompany.com
ADMIN_PASSWORD=your_secure_password

This is the initial administrator account for logging into the web interface.

Service Account Emails

Section titled “Service Account Emails”
Terminal window
DATA_REPLICATION_SERVICE_EMAIL=datarepl@yourcompany.com
SCHEMA_REPLICATION_SERVICE_EMAIL=schemarepl@yourcompany.com
KAFKA_CLI_SERVICE_EMAIL=kafkacli@yourcompany.com
MONITORING_SERVICE_EMAIL=monitoring@yourcompany.com
COLLECTOR_SERVICE_EMAIL=collector@example.com

These are internal service accounts used for inter-service authentication. They do not need to be real email addresses, but must be unique.

Application Secrets

Section titled “Application Secrets”
Terminal window
JWT_SECRET=<generated-16-byte-hex>
JWT_EXPIRES_IN=8h
JWT_EXPIRES_INT=8
USE_SECURE_COOKIES=false
AES_KEY=<generated-32-byte-hex>
VariableDescription
JWT_SECRETSecret key for signing authentication tokens
JWT_EXPIRES_INToken expiration time (for example, 8h, 24h, 7d)
JWT_EXPIRES_INTNumeric value matching JWT_EXPIRES_IN
USE_SECURE_COOKIESSet to true if using HTTPS
AES_KEYEncryption key for sensitive data storage

Service Ports

Section titled “Service Ports”
Terminal window
MONGODB_PORT=27017
FRONTEND_PORT=3000
DATA_REPLICATOR_PORT=18002
MONITORING_SERVICE_PORT=18003
MONITORING_SOCKET_PORT=18004

Modify these only if you have port conflicts on your system.

Post-Installation Verification

Section titled “Post-Installation Verification”

Check container status:

Terminal window
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

All containers should show an “Up” status.

Common Operations

Section titled “Common Operations”

View Logs

Section titled “View Logs”
Terminal window
# Follow all logs
docker compose logs -f


# Follow a specific service
docker compose logs -f frontend

Stop Services

Section titled “Stop Services”
Terminal window
docker compose down

Start Services

Section titled “Start Services”
Terminal window
docker compose up -d

Restart with a Fresh Database

Section titled “Restart with a Fresh Database”
Terminal window
docker compose down -v
docker compose up -d

Update Configuration

Section titled “Update Configuration”

After modifying .env:

Terminal window
docker compose down
docker compose up -d

Troubleshooting

Section titled “Troubleshooting”

UI Shows “Internal Server Error” on Login

Section titled “UI Shows “Internal Server Error” on Login”

Symptom: Login fails with an internal server error.

Cause: Usually indicates database connection issues.

Solution:

  1. Check the database is running: docker ps | grep mongodb
  2. Check the database logs: docker logs kmi-mongodb
  3. Verify the credentials in .env match what the database was initialized with.
  4. If the credentials were changed, restart with fresh volumes.
  5. Make sure you are using the bundle with the correct architecture.

Backend Shows Authentication Timeouts

Section titled “Backend Shows Authentication Timeouts”

Symptom: Backend logs show repeated timeout errors connecting to the UI.

Cause: Services started before dependencies were ready, or performance issues on slower systems.

Solution:

  1. Restart the backend: docker compose restart kmi-backend
  2. If persistent, increase the Docker memory allocation.

Port Already in Use

Section titled “Port Already in Use”

Symptom: A container fails to start with a “port already in use” error.

Solution:

  1. Find what is using the port: lsof -i :<port>
  2. Either stop the conflicting service or change the port in .env.

Services Cannot Communicate

Section titled “Services Cannot Communicate”

Symptom: Services fail to connect to each other.

Solution:

  1. Verify the Docker network exists: docker network ls | grep kmi
  2. If missing, create it: docker network create kmi-network
  3. Restart services: docker compose down && docker compose up -d

Known Limitations

Section titled “Known Limitations”
  • Air-gap updates: To update the application, you must obtain a new air-gap package and redeploy. In-place updates are not supported.
  • Single node: This deployment is designed for single-node installations. High-availability configurations require additional setup not covered here.
  • License required: The application requires a valid license key for operation. Contact your administrator to obtain a license.

Support

Section titled “Support”

For issues not covered here, collect the following information before contacting support:

Terminal window
# System information
uname -a
docker --version
docker compose version


# Container status
docker ps -a


# Recent logs
docker compose logs --tail=100