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 through a single YAML configuration file.

For comprehensive documentation, visit https://ftl-deploy.org

Features

• Zero-downtime deployments with automated health checks
• Single YAML configuration with environment variable support and validation
• 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
• GitHub Actions integration for automated CI/CD workflows

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

Choose one of the following installation methods:

Via Homebrew (macOS and Linux)

brew tap yarlson/ftl
brew install ftl

Direct Download

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/

Build from Source

go install github.com/yarlson/ftl@latest

Verify Installation

After installing FTL, verify it's working correctly by checking the version:

ftl version

Configuration

Create an ftl.yaml file in your project root:

project:
  name: my-project
  domain: my-project.example.com
  email: my-project@example.com
server:   host: my-project.example.com # Optional, defaults to project.domain   port: 22 # Optional, defaults to 22   user: my-project # Optional, defaults to current system user   sshkey: ~/.ssh/idrsa # Optional, auto-detected from standard locations
services:   - name: web     path: ./src     port: 80     health_check:       path: /     routes:       - path: /
dependencies:   - "postgres:16" # Using short notation   - name: redis # Using detailed definition     image: redis:7     volumes:       - redis_data:/custom/redis/path     env:       - REDISPASSWORD=${REDISPASSWORD:-secret}
volumes:   - redis_data

You can validate your configuration at any time using:

ftl validate

Environment Variables

• Required variables: Use ${VAR_NAME}
• Optional variables with defaults: Use ${VARNAME:-defaultvalue}

Usage

GitHub Actions Integration

Deploy automatically using the official FTL GitHub Action:

name: Deploy
on:   push:     branches: [main]
jobs:   deploy:     runs-on: ubuntu-latest     steps:       - uses: actions/checkout@v4
- name: Deploy with FTL         uses: yarlson/ftl-deploy-action@v1         with:           ssh-key: ${{ secrets.SSHPRIVATEKEY }}         env:           DATABASEURL: ${{ secrets.DATABASEURL }}

For complete GitHub Actions documentation, see the integration guide or visit the action repository.

Configuration Validation

# Validate your ftl.yaml configuration
ftl validate

Server Setup

ftl setup

Building Applications

FTL supports two deployment modes:

• Direct SSH Transfer (Default):

services:
  - name: web
    path: ./src # Path to directory containing Dockerfile

• Registry-based Deployment:

services:
  - name: web
    image: registry.example.com/my-app:latest
    path: ./src

Build command:

ftl build [--skip-push]

Deployment

ftl deploy

Log Management

# Stream all logs
ftl logs -f
View specific service logs
ftl logs my-app -n 150

SSH Tunnels

# Create tunnels for all dependencies
ftl tunnels

Development

# Clone repository
git clone https://github.com/yarlson/ftl.git
Install dependencies
cd ftl
go mod download
Run tests
go test ./...

Example Projects

Visit our ftl-examples repository for complete implementation examples:

• Flask Application with PostgreSQL
• Additional examples coming soon

Troubleshooting

Common Issues

• Configuration Validation Errors

- Ensure all required fields are present - Check port numbers are valid - Verify file paths exist - Confirm environment variables are properly defined

• Registry Authentication Failures

- FTL currently supports only username/password authentication - Token-based authentication is not supported

• SSH Connection Issues

- Verify SSH key permissions - Ensure server firewall allows connections - Check user permissions on target server

Contributing

• Fork the repository
• Create a feature branch
• Commit your changes
• Push to the branch
• Create a Pull Request

Please ensure:

• Code follows project style guidelines
• 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

This project is licensed under the MIT License - see the LICENSE file for details.