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):

Default values (hardcoded)
Config file (/etc/colibri/server.conf on Linux)
Environment variables
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

Check logs:
- Linux: journalctl -u colibri-server -n 50
- macOS: tail -n 50 /var/log/colibri-server.error.log
- Windows: Event Viewer → Application logs
Verify configuration:
- Check for syntax errors in server.conf
- Ensure RPC/Beacon endpoints are accessible
- Verify port is not already in use
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

On push to main/dev: Builds all installers and uploads them as artifacts (dev version)
On version tags (v..*):** Builds release versions and creates a GitHub Release with all installer packages
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:

Go to Actions tab → "Build Installers" workflow
Select the workflow run
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

PreviousEmbedded NextMacOS

Last updated 3 months ago

hashtagOverview

hashtagDirectory Structure

hashtagConfiguration File

hashtagConfiguration Parameters

hashtagCMake Build Flag

hashtagThe INSTALLER Flag

hashtagUsage

hashtagRequirements

hashtagWhat Gets Enabled

hashtagDefault Behavior

hashtagWhy This Design?

hashtagExample Workflows

hashtagBuilding Installers

hashtagLinux (Debian/Ubuntu)

hashtagLinux (RPM - RedHat/CentOS/Fedora)

hashtagmacOS

hashtagWindows

hashtagService Management

hashtagLinux (systemd)

hashtagmacOS (LaunchDaemon)

hashtagWindows (Service)

hashtagUninstallation

hashtagLinux (Debian/Ubuntu)

hashtagLinux (RPM)

hashtagmacOS

hashtagWindows

hashtagCustomizing the Configuration

hashtagTroubleshooting

hashtagService won't start

hashtagPort already in use

hashtagNetwork connectivity issues

hashtagCI/CD - Automated Installer Builds

hashtagWorkflow Triggers

hashtagVersion Handling

hashtagDownloading Pre-built Installers

hashtagBuilding Locally

hashtagDevelopment & Testing

hashtagLicense

hashtagSupport

Overview

Directory Structure

Configuration File

Configuration Parameters

CMake Build Flag

The INSTALLER Flag

Usage

Requirements

What Gets Enabled

Default Behavior

Why This Design?

Example Workflows

Building Installers

Linux (Debian/Ubuntu)

Linux (RPM - RedHat/CentOS/Fedora)

macOS

Windows

Service Management

Linux (systemd)

macOS (LaunchDaemon)

Windows (Service)

Uninstallation

Linux (Debian/Ubuntu)

Linux (RPM)

macOS

Windows

Customizing the Configuration

Troubleshooting

Service won't start

Port already in use

Network connectivity issues

CI/CD - Automated Installer Builds

Workflow Triggers

Version Handling

Downloading Pre-built Installers

Building Locally

Development & Testing

License

Support