Skip to content

Commit fd76167

Browse files
yiiman-devyiiman-dev
committed
Update ReadMe
1 parent 1a7893f commit fd76167

1 file changed

Lines changed: 101 additions & 124 deletions

File tree

‎README.md‎

Lines changed: 101 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -3,154 +3,131 @@
33
A secure web service that executes CLI commands based on authenticated HTTP requests.
44

55
## Features
6+
# CI/CD CLI Controller
7+
8+
Purpose
9+
10+
This repository implements a small, secure HTTP-driven command executor intended to run pre-configured, non-interactive shell commands in response to authenticated API requests. It is designed as a safe bridge between event sources (webhooks, internal dashboards, or CI systems) and deterministic maintenance or deployment scripts. Security is a first-class concern: the service is meant to be used with vetted commands, API-key authentication, logging, rate limiting, and optional network isolation (reverse proxy, containerization). Operators should only expose this API to trusted networks, use TLS, restrict allowed commands, and run the service with least privilege.
11+
12+
Safe Use Cases
13+
14+
- Triggering a vetted deployment script on an internal network (pull, build, and restart) during controlled release windows.
15+
- Running non-destructive maintenance tasks such as clearing caches, rotating logs, or syncing files to an internal backup target.
16+
- Kicking off database migration scripts in a scheduled maintenance window after thorough validation.
17+
- Starting/stopping internal services or jobs in an environment protected by access controls and auditing.
18+
- Collecting diagnostics (log bundles, system information) for support or monitoring without exposing sensitive data.
19+
- Launching test runs or build jobs that generate artifacts for internal CI pipelines.
20+
21+
Security notes: always whitelist commands (do not accept arbitrary shell input), keep `API_KEY` secret and rotated, serve behind TLS and a firewall or VPN, run the service as an unprivileged user or inside a container, and log and monitor all requests.
22+
23+
Highlights
24+
- Secure API endpoint with API-key authentication
25+
- Rate limiting and CORS protection
26+
- Optional Nginx reverse proxy
27+
- Dockerized for easy deployment
28+
- Systemd installation script for traditional hosts
29+
- Health check and request logging
30+
31+
Quick Links
32+
- Usage: POST /api/trigger
33+
- Health: GET /health
34+
- Code: index.js, src/server.js
635

7-
- Secure API endpoint with API key authentication
8-
- Rate limiting to prevent abuse
9-
- Nginx reverse proxy configuration
10-
- Environment-based command execution
11-
- Logging system
12-
- Health check endpoint
13-
- Systemd service integration for automatic startup
14-
- Docker support for containerized deployment
15-
- GitHub Actions for automated Docker builds
16-
17-
## Setup
18-
19-
### Option 1: Docker (Recommended)
20-
21-
1. Install Docker and Docker Compose on your Ubuntu system:
22-
```bash
23-
sudo apt-get update
24-
sudo apt-get install docker.io docker-compose
25-
```
26-
27-
2. Configure your environment variables in `.env`
28-
3. Build and start the containers:
29-
```bash
30-
docker-compose up -d
31-
```
32-
33-
The service will be available on port 80 (Nginx) and 3000 (direct access).
34-
35-
### Option 2: Traditional Installation
36-
37-
1. Install dependencies:
38-
```bash
39-
sudo apt update
40-
41-
curl -fsSL https://deb.nodesource.com/setup_19.x | sudo -E bash -
42-
43-
sudo apt install -y nodejs
44-
45-
node -v
46-
47-
npm install
48-
49-
npm -v
50-
51-
npm i
52-
```
53-
54-
2. Configure your environment variables in `.env`:
55-
- Set your secure API_KEY
56-
57-
You can generate safe token by run:
58-
```
59-
date | sha512sum
60-
```
61-
- Configure your CLI_COMMAND
62-
- Set your CLI_WORKING_DIR
63-
64-
3. Configure Nginx:
65-
- Copy the nginx.conf to your Nginx configuration directory
66-
- Restart Nginx
67-
68-
4. Install as a service (Ubuntu):
69-
```bash
70-
sudo chmod +x install-service.sh
71-
sudo ./install-service.sh
72-
```
73-
74-
This will:
75-
- Install Node.js if not present
76-
- Create a dedicated service user
77-
- Set up the project in /opt/cicd-cli-controller
78-
- Create and enable a systemd service
79-
- Start the service automatically
80-
81-
5. Manual start (if not using service):
82-
```bash
83-
npm start
84-
```
85-
86-
## Usage
87-
88-
To trigger the CLI command, send a POST request to `/api/trigger` with your API key:
36+
Requirements
37+
- Docker (recommended) or Node.js >= 16 and npm
38+
- Linux host (Ubuntu is supported by provided scripts)
39+
40+
Quick Start (Docker - recommended)
41+
42+
1. Create a `.env` in the project root with required variables (see Env section).
43+
2. Build and run:
8944

