Installer

This directory contains installer packages and build scripts for deploying Colibri Server as a system service on Linux, macOS, and Windows.

Overview

The installer system provides:

  • Configuration file support: server.conf for easy configuration management

  • System service integration: systemd (Linux), LaunchDaemon (macOS), Windows Service

  • Automatic startup: Server starts automatically on system boot

  • Security: Services run with restricted permissions

  • Firewall rules: Automatic configuration for the server port

Directory Structure

installer/
├── config/
│   ├── server.conf.template    # Template with placeholders
│   └── server.conf.default     # Default configuration
├── scripts/
│   ├── systemd/                # Linux systemd service
│   ├── launchd/                # macOS LaunchDaemon
│   └── windows/                # Windows service scripts
├── linux/
│   ├── debian/                 # Debian/Ubuntu package files
│   ├── rpm/                    # RPM package specs
│   ├── build_deb.sh           # Build Debian package
│   └── build_rpm.sh           # Build RPM package
├── macos/
│   ├── scripts/               # Pre/post-install scripts
│   └── build_pkg.sh          # Build macOS .pkg
└── windows/
    ├── colibri.wxs           # WiX installer definition
    ├── build_installer.ps1   # Build MSI installer
    └── install_service.ps1   # Manual service installation

Configuration File

The server can be configured via server.conf file in addition to environment variables and command-line arguments.

Priority order (lowest to highest):

  1. Default values (hardcoded)

  2. Config file (/etc/colibri/server.conf on Linux)

  3. Environment variables

  4. Command-line arguments

Config file locations:

  • Linux: /etc/colibri/server.conf

  • macOS: /usr/local/etc/colibri/server.conf

  • Windows: %PROGRAMDATA%\Colibri\server.conf (usually C:\ProgramData\Colibri\server.conf)

Configuration Parameters

See config/server.conf.default for all available options:

  • PORT - HTTP server port (default: 8090)

  • CHAIN_ID - Blockchain ID (1=Mainnet, 11155111=Sepolia, 17000=Holesky)

  • RPC - Comma-separated RPC endpoints

  • BEACON - Comma-separated Beacon API endpoints

  • MEMCACHED_HOST / MEMCACHED_PORT - Memcached configuration

  • And many more...

CMake Build Flag

The INSTALLER Flag

Installer packages are built using a dedicated CMake flag that is disabled by default to avoid unnecessary builds during regular development.

Usage

# Build with installer support
cmake -DHTTP_SERVER=ON -DINSTALLER=ON ..
make

# Regular build (no installer)
cmake -DHTTP_SERVER=ON ..
make

Requirements

  • INSTALLER=ON requires HTTP_SERVER=ON

  • If INSTALLER=ON but HTTP_SERVER=OFF, a warning is shown and installer targets are skipped

What Gets Enabled

When INSTALLER=ON is set:

  • CPack configuration is loaded

  • Installer-specific targets are created

  • Platform-specific package metadata is configured

  • Installation rules are set up

Default Behavior

By default (INSTALLER=OFF):

  • Regular server builds work normally

  • No installer-specific configuration is loaded

  • Build times are faster for development

  • No CPack dependencies required

Why This Design?

  • Faster developer builds: Developers don't need installer dependencies

  • Explicit intent: Installer builds are only created when explicitly requested

  • CI optimization: Avoids unnecessary work in non-installer workflows

  • Cleaner separation: Clear distinction between development and distribution builds

Example Workflows

Developer building for testing:

mkdir build && cd build
cmake -DHTTP_SERVER=ON -DPROVER=ON ..
make -j4 colibri-server
./default/bin/colibri-server

Packaging for distribution:

mkdir build && cd build
cmake -DHTTP_SERVER=ON -DPROVER=ON -DINSTALLER=ON ..
make -j4 colibri-server
cpack  # Creates platform-specific package

CI/CD automated build:

