suthep 0.1.0

package/docs/examples.md

@@ -0,0 +1,537 @@
+# Examples
+
+This document provides real-world examples of using Suthep for various deployment scenarios.
+
+## Example 1: Simple Node.js API
+
+Deploy a basic Node.js Express API with health checks.
+
+### Service Code
+
+```javascript
+// server.js
+const express = require('express');
+const app = express();
+
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: Date.now() });
+});
+
+app.get('/', (req, res) => {
+  res.json({ message: 'Hello from API!' });
+});
+
+app.listen(3000, () => {
+  console.log('API server running on port 3000');
+});
+```
+
+### Configuration
+
+```yaml
+project:
+  name: simple-api
+  version: 1.0.0
+
+services:
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+### Deployment
+
+```bash
+# Start your Node.js server
+node server.js
+
+# Deploy
+suthep deploy
+```
+
+## Example 2: Docker Container Service
+
+Deploy a web application running in a Docker container.
+
+### Configuration
+
+```yaml
+project:
+  name: webapp
+  version: 1.0.0
+
+services:
+  - name: webapp
+    port: 8080
+    docker:
+      image: nginx:alpine
+      container: webapp-container
+      port: 80
+    domains:
+      - example.com
+      - www.example.com
+    healthCheck:
+      path: /
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+### Deployment
+
+```bash
+# Suthep will automatically pull and run the Docker image
+suthep deploy
+```
+
+## Example 3: Multiple Services (Microservices)
+
+Deploy a microservices architecture with multiple services.
+
+### Configuration
+
+```yaml
+project:
+  name: microservices-app
+  version: 1.0.0
+
+services:
+  # API Gateway
+  - name: gateway
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+
+  # User Service
+  - name: user-service
+    port: 3001
+    domains:
+      - users.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://localhost:5432/users
+
+  # Product Service
+  - name: product-service
+    port: 3002
+    domains:
+      - products.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://localhost:5432/products
+
+  # Frontend (Docker)
+  - name: frontend
+    port: 8080
+    docker:
+      image: myapp/frontend:latest
+      container: frontend-container
+      port: 80
+    domains:
+      - example.com
+      - www.example.com
+    healthCheck:
+      path: /
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+## Example 4: Connect to Existing Docker Container
+
+Connect Suthep to an already running Docker container.
+
+### Configuration
+
+```yaml
+project:
+  name: existing-container
+  version: 1.0.0
+
+services:
+  - name: database-proxy
+    port: 5432
+    docker:
+      # No image specified - connects to existing container
+      container: postgres-container
+      port: 5432
+    domains:
+      - db.example.com
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+### Prerequisites
+
+```bash
+# Start your container first
+docker run -d --name postgres-container \
+  -p 5432:5432 \
+  -e POSTGRES_PASSWORD=secret \
+  postgres:latest
+```
+
+### Deployment
+
+```bash
+suthep deploy
+```
+
+## Example 5: Development Environment with Staging Certificates
+
+Use staging certificates for development/testing.
+
+### Configuration
+
+```yaml
+project:
+  name: dev-app
+  version: 0.1.0
+
+services:
+  - name: api
+    port: 3000
+    domains:
+      - api-dev.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: dev@example.com
+  staging: true  # Use staging environment
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+## Example 6: HTTP Only (No HTTPS)
+
+Deploy without SSL certificates (development only).
+
+### Configuration
+
+```yaml
+project:
+  name: http-only
+  version: 1.0.0
+
+services:
+  - name: api
+    port: 3000
+    domains:
+      - api.local
+    healthCheck:
+      path: /health
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+### Deployment
+
+```bash
+# Skip HTTPS setup
+suthep deploy --no-https
+```
+
+## Example 7: Docker with Environment Variables
+
+Deploy a Docker container with custom environment variables.
+
+### Configuration
+
+```yaml
+project:
+  name: env-app
+  version: 1.0.0
+
+services:
+  - name: app
+    port: 8080
+    docker:
+      image: myapp/api:latest
+      container: app-container
+      port: 3000
+    domains:
+      - app.example.com
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://db:5432/mydb
+      REDIS_URL: redis://redis:6379
+      API_KEY: your-secret-key
+      LOG_LEVEL: info
+    healthCheck:
+      path: /health
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+## Example 8: Blue-Green Deployment
+
+Use blue-green deployment strategy for zero-downtime.
+
+### Configuration
+
+```yaml
+project:
+  name: blue-green-app
+  version: 1.0.0
+
+services:
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: blue-green  # Use blue-green strategy
+  healthCheckTimeout: 60000  # Longer timeout for blue-green
+
+```
+
+## Example 9: Custom Health Check Interval
+
+Configure custom health check intervals for different services.
+
+### Configuration
+
+```yaml
+project:
+  name: custom-health
+  version: 1.0.0
+
+services:
+  # Fast health checks for critical service
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /health
+      interval: 10  # Check every 10 seconds
+
+  # Slower health checks for less critical service
+  - name: worker
+    port: 3001
+    domains:
+      - worker.example.com
+    healthCheck:
+      path: /health
+      interval: 60  # Check every 60 seconds
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+## Example 10: Multiple Domains per Service
+
+Route multiple domains to a single service.
+
+### Configuration
+
+```yaml
+project:
+  name: multi-domain
+  version: 1.0.0
+
+services:
+  - name: app
+    port: 3000
+    domains:
+      - example.com
+      - www.example.com
+      - app.example.com
+      - myapp.com
+      - www.myapp.com
+    healthCheck:
+      path: /health
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+## Example 11: Full Stack Application
+
+Deploy a complete full-stack application with frontend, backend, and database proxy.
+
+### Configuration
+
+```yaml
+project:
+  name: fullstack-app
+  version: 1.0.0
+
+services:
+  # React Frontend (Docker)
+  - name: frontend
+    port: 8080
+    docker:
+      image: myapp/frontend:latest
+      container: frontend-container
+      port: 80
+    domains:
+      - example.com
+      - www.example.com
+    healthCheck:
+      path: /
+      interval: 30
+
+  # Node.js Backend API
+  - name: backend
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /api/health
+      interval: 30
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://localhost:5432/mydb
+
+  # Database Proxy (existing container)
+  - name: database
+    port: 5432
+    docker:
+      container: postgres-container
+      port: 5432
+    domains:
+      - db.example.com
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+## Tips for Real-World Deployments
+
+1. **Start with staging certificates**: Use `certbot.staging: true` during development
+2. **Test health checks**: Ensure your health endpoints return 200 OK
+3. **Monitor logs**: Check Nginx and application logs after deployment
+4. **DNS configuration**: Ensure all domains point to your server's IP
+5. **Firewall rules**: Open ports 80 and 443 for HTTP/HTTPS
+6. **Backup configurations**: Keep backups of your `suthep.yml` file
+7. **Version control**: Commit your configuration files to version control

