suthep 0.1.0-beta.1

package/docs/en/developer-guide.md

@@ -0,0 +1,588 @@
+# Developer Guide
+
+This guide is for developers who want to contribute to Suthep, understand its codebase, or extend its functionality.
+
+## Table of Contents
+
+1. [Development Setup](#development-setup)
+2. [Project Structure](#project-structure)
+3. [Architecture Overview](#architecture-overview)
+4. [Code Organization](#code-organization)
+5. [Development Workflow](#development-workflow)
+6. [Building and Testing](#building-and-testing)
+7. [Adding New Features](#adding-new-features)
+8. [Code Style and Guidelines](#code-style-and-guidelines)
+9. [Debugging](#debugging)
+10. [Contributing](#contributing)
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js 16+** - [Download Node.js](https://nodejs.org/)
+- **npm** or **yarn** - Package manager
+- **TypeScript** - Already included as a dev dependency
+- **Git** - Version control
+
+### Initial Setup
+
+1. **Clone the repository**:
+   ```bash
+   git clone <repository-url>
+   cd suthep
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Link the CLI tool for local development**:
+   ```bash
+   npm link
+   ```
+   This makes the `suthep` command available globally, pointing to your local development version.
+
+4. **Verify setup**:
+   ```bash
+   suthep --version
+   suthep --help
+   ```
+
+### Development Dependencies
+
+The project uses:
+- **TypeScript** - Type-safe JavaScript
+- **Vite** - Build tool and bundler
+- **Chalk** - Terminal string styling
+- **Commander** - CLI framework
+- **Execa** - Process execution
+- **Inquirer** - Interactive CLI prompts
+- **js-yaml** - YAML parsing
+
+## Project Structure
+
+```
+suthep/
+├── src/                    # Source code
+│   ├── commands/          # CLI commands
+│   │   ├── deploy.ts     # Deploy command
+│   │   ├── init.ts       # Init command
+│   │   └── setup.ts     # Setup command
+│   ├── types/            # TypeScript type definitions
+│   │   └── config.ts     # Configuration types
+│   ├── utils/            # Utility modules
+│   │   ├── certbot.ts   # Certbot/SSL utilities
+│   │   ├── config-loader.ts  # Configuration loading
+│   │   ├── deployment.ts     # Deployment strategies
+│   │   ├── docker.ts        # Docker management
+│   │   └── nginx.ts         # Nginx configuration
+│   └── index.ts          # Entry point
+├── dist/                 # Compiled output (generated)
+├── docs/                 # Documentation
+├── example/              # Example configurations
+├── package.json          # Project metadata and dependencies
+├── tsconfig.json         # TypeScript configuration
+├── vite.config.ts        # Vite build configuration
+└── README.md            # Project readme
+```
+
+## Architecture Overview
+
+Suthep follows a modular architecture with clear separation of concerns:
+
+### Core Components
+
+1. **CLI Layer** (`src/commands/`)
+   - Handles user interaction
+   - Parses command-line arguments
+   - Orchestrates deployment flow
+
+2. **Configuration Layer** (`src/utils/config-loader.ts`)
+   - Loads and validates YAML configuration
+   - Provides type-safe configuration objects
+
+3. **Service Managers** (`src/utils/`)
+   - **Docker Manager**: Container lifecycle management
+   - **Nginx Manager**: Reverse proxy configuration
+   - **Certbot Manager**: SSL certificate management
+   - **Deployment Manager**: Deployment strategies
+
+4. **Type System** (`src/types/`)
+   - TypeScript interfaces for all configuration types
+   - Ensures type safety across the codebase
+
+### Data Flow
+
+```
+User Command
+    ↓
+CLI Command Handler
+    ↓
+Configuration Loader
+    ↓
+Service Managers (Docker, Nginx, Certbot)
+    ↓
+External Tools (Docker, Nginx, Certbot)
+```
+
+## Code Organization
+
+### Commands (`src/commands/`)
+
+Each command is a self-contained module:
+
+- **`deploy.ts`**: Main deployment orchestration
+  - Groups services by domain
+  - Manages Docker containers
+  - Generates Nginx configs
+  - Handles SSL certificates
+  - Performs health checks
+
+- **`init.ts`**: Interactive configuration creation
+  - Prompts for project details
+  - Guides service configuration
+  - Generates `suthep.yml`
+
+- **`setup.ts`**: Prerequisites installation
+  - Installs Nginx
+  - Installs Certbot
+  - Configures system services
+
+### Utilities (`src/utils/`)
+
+**`docker.ts`** - Docker Container Management
+- `startDockerContainer()`: Start or recreate containers
+- `stopDockerContainer()`: Stop containers
+- `isContainerRunning()`: Check container status
+- `getContainerLogs()`: Retrieve logs
+- `needsRecreate()`: Check if container needs recreation
+- `getContainerPortMapping()`: Get port mappings
+
+**`nginx.ts`** - Nginx Configuration
+- `generateNginxConfig()`: Single service config
+- `generateMultiServiceNginxConfig()`: Multiple services on same domain
+- `writeNginxConfig()`: Write config files
+- `enableSite()`: Enable Nginx site
+- `reloadNginx()`: Reload Nginx configuration
+
+**`certbot.ts`** - SSL Certificate Management
+- `requestCertificate()`: Request new certificate
+- `certificateExists()`: Check if certificate exists
+- `renewCertificates()`: Renew certificates
+- `checkCertificateExpiration()`: Check expiration date
+
+**`deployment.ts`** - Deployment Strategies
+- `deployService()`: Main deployment function
+- `rollingDeploy()`: Rolling deployment strategy
+- `blueGreenDeploy()`: Blue-green deployment strategy
+- `performHealthCheck()`: Health check validation
+
+**`config-loader.ts`** - Configuration Management
+- `loadConfig()`: Load and validate YAML config
+- `saveConfig()`: Save configuration to file
+- `validateConfig()`: Validate configuration structure
+
+### Types (`src/types/config.ts`)
+
+All configuration types are defined as TypeScript interfaces:
+
+```typescript
+interface ServiceConfig {
+  name: string
+  port: number
+  domains: string[]
+  path?: string
+  docker?: DockerConfig
+  healthCheck?: HealthCheckConfig
+  environment?: Record<string, string>
+}
+```
+
+## Development Workflow
+
+### Making Changes
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes**:
+   - Edit source files in `src/`
+   - Follow existing code patterns
+   - Add comments for complex logic
+
+3. **Build and test**:
+   ```bash
+   npm run build
+   npm test
+   ```
+
+4. **Test manually**:
+   ```bash
+   # After building, test the CLI
+   suthep --help
+   suthep init
+   suthep deploy --file example/suthep.yml
+   ```
+
+5. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "feat: description of your changes"
+   ```
+
+### Development Scripts
+
+- **`npm run build`**: Compile TypeScript to JavaScript
+- **`npm run dev`**: Start development mode (if configured)
+- **`npm test`**: Run tests (currently builds and shows help)
+
+### Hot Reloading
+
+Since the CLI is linked globally, you need to rebuild after changes:
+
+```bash
+npm run build
+```
+
+The `suthep` command will use the newly built version.
+
+## Building and Testing
+
+### Build Process
+
+1. **TypeScript Compilation**:
+   ```bash
+   tsc
+   ```
+   Compiles TypeScript files to JavaScript in the `dist/` directory.
+
+2. **Vite Bundling**:
+   ```bash
+   vite build
+   ```
+   Bundles the code for production.
+
+3. **Complete Build**:
+   ```bash
+   npm run build
+   ```
+   Runs both compilation and bundling.
+
+### Testing
+
+Currently, testing is minimal. To test:
+
+1. **Build the project**:
+   ```bash
+   npm run build
+   ```
+
+2. **Test commands manually**:
+   ```bash
+   # Test help
+   suthep --help
+
+   # Test init
+   suthep init --file test-config.yml
+
+   # Test deploy (with a test config)
+   suthep deploy --file example/suthep.yml --nginx=false --https=false
+   ```
+
+### Adding Tests
+
+To add proper testing:
+
+1. Install a testing framework:
+   ```bash
+   npm install --save-dev jest @types/jest
+   ```
+
+2. Create test files:
+   ```
+   src/
+   ├── utils/
+   │   ├── docker.ts
+   │   └── docker.test.ts
+   ```
+
+3. Write tests for utility functions
+
+## Adding New Features
+
+### Adding a New Command
+
+1. **Create command file** (`src/commands/newcommand.ts`):
+   ```typescript
+   import chalk from 'chalk'
+   import type { DeployOptions } from '../types/config'
+
+   interface NewCommandOptions {
+     flag: string
+   }
+
+   export async function newCommand(options: NewCommandOptions): Promise<void> {
+     console.log(chalk.blue.bold('\n🚀 New Command\n'))
+     // Implementation
+   }
+   ```
+
+2. **Register in `src/index.ts`**:
+   ```typescript
+   import { newCommand } from './commands/newcommand'
+
+   program
+     .command('newcommand')
+     .description('Description of new command')
+     .option('-f, --flag <value>', 'Flag description')
+     .action(async (options) => {
+       await newCommand(options)
+     })
+   ```
+
+3. **Update documentation** in `docs/commands.md`
+
+### Adding a New Utility Function
+
+1. **Add to appropriate utility file** or create new one
+2. **Export the function**
+3. **Add TypeScript types**
+4. **Update API documentation** in `docs/api-reference.md`
+
+### Extending Configuration
+
+1. **Update types** (`src/types/config.ts`):
+   ```typescript
+   export interface ServiceConfig {
+     // ... existing fields
+     newField?: string
+   }
+   ```
+
+2. **Update config loader** (`src/utils/config-loader.ts`) to handle new field
+3. **Update validation** if needed
+4. **Update documentation** in `docs/configuration.md`
+
+## Code Style and Guidelines
+
+### TypeScript Guidelines
+
+- **Use TypeScript types**: Always define types for function parameters and return values
+- **Prefer interfaces over types**: For object shapes, use interfaces
+- **Use strict mode**: TypeScript strict mode is enabled
+- **Avoid `any`**: Use proper types or `unknown` if type is truly unknown
+
+### Naming Conventions
+
+- **Files**: Use kebab-case (`config-loader.ts`)
+- **Functions**: Use camelCase (`startDockerContainer`)
+- **Interfaces**: Use PascalCase (`ServiceConfig`)
+- **Constants**: Use UPPER_SNAKE_CASE (`MAX_RETRIES`)
+
+### Code Organization
+
+- **One function per responsibility**: Keep functions focused
+- **Extract utilities**: Reusable logic should be in utility functions
+- **Error handling**: Always handle errors appropriately
+- **Logging**: Use `chalk` for colored output, provide clear messages
+
+### Example Code Style
+
+```typescript
+/**
+ * Start or connect to a Docker container for a service
+ * @param service - Service configuration
+ * @throws Error if container cannot be started
+ */
+export async function startDockerContainer(
+  service: ServiceConfig
+): Promise<void> {
+  if (!service.docker) {
+    return
+  }
+
+  const { image, container, port } = service.docker
+
+  try {
+    // Implementation
+  } catch (error) {
+    throw new Error(
+      `Failed to start Docker container: ${
+        error instanceof Error ? error.message : error
+      }`
+    )
+  }
+}
+```
+
+## Debugging
+
+### Enable Debug Logging
+
+Add debug logging to functions:
+
+```typescript
+import chalk from 'chalk'
+
+console.log(chalk.dim(`Debug: ${variable}`))
+```
+
+### Common Debugging Scenarios
+
+1. **Docker Issues**:
+   ```bash
+   # Check container status
+   docker ps -a
+   docker logs <container-name>
+   ```
+
+2. **Nginx Issues**:
+   ```bash
+   # Test configuration
+   sudo nginx -t
+
+   # Check error logs
+   sudo tail -f /var/log/nginx/error.log
+   ```
+
+3. **Certbot Issues**:
+   ```bash
+   # Check certificates
+   sudo certbot certificates
+
+   # Check logs
+   sudo tail -f /var/log/letsencrypt/letsencrypt.log
+   ```
+
+### Using Node.js Debugger
+
+1. **Add debugger statement**:
+   ```typescript
+   debugger
+   ```
+
+2. **Run with inspect**:
+   ```bash
+   node --inspect dist/index.js deploy
+   ```
+
+3. **Connect with Chrome DevTools**: `chrome://inspect`
+
+## Contributing
+
+### Before Contributing
+
+1. **Check existing issues**: See if your feature/bug is already reported
+2. **Discuss major changes**: Open an issue first for significant changes
+3. **Follow the code style**: Match existing code patterns
+
+### Pull Request Process
+
+1. **Fork the repository**
+2. **Create a feature branch**
+3. **Make your changes**
+4. **Test thoroughly**
+5. **Update documentation**
+6. **Submit pull request**
+
+### Commit Message Format
+
+Use conventional commits:
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation changes
+- `style:` - Code style changes
+- `refactor:` - Code refactoring
+- `test:` - Test additions/changes
+- `chore:` - Build process or auxiliary tool changes
+
+Examples:
+```
+feat: add support for custom nginx templates
+fix: handle missing docker image gracefully
+docs: update developer guide
+```
+
+### Code Review Checklist
+
+- [ ] Code follows existing patterns
+- [ ] TypeScript types are properly defined
+- [ ] Error handling is appropriate
+- [ ] Logging is clear and helpful
+- [ ] Documentation is updated
+- [ ] Tests pass (if applicable)
+- [ ] No console.log statements (use chalk for user-facing output)
+
+## Key Implementation Details
+
+### Docker Container Management
+
+Containers are managed with the following logic:
+
+1. **Check existence**: Use `docker inspect` to check if container exists
+2. **Recreate if needed**: Always recreate on redeploy for fresh state
+3. **Port mapping**: Format is `hostPort:containerPort`
+4. **Environment variables**: Injected via `-e` flags
+
+### Nginx Configuration
+
+- **One config per domain**: Services on the same domain share one config file
+- **Upstream naming**: Format is `domain_service` (e.g., `muacle_com_api`)
+- **Path-based routing**: Services are routed by their `path` configuration
+- **HTTPS support**: Automatically configured when `--https` flag is used
+
+### SSL Certificate Management
+
+- **Check before request**: Always check if certificate exists first
+- **Skip if exists**: Don't request if certificate already exists
+- **Domain-based**: One certificate per domain
+- **Automatic renewal**: Certbot handles renewal automatically
+
+### Deployment Strategies
+
+- **Rolling**: Gradually replace old instances (currently simplified)
+- **Blue-Green**: Maintain two environments (currently simplified)
+
+## Troubleshooting Development Issues
+
+### Build Errors
+
+- **TypeScript errors**: Check `tsconfig.json` settings
+- **Module not found**: Ensure all dependencies are installed
+- **Import errors**: Check import paths match file structure
+
+### Runtime Errors
+
+- **Permission denied**: Ensure sudo access for Nginx/Certbot operations
+- **Command not found**: Rebuild and relink: `npm run build && npm link`
+- **Configuration errors**: Validate YAML syntax
+
+### Common Issues
+
+1. **Changes not reflected**: Rebuild the project (`npm run build`)
+2. **Linked version outdated**: Run `npm link` again
+3. **Type errors**: Check TypeScript compiler output
+
+## Resources
+
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
+- [Node.js Documentation](https://nodejs.org/docs/)
+- [Docker Documentation](https://docs.docker.com/)
+- [Nginx Documentation](https://nginx.org/en/docs/)
+- [Certbot Documentation](https://eff-certbot.readthedocs.io/)
+
+## Getting Help
+
+- Check existing [documentation](./README.md)
+- Review [troubleshooting guide](./troubleshooting.md)
+- Open an issue on GitHub
+- Check [API reference](./api-reference.md) for function details
+
+---
+
+Happy coding! 🚀
+