cd installer/macos
./build_pkg.sh 1.2.3  # Automatically sets INSTALLER=ON

Note: All build scripts in installer/linux/, installer/macos/, and installer/windows/ automatically set -DINSTALLER=ON, so you don't need to set it manually when using those scripts.

Building Installers

Linux (Debian/Ubuntu)

Requirements:

  • dpkg-dev, debhelper, cmake, gcc, g++

cd installer/linux
./build_deb.sh

Output: ../colibri-server_1.0.0-1_amd64.deb

Install:

sudo dpkg -i colibri-server_1.0.0-1_amd64.deb
sudo apt-get install -f  # Install dependencies if needed

Linux (RPM - RedHat/CentOS/Fedora)

Requirements:

  • rpm-build, rpmdevtools, cmake, gcc, gcc-c++

cd installer/linux
./build_rpm.sh

Output: ~/rpmbuild/RPMS/x86_64/colibri-server-1.0.0-1.x86_64.rpm

Install:

sudo rpm -ivh ~/rpmbuild/RPMS/x86_64/colibri-server-1.0.0-1.x86_64.rpm
# Or on Fedora/RHEL 8+:
sudo dnf install ~/rpmbuild/RPMS/x86_64/colibri-server-1.0.0-1.x86_64.rpm

macOS

Requirements:

  • Xcode Command Line Tools

  • CMake

cd installer/macos
./build_pkg.sh

Output: ../../colibri-server-1.0.0.pkg

Install:

sudo installer -pkg colibri-server-1.0.0.pkg -target /
# Or double-click the .pkg file in Finder

Windows

