suthep 0.1.0-beta.1 → 0.2.0-beta.1

package/docs/en/developer-guide.md

@@ -1,588 +0,0 @@
-# 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! 🚀
-