Skip to main content

MaxKB v2.4.1 (CentOS 9) AMI Administrator Guide

1. Quick Start Information​

Install Information:

  • OS: CentOS Stream 9
  • MaxKB version: 2.4.1
  • MaxKB Install Directory: /opt/maxkb

MaxKB Service Management:

  • To start MaxKB Service: sudo mkctl start
  • To stop MaxKB Service: sudo mkctl stop
  • To status MaxKB Service: sudo mkctl status
  • To restart MaxKB Service: sudo mkctl restart

Accessing MaxKB:

  • Visit https://YOUR_IP to start using MaxKB.
  • Note: The service may take a few minutes to start on the first boot. If the page fails to load, please wait patiently.

Web username and password:

  • View via the command: sudo cat /opt/maxkb/readme

Firewall Configuration:

  • Please allow SSH port 22 and MaxKB port 443.
  • For security, it is recommended to limit access to trusted IPs only.

Recommended:

  • 4 Cores / 8GB RAM or higher

2. Overview​

Welcome to the Easycloud optimized MaxKB v2.4.1 AMI. This image is based on CentOS Stream 9 and has been pre-configured as a secure, auto-starting production environment.

MaxKB is an enterprise-grade knowledge base Q&A system based on LLMs. This AMI is built from the official v2.4.1 offline package and has been security-hardened by the Easycloud team, pre-installing Nginx HTTPS reverse proxy and optimized firewall rules.

Core Features of this AMI:

  • Full-featured: Based on the official offline installation package (Docker Compose), includes all dependencies.
  • Secure:
    • Default deployment of Nginx as a high-performance reverse proxy.
    • Default enabled HTTPS (SSL) (using a self-signed certificate) to ensure all data transmission is encrypted.
  • Automated: Nginx and Docker services both auto-start on boot via systemd.

3. First Launch & Access (Mandatory)​

Step 1: Configure Security Group (Cloud Firewall)​

In your cloud provider's console (e.g., AWS EC2), add inbound rules to the security group for this instance to allow:

  • TCP Port 443 (HTTPS): Required for accessing the MaxKB Web interface (Mandatory).
  • TCP Port 22 (SSH): (Optional) Allows logging into the server for management.

Step 2: Access the MaxKB Instance​

  1. Get your instance's public IP address.
  2. Open a brand new browser "Incognito Window".
  3. In the address bar, type https:// and your IP address (do not add a port number): https://[Your_Public_IP]

Step 3: Handle the SSL Security Warning​

  1. You will see a full-screen security warning ("NET::ERR_CERT_AUTHORITY_INVALID").
  2. This is normal, because this AMI uses a self-signed certificate to ensure traffic is encrypted.
  3. Please click "Advanced" -> "Proceed to [IP Address] (unsafe)".

Step 4: Login​

You will now see the MaxKB login page.

4. AMI Detailed Configuration & Architecture​

  • Service Architecture: [Public] -> Nginx (Port 443, SSL) -> MaxKB Docker (127.0.0.1:8080)
  • Application Directory: /opt/maxkb (Based on official install.conf default)

4.1. MaxKB Application (Docker Compose) - Installation Steps​

This AMI is built based on the MaxKB official v2.4.1 offline package. The following are the core installation steps performed when building the AMI:

Path​

/opt/maxkb

Configuration (How-To-Create)​

# (As root) 1. Prepare environment
# (This AMI has docker and docker-compose pre-installed)
# sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# sudo systemctl enable --now docker

# (As root) 2. Upload and decompress the official offline package
# (Assuming the official package name is maxkb-v2.4.1-x86_64-offline-installer.tar.gz)
# cd /opt/
# tar -zxvf maxkb-v2.4.1-x86_64-offline-installer.tar.gz

# (As root) 3. Execute installation
# (The installation script will use the default value MAXKB_BASE=/opt from install.conf)
# cd maxkb-v2.4.1-x86_64-offline-installer
# bash install.sh

