Xamboo for Go

Introduction

Xamboo is the orchestration layer for APIs, microservices, and CMS modules into one cohesive platform for modern distributed architectures.

It orchestrates and manages:

APIs
Microservices
Web applications
Web pages
Full CMS systems
Administration backends

All as modular, dynamically compiled components working together under a unified engine.

Built in Go (1.24+), Xamboo is designed for:

Large-scale content distribution
High-performance REST and Graph APIs
Modular service architectures
Multi-host and multi-site environments

Xamboo is:

Plugin-based
Engine-driven
Modular-first
CMS-capable
Multi-host ready
Highly scalable
MIT licensed

| | |---------------------------------------------------------------------------------------------------------------------------------------------------| | # Architecture | | Incoming Request ↓ Listener (IP:Port) ↓ Host (Domain resolution) ↓ Components (Middleware chain) ↓ CMS Router ↓ Engine ↓ Page / Plugin ↓ Response |

Key Features

Core

Multi-site & virtual host support
Automatic plugin compilation (go build --buildmode=plugin)
Runtime page compilation
Hot configuration reload
Middleware-based architecture

CMS

Directory-based page resolution
Version & language support
Meta-language injection
Template engine
Language engine
Library engine (Go plugins)

Performance

500+ requests/sec production observed
3000+ requests/sec lab tested
TLS 1.2 / TLS 1.3
Gzip / Deflate compression
Code minification

Security

Basic authentication
SQL injection heuristic protection
IP blacklist support
CORS origin control

Installation & Deployment Guide

Overview

This chapter provides a complete, production-oriented guide to installing and running a fully functional Xamboo server environment.

Xamboo is built around a modular runtime architecture that dynamically compiles:

Engines
Components
Applications
CMS pages
XModules

Because Xamboo uses Go plugins (--buildmode=plugin), installation must be performed on a Unix/Linux environment.

System Requirements

Operating System

Linux (recommended)
Unix-based systems
❌ Windows is NOT supported (Go plugin limitation)

Software Requirements

Go 1.24+ (Go 1.26+ recommended)
Git
GNU Make (optional but recommended)
OpenSSL (if using HTTPS)

Verify Go installation:

go version

Installation Architecture

A typical Xamboo installation may include:

/home/sites/server
│
├── xamboo-env (core runtime)
├── master      (optional administration UI)
├── admin       (optional XModules administration)
└── your-sites  (your CMS projects)

Only xamboo-env is mandatory.
master and admin are optional but highly recommended for development and administration.

Step 1 — Create the Server Root Directory

mkdir -p /home/sites/server
cd /home/sites/server
git init

Step 2 — Install the Xamboo Runtime Environment

git pull https://github.com/webability-go/xamboo-env.git

Step 3 — (Optional) Install the Master Administration Interface

mkdir master
cd master
git init
git pull https://github.com/webability-go/xamboo-master.git
cd ..

Step 4 — (Optional) Install the Admin Interface

mkdir admin
cd admin
git init
git pull https://github.com/webability-go/xamboo-admin.git
cd ..

Step 5 — Configure the Server

Edit:

mainconfig.json
listeners.json
hosts.json

Example listener:

{
  "name": "server-http",
  "ip": "0.0.0.0",
  "port": "80",
  "protocol": "http",
  "readtimeout": 120,
  "writetimeout": 120,
  "headersize": 65536
}

Example host:

{
  "name": "mysite",
  "listeners": ["server-http"],
  "hostnames": ["example.com", "www.example.com"]
}

Ensure:

DNS points to the server IP
Firewall allows the configured ports

Linking Master & Admin

In mainconfig.json:

"include": [
  "master/config/hosts.json",
  "admin/config/hosts.json"
]

Step 6 — Download Dependencies

go get -u

⚠ Do NOT run:

go mod tidy

If accidentally executed, restore modules:

go get master
go get admin
go get github.com/webability-go/wajaf
go get github.com/webability-go/xdominion
go get github.com/webability-go/xdommask
go get github.com/webability-go/xmodules

