unholyw4r/ferryx-hub

🚢 Ferryx Hub

Secure remote job triggering for closed / private networks (***-only, no static IP, inbound blocked). Ferryx is a lightweight hub-and-worker system designed to manage deployments and operational tasks across closed, local, or ***-restricted networks.

The Hub runs on a public server and can be triggered externally via authenticated HTTP requests. When triggered, it uses SignalR to notify all connected Workers that match the configured application and group definitions.

Workers run inside private or isolated environments and maintain an outbound connection to the Hub. Each Worker executes a run.sh script located in a group-specific directory, allowing DevOps teams to define any deployment, maintenance, or control logic using standard shell scripting.

Trigger requests can include dynamic parameters such as target, tag, and custom metadata. These values are injected into the Worker execution context, enabling flexible and reusable deployment pipelines, environment resets, service restarts, or infrastructure orchestration.

Security is handled using JWT authentication generated by the Hub. External triggers authenticate via Bearer tokens, while Workers authenticate using environment variables, ensuring secure communication without exposing inbound ports.

Ferryx enables CI/CD, Swarm orchestration, and operational automation in environments that are otherwise unreachable from the internet.

---

✨ What it solves

Ferryx is built for environments where you cannot reliably reach servers from the internet:

• No static IP
• Inbound traffic blocked (NAT / firewall)
• ***-only or fully private networks

Instead of connecting into those networks, Workers connect outbound to a central Hub.
You trigger jobs via the Hub using authenticated HTTP requests, and the Hub dispatches signals to the right workers.

---

🧱 Architecture

🌐 Ferryx Hub (publicly accessible)

• Receives authenticated HTTP requests (JWT)
• Routes signals by Target + Group
• Dispatches notifications via SignalR

🔒 Ferryx Worker (private / restricted networks)

• Runs inside the closed network
• Establishes an outbound connection to️ to the Hub
• Subscribes to a single group (environment)
• Executes jobs when triggered

---

🚀 Quick Start (Docker)

1) Run Hub

bash
docker run -d --name ferryx --restart unless-stopped   -p 18080:18080   -v /etc/ferryx:/etc/ferryx   unholyw4r/ferryx-hub:latest

2) Use built-in CLI (inside container)

bash
docker exec -it ferryx ferryx where
docker exec -it ferryx ferryx reconfig
docker exec -it ferryx ferryx jwt

• where → prints the config directory path
• reconfig → reloads Hub using the latest config file
• jwt → prints a Hub JWT token (HUB TOKEN)

---

📁 Configuration

Hub config path:

bash
/etc/ferryx/ferryx-hub.json

Example:

json
{
  "Server": {
    "Env": "hub",
    "Bind": "0.0.0.0",
    "Port": 18080,
    "ControlPort": 18081
  },
  "Security": {
    "JwtKey": "BASE64_SECRET_KEY"
  },
  "Services": {
    "my-app": {
      "Groups": ["workgroup"]
    },
    "my-app-2": {
      "Groups": ["groupname"]
    },
  }
}

Concepts

🎯 Target (my-app)

A Target is a logical application / destination.
Name it however you want (e.g. billing-api, frontend, my-app).

👥 Groups (groupname, workgroup)

A Group is a SignalR channel under a target.
Workers subscribe to exactly one group and only receive signals for that group.

---

🔐 Security (JWT)

All Hub API calls require JWT.

Generate a token:

bash
docker exec -it ferryx ferryx jwt

Token notes:

• Long-lived (10 years)
• No revocation / lifecycle management
• Signature validation only (key-based)
• Intended for infrastructure-level trust

---

🔔 Triggering a job (Hub API)

Trigger via authenticated HTTP POST.

bash
curl --location 'http://HUB_ADDRESS/api/deploy'   --header 'Authorization: Bearer HUB_JWT'   --header 'Content-Type: application/json'   --data '{
    "env": "pre-prod",
    "target": "my-app",
    "tag": "v1",
    "meta": {
      "latestimage": "xxxx"
    }
  }'

📁 Github Workflow Example

.github/workflows yml:

bash
name: Deploy pre-prod

on:
  push:
    branches:
      - main
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Call Ferryx Deploy API
        run: |
          curl --fail --location 'http://HUB_ADDRESS:18080/api/deploy' \
            --header "Authorization: Bearer ${{ secrets.FERRYX_DEPLOY_TOKEN }}" \
            --header 'Content-Type: application/json' \
            --data '{
              "env": "pre-prod",
              "target": "my-app",
              "tag": "v1",
              "meta": {
                 "latestimage": "example image"
              }
            }'

📁 Jenkinsfile Example

bash
pipeline {
  agent any

  environment {
    FERRYX_DEPLOY_TOKEN = credentials('ferryx-deploy-token')
  }

  stages {
    stage('Deploy pre-prod') {
      steps {
        sh '''
        curl --fail --location 'http://HUB_ADDRESS:18080/api/deploy' \
          --header "Authorization: Bearer $FERRYX_DEPLOY_TOKEN" \
          --header 'Content-Type: application/json' \
          --data '{
            "env": "pre-prod",
            "target": "my-app",
            "tag": "v1",
            "meta": {
              "latestimage": "ImageName",
              "val1": "ferryx_001",  
            }
          }'
        '''
      }
    }
  }
}

Payload fields

• env *(optional)
• target (required) → selects the target
• tag (optional) → informational label (version, release, etc.)
• meta (optional) → dynamic metadata object (free-form)

When the request is received:

1. JWT is validated
2. Target is resolved
3. Group is selected
4. All subscribed workers are notified

---

🧑‍🏭 Worker

Run Worker

bash
docker run -d      --restart unless-stopped  --user 0:0   -p 16080:16080   -e FERRYX_HUB_URL="http://HUB_ADDRESS:18080"   -e FERRYX_HUB_TOKEN="HUB_JWT"   -e FERRYX_GROUP="workgroup"   -v /ferryx/operation:/ferryx/operation   -v /var/run/docker.sock:/var/run/docker.sock   unholyw4r/ferryx-worker:latest

Required environment variables

• FERRYX_HUB_URL → Hub address (IP or domain)
• FERRYX_HUB_TOKEN → JWT generated by the Hub
• FERRYX_GROUP → group name to subscribe to

---

⚙️ Job execution

Worker executes:

bash
/ferryx/operation/{WorkGroupName}/run.sh

Use it for:

• Deployment scripts
• System operations
• Custom automation workflows

Edit Worker Job (Example)

bash
#!/usr/bin/env bash
set -e

FromPostMetaDatasImage="{{ferryx_Meta.latestimage}}"
FromPostMetaDatasValue1="{{ferryx_Meta.val1}}"

FromPostEnv="{{ferryx_Env}}"
FromPostTarget="{{ferryx_Target}}"
FromPostTag="{{ferryx_Tag}}"

docker pull "${APPIMAGE}"

---

✅ Summary

• Public Hub + Private Workers
• Workers connect outbound-only
• Routing via Target + Group
• Trigger jobs using authenticated HTTP requests
• Best fit for ***-only, private or restricted environments