# (As root) 4. Validate MaxKB local startup
# (At this point, MaxKB is running on 0.0.0.0:8080, waiting for Nginx proxy)
# /opt/maxkb/mkctl status

4.2. MaxKB Application Configuration (.env file)​

According to the official documentation, MaxKB's core configuration after installation is stored in the .env file.

Path​

/opt/maxkb/.env

How to Modify Configuration (e.g., Port or Database)​

  1. Log in to the server via SSH.
  2. Edit the .env file: 
    sudo vi /opt/maxkb/.env
  3. Modify the parameters you need (e.g., MAXKB_PORT or MAXKB_PGSQL_HOST).
  4. (Critical) After modification, you must run MaxKB's mkctl reload command to reload the configuration: 
    # Enter MaxKB directory
    cd /opt/maxkb
    # Reload configuration
    sudo mkctl reload

4.3. Nginx Reverse Proxy (SSL) - Security Hardening​

This is the security layer added to the AMI by Easycloud.

Path​

/etc/nginx/conf.d/maxkb.conf

File Content​

# =========================================================
# HTTP Server Block (Redirect HTTP to HTTPS)
# =========================================================
server {
    listen 80;
    listen [::]:80;

    # Catch-all server name
    server_name _;

    # Permanently redirect (301) all HTTP requests to HTTPS
    return 301 https://$host$request_uri;
}

# =========================================================
# HTTPS Server Block (Main Application)
# =========================================================
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name _;

    # SSL Certificate configuration
    ssl_certificate /etc/nginx/ssl/maxkb.crt;
    ssl_certificate_key /etc/nginx/ssl/maxkb.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:8080;

        # Proxy headers to forward client information
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support (required for some real-time features)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Configuration (How-To-Create)​

# (As root) 1. Install Nginx
sudo dnf install nginx -y
sudo systemctl enable --now nginx

# (As root) 2. Create self-signed certificate (10-year validity)
sudo mkdir -p /etc/nginx/ssl
sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
 -keyout /etc/nginx/ssl/maxkb.key \
 -out /etc/nginx/ssl/maxkb.crt \
 -subj "/C=US/ST/N/A/L/N/A/O=MaxKB/CN=localhost"

# (As root) 3. Create Nginx config file
sudo vi /etc/nginx/conf.d/maxkb.conf
# (Paste the Nginx config content above)

# (As root) 4. Restart Nginx
sudo nginx -t && sudo systemctl restart nginx

5. Credentials and Security (Mandatory)​

Default Credentials​

Execute the following command to get the initial username and password

sudo cat /opt/maxkb/readme

Note: You will be required to change your password upon first login.

6. Service Management (Quick Reference)​

Manage MaxKB (Application)​

MaxKB comes with a dedicated management script, mkctl.

  • Path: cd /opt/maxkb
  • Check Status: sudo mkctl status
  • Stop MaxKB: sudo mkctl stop
  • Start MaxKB: sudo mkctl start
  • Restart MaxKB: sudo mkctl restart
  • Reload Configuration (After modifying .env file): sudo mkctl reload

Manage Nginx (Web Proxy)​

  • Check Nginx Status: sudo systemctl status nginx
  • Restart Nginx: sudo systemctl restart nginx
  • Check Nginx Logs: sudo journalctl -u nginx -f

7. Troubleshooting​

  • Problem: Cannot connect to the server.
    • Solution: Check your cloud provider's Security Group to ensure TCP Port 443 is open to your IP.
  • Problem: I see a "502 Bad Gateway" error.
    • Solution: This means Nginx is running, but the MaxKB application is not responding on port 8080.
    • Diagnose: cd /opt/maxkb then run sudo mkctl status.
    • Fix: If the service is not running, run sudo mkctl start to start MaxKB.
  • Problem: I see a "400 Bad Request" error.
    • Solution: Ensure you are typing https:// in your browser's address bar, not http://. Use an incognito window.