and follow the sys logs entries to know if you need to restore more modules for recompilation of the .so libraries

Step 7 — Start the Server

./start.sh

Or:

go run xamboo.go --config=mainconfig.json

Step 8 — Build Production Binary (Optional)

go build xamboo.go

Xamboo dynamically compiles plugins at runtime when needed.

Step 9 — Run as a Service (Recommended)

Example systemd service:

[Unit]
Description=Xamboo Server
After=network.target

[Service]
WorkingDirectory=/home/sites/server
ExecStart=/home/sites/server/xamboo --config=mainconfig.json
Restart=always

[Install]
WantedBy=multi-user.target

There is a systemd directory into the main xamboo project, with example systemd file.

Summary of installation:

Install Go
Clone xamboo-env
(Optional) Install master/admin
Configure JSON files
Run go get -u
Start server

Xamboo handles dynamic compilation automatically.

Configuration Files

Overview

Xamboo is entirely driven by a JSON-based configuration system.

When starting the server, you must provide a configuration file:

xamboo --config=./mainconfig.json

You may use absolute paths, but relative paths are strongly recommended for portability.

All paths are resolved relative to the directory where Xamboo is launched.

Configuration Philosophy

Xamboo’s configuration system is:

Modular
Composable
Merge-based
Multi-file capable
Environment-friendly

You can split configuration across multiple files and include them dynamically.

Root Configuration Structure

{
  "pluginprefix": "prefix-",
  "log": {},
  "include": [],
  "listeners": [],
  "hosts": [],
  "components": [],
  "engines": []
}

Each section is optional within an individual file — but must exist at least once across the full merged configuration.

Configuration Merging & Includes

Main configuration:

{
  "log": {},
  "include": [
    "site1/config.json",
    "site2/config.json"
  ],
  "components": [],
  "engines": []
}

Site configuration example:

{
  "comments": "site1/config.json",
  "listeners": [ <LISTENER1>, <LISTENER2> ],
  "hosts": [ <HOST1> ]
}

{
  "comments": "site2/config.json",
  "listeners": [ <LISTENER3> ],
  "hosts": [ <HOST2> ]
}

Xamboo concatenates sections of the same type when merging. the result configuration would be (as interpreted by Xamboo):

{
  "log": {},
  "listeners": [ <LISTENER1>, <LISTENER2>, <LISTENER3> ],
  "hosts": [ <HOST1>, <HOST2> ],
  "components": [],
  "engines": []
}

1. pluginprefix

"pluginprefix": "instanceA-"

The plugin prefix is appended to every compiled .so plugin.

This prevents naming collisions when running multiple Xamboo instances on the same filesystem.

2. log Section

{
  "log": {
    "enabled": true,
    "sys": "file:./logs/xamboo-sys.log",
    "pages": "file:./logs/pages.log",
    "pagesformat": "%requestid% %clientip% %method% %protocol% %code% %request% %duration%",
    "errors": "file:./logs/errors.log",
    "stats": "discard"
  }
}

The log section can be defined at three levels within the configuration:

At the root level of the main configuration file (global log settings)
Inside each listener
Inside each host

Each level supports different log parameters.

Xamboo

Install / Use

README

Xamboo for Go

Introduction

Key Features

Core

CMS

Performance

Security

Installation & Deployment Guide

Overview

System Requirements

Operating System

Software Requirements

Installation Architecture

Step 1 — Create the Server Root Directory

Step 2 — Install the Xamboo Runtime Environment

Step 3 — (Optional) Install the Master Administration Interface

Step 4 — (Optional) Install the Admin Interface

Step 5 — Configure the Server

Linking Master & Admin

Step 6 — Download Dependencies

Step 7 — Start the Server

Step 8 — Build Production Binary (Optional)

Step 9 — Run as a Service (Recommended)

Summary of installation:

Configuration Files

Overview

Configuration Philosophy

Root Configuration Structure

Configuration Merging & Includes

1. pluginprefix

2. log Section