package/docs/getting-started.md

@@ -0,0 +1,197 @@
+# Getting Started with Suthep
+
+This guide will walk you through installing Suthep and deploying your first service.
+
+## Installation
+
+### Prerequisites
+
+Before installing Suthep, ensure you have:
+
+- **Node.js 16+** - [Download Node.js](https://nodejs.org/)
+- **sudo access** - Required for Nginx and Certbot operations
+- **Docker** (optional) - Only needed if deploying Docker containers
+
+### Install Suthep
+
+1. Clone or download the Suthep repository:
+   ```bash
+   git clone <repository-url>
+   cd suthep
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Link the CLI tool globally:
+   ```bash
+   npm link
+   ```
+
+   This makes the `suthep` command available globally on your system.
+
+4. Verify installation:
+   ```bash
+   suthep --version
+   ```
+
+## Quick Start Guide
+
+### Step 1: Initialize Configuration
+
+Create a configuration file for your project:
+
+```bash
+suthep init
+```
+
+This interactive command will:
+- Ask for your project name and version
+- Guide you through configuring services
+- Set up domain names
+- Configure Docker (if needed)
+- Set up health checks
+- Configure Certbot email
+
+Alternatively, you can copy the example configuration:
+
+```bash
+cp suthep.example.yml suthep.yml
+# Edit suthep.yml with your settings
+```
+
+### Step 2: Setup Prerequisites
+
+Install and configure Nginx and Certbot:
+
+```bash
+suthep setup
+```
+
+This command will:
+- Install Nginx (if not already installed)
+- Install Certbot (if not already installed)
+- Start and enable the Nginx service
+
+You can also install them separately:
+
+```bash
+suthep setup --nginx-only    # Only install Nginx
+suthep setup --certbot-only  # Only install Certbot
+```
+
+### Step 3: Deploy Your Services
+
+Deploy your project:
+
+```bash
+suthep deploy
+```
+
+This will:
+1. Load your configuration from `suthep.yml`
+2. Start Docker containers (if configured)
+3. Deploy each service
+4. Generate and enable Nginx configurations
+5. Request SSL certificates from Let's Encrypt
+6. Reload Nginx
+7. Perform health checks
+
+## Your First Deployment
+
+Let's deploy a simple Node.js API service:
+
+### 1. Create a Simple Service
+
+Create a basic Node.js server:
+
+```javascript
+// server.js
+const http = require('http');
+
+const server = http.createServer((req, res) => {
+  if (req.url === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ status: 'ok' }));
+  } else {
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('Hello from Suthep!');
+  }
+});
+
+server.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### 2. Create Configuration
+
+Create `suthep.yml`:
+
+```yaml
+project:
+  name: my-first-app
+  version: 1.0.0
+
+services:
+  - name: api
+    port: 3000
+    domains:
+      - api.yourdomain.com
+    healthCheck:
+      path: /health
+      interval: 30
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: your-email@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+### 3. Start Your Service
+
+Run your Node.js server:
+
+```bash
+node server.js
+```
+
+### 4. Setup and Deploy
+
+```bash
+# Setup Nginx and Certbot
+suthep setup
+
+# Deploy
+suthep deploy
+```
+
+### 5. Verify
+
+Visit `https://api.yourdomain.com` in your browser. You should see "Hello from Suthep!" and the SSL certificate should be valid.
+
+## Next Steps
+
+- Read the [Configuration Reference](./configuration.md) to learn about all configuration options
+- Check out [Examples](./examples.md) for more complex deployment scenarios
+- Review [Commands Reference](./commands.md) for detailed command documentation
+
+## Common Issues
+
+If you encounter issues during setup:
+
+1. **Permission denied**: Ensure you have sudo access
+2. **Nginx not found**: Run `suthep setup` to install it
+3. **Domain not resolving**: Make sure your domain DNS points to your server's IP
+4. **SSL certificate failed**: Check that your domain is publicly accessible and port 80 is open
+
+For more troubleshooting help, see the [Troubleshooting Guide](./troubleshooting.md).