@it-club/provisor 0.1.0

package/README.md

@@ -0,0 +1,317 @@
+# @it-club/provisor
+
+Interactive CLI tool for server provisioning and deployment with automatic deploy support.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @it-club/provisor
+
+# Or run directly with npx
+npx @it-club/provisor
+```
+
+## Commands
+
+### `provisor init` - Initialize Server
+
+Sets up a new server with user management, SSH hardening, and firewall configuration.
+
+```bash
+provisor init -h <server-ip>
+
+# Options
+-h, --host <host>   Server hostname or IP (required)
+-u, --user <user>   Username to create (default: "deploy")
+-k, --key <path>    Path to SSH private key
+-p, --port <port>   SSH port (default: "22")
+```
+
+**What it does:**
+1. Connects as root
+2. Updates system packages
+3. Creates a new user with sudo access
+4. Copies root's SSH keys to new user
+5. Configures UFW firewall (SSH, HTTP, HTTPS)
+6. Hardens SSH (disables root login, password auth)
+
+---
+
+### `provisor app` - Provision Application
+
+Sets up Caddy, Node.js, and git-based deployment with optional auto-deploy.
+
+```bash
+provisor app -h <server-ip> -n myapp
+
+# Options
+-h, --host <host>      Server hostname or IP (required)
+-u, --user <user>      Username to connect as (default: "deploy")
+-k, --key <path>       Path to SSH private key
+-p, --port <port>      SSH port (default: "22")
+-b, --branch <branch>  Deploy branch (default: "main")
+-n, --name <name>      Application name (default: "app")
+-r, --repo <url>       Clone from repository URL (GitHub, GitLab, etc.)
+```
+
+**What it does:**
+1. Installs Caddy web server
+2. Installs Node.js LTS and PM2
+3. Sets up deployment (choose from 3 methods):
+   - **Push-to-deploy**: Creates bare git repo for `git push` deployments
+   - **Clone from public repo**: Clones HTTPS repository
+   - **Clone from private repo**: Generates deploy key, clones SSH repository
+4. Sets up auto-deploy (choose from 3 options):
+   - **Git polling**: Checks for new commits every N seconds (simpler, works everywhere)
+   - **Webhook**: Instant deployment on push (requires repo webhook setup)
+   - **Manual only**: Use `provisor deploy` command
+5. Configures Caddy with your choice of TLS (on-demand, specific domain, or none)
+
+**Deployment Methods:**
+
+| Method | Best For | Auto-Deploy |
+|--------|----------|-------------|
+| Push-to-deploy | Private repos, full control | Built-in (git hook) |
+| Clone public | Open source projects | Polling or webhook |
+| Clone private | Private GitHub/GitLab repos | Polling or webhook |
+
+---
+
+### `provisor deploy` - Trigger Deployment
+
+Manually trigger a deployment for an application.
+
+```bash
+provisor deploy -h <server-ip> -n myapp
+
+# Options
+-h, --host <host>   Server hostname or IP (required)
+-n, --name <name>   Application name (required)
+-u, --user <user>   Username to connect as (default: "deploy")
+-k, --key <path>    Path to SSH private key
+-p, --port <port>   SSH port (default: "22")
+```
+
+---
+
+### `provisor config` - Manage Configuration
+
+View and manage application configuration, deploy keys, and auto-deploy settings.
+
+```bash
+# Show current configuration
+provisor config -h <server-ip> -n myapp --show
+
+# Options
+-h, --host <host>              Server hostname or IP (required)
+-n, --name <name>              Application name (required)
+-u, --user <user>              Username to connect as (default: "deploy")
+-k, --key <path>               Path to SSH private key
+-p, --port <port>              SSH port (default: "22")
+--show                         Show current configuration
+--repo <url>                   Change repository URL
+--branch <branch>              Change deploy branch
+--new-key                      Generate new deploy key
+--delete-key                   Delete deploy key
+--webhook-secret <secret>      Update webhook secret
+--disable-webhook              Disable webhook
+--polling-interval <seconds>   Set git polling interval
+--enable-polling               Enable git polling
+--disable-polling              Disable git polling
+```
+
+**Examples:**
+
+```bash
+# View configuration and deploy key
+provisor config -h 203.0.113.10 -n myapp --show
+
+# Change polling interval to 30 seconds
+provisor config -h 203.0.113.10 -n myapp --polling-interval 30
+
+# Switch branches
+provisor config -h 203.0.113.10 -n myapp --branch develop
+
+# Disable auto-deploy
+provisor config -h 203.0.113.10 -n myapp --disable-polling
+```
+
+---
+
+### `provisor ssh-key` - Manage SSH Keys
+
+Add or list SSH keys on the server.
+
+```bash
+# List keys
+provisor ssh-key -h <server-ip> --list
+
+# Add a key
+provisor ssh-key -h <server-ip> --add "ssh-ed25519 AAAA... user@machine"
+```
+
+---
+
+### `provisor status` - Check Server Status
+
+Display server health and service status.
+
+```bash
+provisor status -h <server-ip>
+```
+
+---
+
+## Auto-Deploy Options
+
+### Git Polling (Recommended for simplicity)
+
+Checks your repository for new commits at a configurable interval.
+
+**Pros:**
+- Works behind NAT/firewalls
+- No webhook configuration needed
+- Works in Docker containers
+- Simple and reliable
+
+**Cons:**
+- Slight delay (interval-based)
+- Uses minimal bandwidth for git fetch
+
+```bash
+# View polling status
+provisor config -h server -n app --show
+# Output: Git Polling: Running (every 10s, daemon mode)
+
+# Change interval
+provisor config -h server -n app --polling-interval 60
+
+# View polling logs
+ssh deploy@server "tail -f /var/log/poll-app.log"           # Daemon mode
+ssh deploy@server "journalctl -u poll-app -f"               # Systemd mode
+```
+
+### Webhook (Recommended for instant deploys)
+
+Repository triggers deployment instantly on push.
+
+**Pros:**
+- Instant deployments
+- No polling overhead
+
+**Cons:**
+- Requires firewall port open
+- Requires webhook setup on GitHub/GitLab
+- Doesn't work behind NAT without port forwarding
+
+After setup, configure webhook in your repository:
+- **URL**: `http://your-server:PORT/webhook`
+- **Secret**: Shown after provisioning
+- **Events**: Push events only
+
+---
+
+## Typical Workflows
+
+### Quick Start: Push-to-Deploy
+
+```bash
+# 1. Initialize server
+provisor init -h 203.0.113.10
+
+# 2. Provision app
+provisor app -h 203.0.113.10 -n myapp
+# Select: Push-to-deploy
+# Select: On-demand TLS
+
+# 3. Add remote to local project
+git remote add production ssh://deploy@203.0.113.10/var/repo/myapp.git
+
+# 4. Deploy
+git push production main
+```
+
+### Clone from GitHub with Auto-Deploy
+
+```bash
+# 1. Initialize server  
+provisor init -h 203.0.113.10
+
+# 2. Provision app with repo
+provisor app -h 203.0.113.10 -n myapp -r https://github.com/user/repo.git
+# Select: Git polling (recommended)
+# Select: On-demand TLS
+
+# Done! Polling will auto-deploy on new commits
+```
+
+### Private Repository with Deploy Key
+
+```bash
+# 1. Initialize server
+provisor init -h 203.0.113.10
+
+# 2. Provision app
+provisor app -h 203.0.113.10 -n myapp
+# Select: Clone from private repository
+# Enter: git@github.com:user/private-repo.git
+
+# 3. Copy the displayed deploy key to GitHub:
+#    Repo → Settings → Deploy keys → Add deploy key
+
+# 4. Confirm key added, deployment continues
+# Select: Git polling
+# Select: On-demand TLS
+```
+
+---
+
+## Environment Detection
+
+The CLI automatically adapts to different environments:
+
+| Environment | Auto-Deploy Method |
+|-------------|-------------------|
+| Systemd servers (Ubuntu, Debian) | Systemd timer |
+| Docker containers | Background daemon loop |
+| Non-systemd systems | Background daemon loop |
+
+---
+
+## SSH Key Detection
+
+The CLI automatically looks for SSH keys in this order:
+1. `--key` flag if provided
+2. `~/.ssh/id_ed25519`
+3. `~/.ssh/id_rsa`
+4. `~/.ssh/id_ecdsa`
+
+---
+
+## File Locations on Server
+
+| File | Purpose |
+|------|---------|
+| `/var/www/<app>/` | Application directory |
+| `/var/repo/<app>.git/` | Bare git repo (push-to-deploy) |
+| `/usr/local/bin/update-<app>` | Update/deploy script |
+| `/usr/local/bin/poll-<app>.sh` | Single poll script |
+| `/usr/local/bin/poll-<app>-daemon.sh` | Polling daemon (non-systemd) |
+| `/var/log/poll-<app>.log` | Polling logs (daemon mode) |
+| `/var/www/<app>/.provisor.json` | App configuration |
+| `/home/<user>/.ssh/deploy_<app>` | Deploy key (private) |
+
+---
+
+## Requirements
+
+- Node.js 20+
+- SSH key pair for server access
+- Target server running Debian/Ubuntu
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }