From b4d841c0979fc0fdb9b47970f3d9925a0d9355ca Mon Sep 17 00:00:00 2001 From: Yar Kravtsov Date: Sun, 12 Jan 2025 09:47:09 +0200 Subject: [PATCH] docs: Update README with improved structure and content clarity --- README.md | 280 ++++++++++++++++++------------------------------------ 1 file changed, 92 insertions(+), 188 deletions(-) diff --git a/README.md b/README.md index ba5ab7d..a1caa57 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,50 @@ -

 

- - - - - - +# FTL (Faster Than Light) Deployment -# FTL: Faster Than Light Deployment +FTL is a lightweight deployment tool designed to simplify cloud deployments without the complexity of traditional CI/CD pipelines or container orchestration platforms. It provides automated, zero-downtime deployments to various cloud providers through a single YAML configuration file. -FTL is a deployment tool that reduces complexity for projects that don't require extensive orchestration infrastructure. It provides automated deployment to cloud providers like Hetzner, DigitalOcean, Linode, and custom servers without the overhead of CI/CD pipelines or container orchestration platforms. +## Features -## Core Features +- Zero-downtime deployments with automated health checks +- Single YAML configuration with environment variable support +- Built-in Nginx reverse proxy with automatic SSL/TLS certificate management +- Docker-based deployment with layer-optimized transfers +- Real-time log streaming and monitoring +- Secure SSH tunneling for remote dependencies -- Single YAML configuration file with environment variable substitution -- Zero-downtime deployments -- Automatic SSL/TLS certificate management -- Docker-based deployment with built-in health checks -- Integrated Nginx reverse proxy -- Multi-provider support (Hetzner, DigitalOcean, Linode, custom servers) -- Fetch and stream logs from deployed services -- Establish SSH tunnels to remote dependencies +## Requirements + +- Docker installed locally for building images +- SSH access to target deployment servers +- Git for version control +- Go 1.16+ (only if building from source) ## Installation -1. **Via Homebrew (macOS and Linux)** +Choose one of the following installation methods: - ```bash - brew tap yarlson/ftl - brew install ftl - ``` +### Via Homebrew (macOS and Linux) -2. **Download from GitHub releases** +```bash +brew tap yarlson/ftl +brew install ftl +``` - ```bash - curl -L https://github.com/yarlson/ftl/releases/latest/download/ftl_$(uname -s)_$(uname -m).tar.gz | tar xz - sudo mv ftl /usr/local/bin/ - ``` +### Direct Download -3. **Build from source** +```bash +curl -L https://github.com/yarlson/ftl/releases/latest/download/ftl_$(uname -s)_$(uname -m).tar.gz | tar xz +sudo mv ftl /usr/local/bin/ +``` - ```bash - go install github.com/yarlson/ftl@latest - ``` +### Build from Source -## Usage +```bash +go install github.com/yarlson/ftl@latest +``` -### 1. Create Configuration File +## Configuration -Create an `ftl.yaml` configuration file in your project directory: +Create an `ftl.yaml` file in your project root: ```yaml project: @@ -88,37 +85,24 @@ volumes: - postgres_data ``` -Environment variables in the configuration can be: +### Environment Variables -- **Required**: `${VAR_NAME}` - Must be set in the environment -- **Optional with default**: `${VAR_NAME:-default_value}` - Uses default if not set +- Required variables: Use `${VAR_NAME}` +- Optional variables with defaults: Use `${VAR_NAME:-default_value}` -### 2. Initialize Server +## Usage -Set up your server with the required dependencies: +### Server Setup ```bash ftl setup ``` -This command will: - -- Install Docker and other necessary packages on your server -- Configure firewall rules -- Set up user permissions -- Initialize Docker networks - -### 3. Build Application Images - -Build and deploy Docker images for your services. FTL offers two ways to handle images: +### Building Applications -#### Direct SSH Transfer (Default) +FTL supports two deployment modes: -When no `image` field is specified in your service configuration, FTL will: -- Build the image locally -- Transfer it directly to your server via SSH -- Use its own layer caching algorithm to optimize transfers -- Only transfer layers that haven't been previously sent to the server +1. Direct SSH Transfer (Default): ```yaml services: @@ -128,13 +112,7 @@ services: dockerfile: Dockerfile ``` -#### Registry-based Deployment - -When you specify the `image` field, FTL will use a Docker registry: -- Build and tag the image locally -- Push it to the specified registry -- Pull the image on the server during deployment -- Require registry authentication during server setup (username/password only) +2. Registry-based Deployment: ```yaml services: @@ -145,143 +123,37 @@ services: dockerfile: Dockerfile ``` -::: warning -Currently, FTL only supports registries with username/password authentication. Token-based authentication will fail. -::: - -#### Build Command +Build command: ```bash -ftl build [flags] +ftl build [--skip-push] ``` -#### Flags - -- `--skip-push`: Skip pushing images to the registry (only applies when using registry-based deployment) - -#### Examples - -- Build all services (using direct SSH transfer): - ```bash - ftl build - ``` -- Build all services but skip pushing to registry (when using registry-based deployment): - ```bash - ftl build --skip-push - ``` - -### 4. Deploy Application - -Deploy your application to the configured servers: +### Deployment ```bash ftl deploy ``` -This command will: - -- Connect to your servers via SSH -- Pull Docker images specified in your configuration -- Start new containers with health checks -- Configure the Nginx reverse proxy -- Manage SSL/TLS certificates via ACME -- Perform zero-downtime container replacement -- Clean up unused resources - -### 5. Fetch Logs - -Retrieve logs from your deployed services: +### Log Management ```bash -ftl logs [service] [flags] -``` - -#### Flags +# Stream all logs +ftl logs -f -- `-f`, `--follow`: Stream logs in real-time. -- `-n`, `--tail `: Number of lines to show from the end of the logs (default is 100 if `-f` is used). - -#### Examples - -- Fetch logs from all services: - ```bash - ftl logs - ``` -- Stream logs from a specific service: - ```bash - ftl logs my-app -f - ``` -- Fetch the last 50 lines of logs from all services: - ```bash - ftl logs -n 50 - ``` -- Fetch logs from a specific service with a custom tail size: - ```bash - ftl logs my-app -n 150 - ``` - -### 6. Create SSH Tunnels - -Establish SSH tunnels for your dependencies, allowing local access to services running on your server: - -```bash -ftl tunnels [flags] +# View specific service logs +ftl logs my-app -n 150 ``` -#### Flags - -- `-s`, `--server `: (Optional) Specify the server name or index to connect to, if multiple servers are defined. - -#### Examples +### SSH Tunnels -- Establish tunnels to all dependency ports: - ```bash - ftl tunnels - ``` -- Specify a server to connect to (if multiple servers are configured): - ```bash - ftl tunnels --server my-project.example.com - ``` - -#### Purpose - -The `ftl tunnels` command is useful for: - -- Accessing dependency services (e.g., databases) running on your server from your local machine -- Simplifying local development by connecting to remote services without modifying your code -- Testing and debugging your application against live dependencies - -## Additional Notes - -### Error Handling - -All commands include detailed error reporting and user feedback through spinners and console messages. Examples: - -- Commands gracefully handle configuration file parsing issues. -- Detailed error messages are provided for server connection or dependency issues. - -### Concurrency - -Commands like `build` and `tunnels` leverage concurrent operations to improve performance. For example: - -- `ftl build` builds and optionally pushes images for all services concurrently. -- `ftl tunnels` establishes SSH tunnels for multiple dependencies simultaneously. - -### Configuration Highlights - -To ensure optimal usage: - -- Ensure all dependencies have `ports` specified in `ftl.yaml` for `ftl tunnels` to function. -- Use health checks in service definitions to ensure reliability during deployment and build processes. - -## Example Projects - -The [ftl-examples](https://github.com/yarlson/ftl-examples) repository contains reference implementations: - -- [Flask](https://github.com/yarlson/ftl-examples/tree/main/flask) - Python Flask application with PostgreSQL -- More examples coming soon +```bash +# Create tunnels for all dependencies +ftl tunnels -Each example provides a complete project structure with configuration files and deployment instructions. +# Connect to specific server +ftl tunnels --server my-project.example.com +``` ## Development @@ -297,14 +169,46 @@ go mod download go test ./... ``` +## Example Projects + +Visit our [ftl-examples](https://github.com/yarlson/ftl-examples) repository for complete implementation examples: + +- [Flask Application with PostgreSQL](https://github.com/yarlson/ftl-examples/tree/main/flask) +- Additional examples coming soon + +## Troubleshooting + +### Common Issues + +1. Registry Authentication Failures + + - FTL currently supports only username/password authentication + - Token-based authentication is not supported + +2. SSH Connection Issues + - Verify SSH key permissions + - Ensure server firewall allows connections + - Check user permissions on target server + ## Contributing -Contributions are welcome. Please ensure: +1. Fork the repository +2. Create a feature branch +3. Commit your changes +4. Push to the branch +5. Create a Pull Request + +Please ensure: - Code follows project style guidelines -- Tests pass and new tests are added for new features -- Documentation is updated accordingly +- All tests pass +- Documentation is updated +- Commit messages are clear and descriptive + +## Security + +Report security vulnerabilities by opening an issue with the "security" label. We take all security reports seriously and will respond promptly. ## License -[MIT License](LICENSE) +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.