9045
```bash
91-
curl -X POST http://localhost/api/trigger \
92-
-H "X-API-Key: your-api-key-here"
46+
docker-compose up -d --build
9347
```
9448

95-
## Security Features
49+
3. View logs:
9650

97-
- Helmet.js for security headers
98-
- API key authentication
99-
- Rate limiting
100-
- CORS protection
101-
- Nginx reverse proxy
102-
- Request logging
103-
- Dedicated service user
104-
- Systemd service isolation
105-
- Docker container isolation
51+
```bash
52+
docker-compose logs -f
53+
```
10654

107-
## Health Check
55+
Start Without Docker (traditional install)
10856

109-
Access the health check endpoint:
57+
1. Install Node.js and dependencies:
11058

11159
```bash
112-
curl http://localhost/health
60+
sudo apt update
61+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
62+
sudo apt install -y nodejs
63+
npm install
11364
```
11465

115-
## Service Management
66+
2. Configure `.env` and start:
11667

117-
### Docker
11868
```bash
119-
# Start services
120-
docker-compose up -d
69+
npm start
70+
```
12171

122-
# Stop services
123-
docker-compose down
72+
3. To install as a systemd service (Ubuntu):
12473

125-
# View logs
126-
docker-compose logs -f
74+
```bash
75+
sudo chmod +x install-service.sh
76+
sudo ./install-service.sh
77+
```
12778

128-
# Rebuild and restart
129-
docker-compose up -d --build
79+
Environment (important)
80+
Create a `.env` file with at least the following values:
81+
82+
```
83+
API_KEY=your-secure-api-key
84+
CLI_COMMAND=./your-script.sh
85+
CLI_WORKING_DIR=/path/to/working/dir
86+
PORT=3000
87+
```
88+
89+
Generating a secure key locally:
90+
91+
```bash
92+
date | sha512sum | cut -c1-64
13093
```
13194

132-
### Traditional Installation
133-
Once installed as a service, you can manage it using systemctl:
95+
API
96+
- POST /api/trigger — triggers the configured CLI command.
97+
- Header: `X-API-Key: <API_KEY>`
98+
- Response: JSON with status and optional command output or error.
99+
100+
- GET /health — returns 200 OK when the service is healthy.
101+
102+
Example trigger
134103

135104
```bash
136-
sudo systemctl start cicd-cli-controller # Start the service
137-
sudo systemctl stop cicd-cli-controller # Stop the service
138-
sudo systemctl restart cicd-cli-controller # Restart the service
139-
sudo systemctl status cicd-cli-controller # Check service status
105+
curl -X POST http://localhost/api/trigger -H "X-API-Key: your-api-key"
140106
```
141107

142-
## GitHub Actions
108+
Logging
109+
- Logs are written to the `logs/` directory by default (see project files).
110+
111+
Deployment Notes
112+
- The included `nginx.conf` is a ready-to-use reverse proxy config — adapt upstream/SSL as needed.
113+
- `docker-compose.yml` starts the app and nginx for production-like testing.
114+
- The `install-service.sh` script sets up a systemd service and places the app under `/opt/cicd-cli-controller` by default.
115+
116+
Security Best Practices
117+
- Keep `API_KEY` secret and rotate it periodically.
118+
- Serve the API behind TLS (terminate TLS at Nginx or an external proxy).
119+
- Run the service with a dedicated, unprivileged user when using systemd.
120+
- Restrict access to the host and control network rules if exposing the API.
143121

144-
The project includes GitHub Actions workflow that automatically:
145-
- Builds the Docker image
146-
- Pushes to Docker Hub on successful builds
147-
- Tags images based on git tags and commits
148-
- Uses caching to speed up builds
122+
CI/CD
123+
- A GitHub Actions workflow is included to build and push Docker images. Add Docker Hub credentials as repository secrets (`DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`) to enable publishing.
149124

150-
To set up GitHub Actions:
125+
Troubleshooting
126+
- If the service doesn't start, check `docker-compose logs` or `journalctl -u cicd-cli-controller` for systemd installs.
127+
- Ensure `CLI_COMMAND` is executable and `CLI_WORKING_DIR` exists.
151128

152-
1. Add these secrets to your GitHub repository:
153-
- `DOCKERHUB_USERNAME`: Your Docker Hub username
154-
- `DOCKERHUB_TOKEN`: Your Docker Hub access token (not password)
129+
Contributing
130+
- Open issues or pull requests. Keep changes small and include tests where appropriate.
155131

156-
2. Push to the main branch or create a tag to trigger the workflow
132+
License
133+
- MIT (or choose your preferred license)

0 commit comments

Comments
 (0)