Requirements:

  • Visual Studio 2022 (or newer)

  • WiX Toolset v3.11+ (https://wixtoolset.org/)

  • CMake

cd installer\windows
.\build_installer.ps1

Output: ..\..\build\colibri-server-1.0.0.msi

Install:

# As Administrator:
msiexec /i colibri-server-1.0.0.msi
# Or double-click the MSI file

Service Management

Linux (systemd)

# Start service
sudo systemctl start colibri-server

# Stop service
sudo systemctl stop colibri-server

# Restart service
sudo systemctl restart colibri-server

# View status
sudo systemctl status colibri-server

# View logs
sudo journalctl -u colibri-server -f

# Enable/disable auto-start
sudo systemctl enable colibri-server
sudo systemctl disable colibri-server

macOS (LaunchDaemon)

# Start service
sudo launchctl start io.corpuscore.colibri-server

# Stop service
sudo launchctl stop io.corpuscore.colibri-server

# View logs
tail -f /var/log/colibri-server.log
tail -f /var/log/colibri-server.error.log

# Load/unload service
sudo launchctl load /Library/LaunchDaemons/io.corpuscore.colibri-server.plist
sudo launchctl unload /Library/LaunchDaemons/io.corpuscore.colibri-server.plist

Windows (Service)

# Start service
Start-Service -Name ColibriServer

# Stop service
Stop-Service -Name ColibriServer

# Restart service
Restart-Service -Name ColibriServer

# View status
Get-Service -Name ColibriServer

# View logs (Event Viewer)
Get-EventLog -LogName Application -Source ColibriServer -Newest 50

Uninstallation

Linux (Debian/Ubuntu)

sudo apt-get remove colibri-server
# Or purge to remove config files:
sudo apt-get purge colibri-server

Linux (RPM)

sudo rpm -e colibri-server
# Or on Fedora/RHEL 8+:
sudo dnf remove colibri-server

macOS

Recommended: Use the uninstall script

cd installer/macos
sudo ./uninstall.sh

The script will:

  • Stop and unload the service

  • Remove the binary and LaunchDaemon

  • Ask if you want to keep or remove config files and logs

See macos/UNINSTALL.md for manual uninstallation instructions.

Windows

# Via Control Panel > Programs and Features
# Or via command line:
msiexec /x {Product-GUID}

Customizing the Configuration

After installation, edit the configuration file:

Linux:

sudo nano /etc/colibri/server.conf
sudo systemctl restart colibri-server

macOS:

sudo nano /usr/local/etc/colibri/server.conf
sudo launchctl stop io.corpuscore.colibri-server
sudo launchctl start io.corpuscore.colibri-server

Windows:

notepad C:\ProgramData\Colibri\server.conf
Restart-Service -Name ColibriServer

Troubleshooting

Service won't start

  1. Check logs:

    • Linux: journalctl -u colibri-server -n 50

    • macOS: tail -n 50 /var/log/colibri-server.error.log

    • Windows: Event Viewer → Application logs

  2. Verify configuration:

    • Check for syntax errors in server.conf

    • Ensure RPC/Beacon endpoints are accessible

    • Verify port is not already in use

  3. Check permissions:

    • Linux: Ensure /var/lib/colibri is owned by colibri user

    • macOS: Ensure log files are writable

    • Windows: Ensure service has necessary permissions

Port already in use

Edit the config file and change PORT to a different value:

# Linux/macOS
sudo sed -i 's/PORT=8090/PORT=8091/' /etc/colibri/server.conf

# Windows
# Edit C:\ProgramData\Colibri\server.conf manually

Then restart the service.

Network connectivity issues

Ensure firewall rules allow incoming connections:

Linux:

sudo ufw allow 8090/tcp

macOS:

# Add rule via System Preferences > Security & Privacy > Firewall

Windows:

New-NetFirewallRule -DisplayName "Colibri Server" -Direction Inbound -Protocol TCP -LocalPort 8090 -Action Allow

CI/CD - Automated Installer Builds

Installer packages are automatically built via GitHub Actions on every push to main or dev branches, as well as on release tags.

Workflow Triggers

  1. On push to main/dev: Builds all installers and uploads them as artifacts (dev version)

  2. On version tags (v..*):** Builds release versions and creates a GitHub Release with all installer packages

  3. Manual trigger: Can be triggered manually via GitHub UI with custom version

Version Handling

  • Release tags (e.g., v1.2.3): Version extracted from tag → colibri-server-1.2.3.pkg

  • Branch pushes: Uses commit SHA → colibri-server-dev-abc1234.pkg

  • Manual builds: Uses provided version number

Downloading Pre-built Installers

From GitHub Releases:

# Get latest release
curl -s https://api.github.com/repos/corpus-core/colibri-stateless/releases/latest \
  | grep "browser_download_url.*\.pkg" \
  | cut -d '"' -f 4 \
  | xargs curl -L -O

From GitHub Actions Artifacts:

  1. Go to Actions tab → "Build Installers" workflow

  2. Select the workflow run

  3. Download artifacts (requires GitHub login)

Building Locally

To build installers locally with a custom version:

# macOS
cd installer/macos
./build_pkg.sh 1.2.3

# The version parameter is optional; defaults to 1.0.0

Development & Testing

To test the server without installing:

# Build server
mkdir -p build/test
cd build/test
cmake -DCMAKE_BUILD_TYPE=Release -DHTTP_SERVER=ON -DPROVER=ON -DVERIFIER=ON ../..
make -j4 colibri-server

# Create config
cp ../../installer/config/server.conf.default ./server.conf

# Run manually
./default/bin/colibri-server -c server.conf

License

The Colibri core library is licensed under the MIT License.

The server component (src/server/) is dual-licensed:

  • PolyForm Noncommercial License 1.0.0 for non-commercial use

  • Commercial License required for commercial use (contact jork@corpus.io)

Support

For issues, questions, or feature requests:

  • GitHub: https://github.com/corpus-core/colibri-stateless/issues

  • Email: jork@corpus.io

  • Documentation: https://corpus-core.gitbook.io/specification-colibri-stateless

PreviousEmbeddedNextMacOS

Last updated