Page 1 of 5

Quick Start

Deploy and monitor multiple applications on your VPS. CICD is a single, zero-dependency binary that manages your entire server fleet.

Zero-Flag Core Execution

To run CICD, no flags are required at all. Running the binary directly sets up the internal database, auto-detects your VPS public IP, starts the webhook server on port 9641, and activates the web dashboard.

sudo ./cicd
Core Automatic Setup

On startup with no arguments, CICD:
1. Auto-detects your server public IP using api.ipify.org.
2. Initializes the SQLite database at the hardcoded path /etc/cicd/data/cicd.db.
3. Configures port 9641 as the default listener.
4. Exposes the Command Center dashboard at /dashboard.

Prerequisites

GitHub Authentication (Personal Access Token)

If your repository is private, the background agent needs a Personal Access Token (PAT) to securely pull and sync code to your server. We highly recommend using fine-grained tokens for minimum scope footprint.

3-Step Fine-Grained Token Setup

1. Navigate directly to the GitHub Fine-Grained Personal Access Tokens Creator.
2. Set the Repository access to either All repositories or Only select repositories (choosing your specific project repo).
3. Under Repository permissions, expand the Contents resource category and set its permission level to Read-only (or Read & Write if your application writes tags/logs back to the git branch directly).

How to Properly Setup Webhooks

To enable instant deployments on git push, you must register a secure webhook inside GitHub. This triggers a cryptographic signature-validated dispatch to your background daemon.

Secure Webhook Setup Steps

1. Go to your GitHub repository page, click Settings, and choose Webhooks in the left-hand sidebar.
2. Click the Add webhook button in the top-right corner.
3. Enter your Payload URL: http://YOUR-SERVER-PUBLIC-IP:9641/ (Ensure the trailing slash / is present).
4. Change Content type to application/json (important — standard forms will not be parsed properly by the API).
5. Paste your Secret key: This is your HMAC signature validation secret (auto-generated by our command builder or defined via --webhook-secret).
6. Select Just the push event, leave the webhook active, and click Add webhook.

Installation & Deployment

1

Download and Install

Run the universal shell installer. It auto-detects your operating system (Linux, macOS) and hardware architecture (Intel/AMD x86, ARM64, 386) to fetch the correct binary:

# Install via Curl:
curl -fsSL https://cicd.rf.gd/install.sh | sh

# Or install via Wget:
wget -qO- https://cicd.rf.gd/install.sh | sh
2

Start the Core Daemon

Run the core binary with zero flags. This registers the background systemd daemon, reads configuration, and hosts the Command Center dashboard:

sudo ./cicd

Look at the terminal output to copy your setup token and the dashboard link:

Terminal — Initial Setup Output 
======================================================================
 🖥️  STEP 1: ACCESS YOUR ADMIN DASHBOARD
======================================================================
  1. Open your browser and navigate to the Dashboard URL.
  2. Copy and paste the Setup Token below to log in (expires in 15m).
  3. In the login page you have to click `USE SETUP TOKEN` button and paste the token.

╭──────────────────┬───────────────────────────────────╮
│ 🌐 Dashboard URL │ http://127.0.0.1:9641/dashboard   │
│ 🔑 Setup Token   │ Failed to load active setup token │
╰──────────────────┴───────────────────────────────────╯

======================================================================
 🛰️  STEP 2: CONNECT GITHUB (WEBHOOK SETUP)
======================================================================
  1. Go to your GitHub repository -> Settings -> Webhooks -> Add Webhook.
  2. Set Payload URL, select 'application/json', and paste the Secret key.

╭───────────────────┬──────────────────────────────────╮
│ 🔌 Payload URL    │ http://127.0.0.1:9641/           │
│ ⚙️  Content Type  │ application/json                 │
│ 🔒 Secret Key     │ d6016594455bca3c20fdf3e7d8486931 │
╰───────────────────┴──────────────────────────────────╯

======================================================================
 🎥 STEP 3: NEED HELP? WATCH VIDEO GUIDE
======================================================================
  Watch the latest YouTube guide on configuring GitHub webhooks:
  https://www.youtube.com/watch?v=MyEkKp3VRwo
======================================================================
⚙️  SYSTEMD SERVICE MANAGEMENT:
  - To view gateway info:            cicd info
  - To monitor live background logs:  cicd log -f
  - To check systemd service status:  cicd status
  - To view list of active services:  cicd ls
  - To view all commands:             cicd commands
3

Register Your Projects

Once started, there are two simple ways to add projects to the fleet:

  • Web Dashboard (Recommended): Log in to the dashboard at http://YOUR-SERVER-IP:9641/dashboard using your setup token, click "New Project", and enter your repository details visually.
  • Command Line: If you prefer CLI setup, use the Interactive Command Builder on the homepage to generate a custom startup command containing all your configurations (such as SMTP credentials for email alerts, webhook secrets, and custom branch rules).
4

Connect GitHub Webhooks

Add a Webhook to your GitHub repository under Settings → Webhooks → Add Webhook:

FieldValue
Payload URLhttp://YOUR-SERVER-IP:9641/
Content typeapplication/json
SecretYour --webhook-secret (find it anytime with cicd info)
EventsJust the push event

Override Configurations

CLI flags are used to overwrite default settings. For example, if you are testing locally or behind a proxy and want to bypass the public IP auto-lookup:

sudo ./cicd --public-ip 127.0.0.1

Cloud Provider Firewall Rules

Make sure to allow inbound traffic on port 9641:

← All Docs Next: The .cicd Folder →