Deployment Guide

Deploying Joynare Nexus involves compiling the Go application for your target operating system and packaging it alongside your YAML configurations (flows/, routes/, and config/).

Because Joynare Nexus utilizes CGO (for packages like go-sqlite3 and alexbrainman/odbc), cross-compiling from Windows to Linux isn't straightforward without a specific C cross-compiler. The best practice is to build the application natively on the OS you intend to deploy it to.

---

1. Preparing the Environment

Depending on your target OS, you may need to install the golang compiler and the Unix ODBC development headers so that CGO can successfully build the database adapters.

Windows

On Windows, standard Go and GCC (via MinGW or similar) is sufficient.

Linux (Ubuntu / Debian / WSL)

sudo apt-get update
sudo apt-get install golang gcc zip unixodbc-dev

Linux (AlmaLinux / RHEL / CentOS)

On Enterprise Linux, the ODBC development headers are often located in the CRB (or PowerTools) repository which is disabled by default.

AlmaLinux 9 / RHEL 9:

sudo dnf config-manager --set-enabled crb
sudo dnf install golang gcc zip unixODBC-devel

AlmaLinux 8 / CentOS 8:

sudo dnf config-manager --set-enabled powertools
sudo dnf install golang gcc zip unixODBC-devel

(If you encounter a missing sql.h error during build, it means the unixODBC-devel package is missing!)

---

2. Deployment Scripts

We recommend standardizing your build output into separate dist/windows and dist/linux directories to prevent artifact mixing. We've provided two scripts to automate this process.

Building for Windows (build-deploy.ps1)

Run this in PowerShell if you plan to deploy to a Windows Server.

$ErrorActionPreference = "Stop"

$BaseDir = "dist"
$OutputDir = "$BaseDir/windows"
$ZipFile = "$BaseDir/joynare-nexus-windows.zip"
$BinaryName = "joynare-nexus.exe"

Write-Host "Cleaning up old Windows build..." -ForegroundColor Cyan
if (Test-Path $OutputDir) { Remove-Item -Path $OutputDir -Recurse -Force }
if (Test-Path $ZipFile) { Remove-Item -Path $ZipFile -Force }

Write-Host "Creating $OutputDir directory..." -ForegroundColor Cyan
New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null

Write-Host "Building Joynare Nexus for Windows..." -ForegroundColor Cyan
go build -o "$OutputDir/$BinaryName" ./cmd/esb

Write-Host "Copying configuration and resources..." -ForegroundColor Cyan
$FoldersToCopy = @("flows", "routes", "config")
foreach ($Folder in $FoldersToCopy) {
    if (Test-Path $Folder) {
        Copy-Item -Path $Folder -Destination "$OutputDir/$Folder" -Recurse -Force
    }
}

Write-Host "Packaging deployment archive ($ZipFile)..." -ForegroundColor Cyan
Compress-Archive -Path "$OutputDir\*" -DestinationPath $ZipFile -Force
Write-Host "Deployment package ready: $ZipFile" -ForegroundColor Green

Building for Linux (build-deploy.sh)

Run this in Bash (on your Linux server, or via WSL on Windows) if you plan to deploy to a Linux Server.

#!/bin/bash
set -e

BASE_DIR="dist"
OUTPUT_DIR="$BASE_DIR/linux"
ZIP_FILE="$BASE_DIR/joynare-nexus-linux.zip"
BINARY_NAME="joynare-nexus"

echo -e "\e[36mCleaning up old Linux build...\e[0m"
rm -rf "$OUTPUT_DIR"
rm -f "$ZIP_FILE"

echo -e "\e[36mCreating $OUTPUT_DIR directory...\e[0m"
mkdir -p "$OUTPUT_DIR"

echo -e "\e[36mBuilding Joynare Nexus for Linux...\e[0m"
go build -o "$OUTPUT_DIR/$BINARY_NAME" ./cmd/esb

echo -e "\e[36mCopying configuration and resources...\e[0m"
for folder in flows routes config; do
    if [ -d "$folder" ]; then cp -r "$folder" "$OUTPUT_DIR/" ; fi
done

echo -e "\e[36mPackaging deployment archive ($ZIP_FILE)...\e[0m"
cd "$OUTPUT_DIR"
zip -r "../joynare-nexus-linux.zip" ./* > /dev/null
cd ../..

echo -e "\n\e[32mDeployment package ready: $ZIP_FILE\e[0m"

(Make sure to grant execution permissions to the script: chmod +x build-deploy.sh)

---

3. Running as a Background Service (Linux systemd)

Once you transfer and unzip the deployment package onto your Linux server (e.g., into /opt/joynare-nexus), you should configure it as a systemd service so it runs continuously in the background and restarts on server reboots.

1. Ensure the binary has execute permissions:

   sudo chmod +x /opt/joynare-nexus/joynare-nexus

2. Create the service file:

   sudo nano /etc/systemd/system/joynare-nexus.service

3. Paste the following configuration:

   [Unit]
   Description=Joynare Nexus ESB
   After=network.target
   
   [Service]
   Type=simple
   User=root
   WorkingDirectory=/opt/joynare-nexus
   ExecStart=/opt/joynare-nexus/joynare-nexus serve
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target

4. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable joynare-nexus
   sudo systemctl start joynare-nexus
   sudo systemctl status joynare-nexus

You can now monitor the application logs using:

sudo journalctl -u joynare-nexus -f