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

• 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

• Docker installed locally for building images
• SSH access to target deployment servers
• Git for version control
• Go 1.16+ (only if building from source)

Choose one of the following installation methods:

brew tap yarlson/ftl
brew install ftl

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/

go install github.com/yarlson/ftl@latest

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

ftl version

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
 ssh_key: ~/.ssh/id_rsa # 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:
 - REDIS_PASSWORD=${REDIS_PASSWORD:-secret}
volumes:
 - redis_data

You can validate your configuration at any time using:

ftl validate

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

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.SSH_PRIVATE_KEY }}
 env:
 DATABASE_URL: ${{ secrets.DATABASE_URL }}

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

# Validate your ftl.yaml configuration
ftl validate

ftl setup

FTL supports two deployment modes:

1. Direct SSH Transfer (Default):

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

2. Registry-based Deployment:

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

Build command:

ftl build [--skip-push]

ftl deploy

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

# Create tunnels for all dependencies
ftl tunnels

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

Visit our ftl-examples repository for complete implementation examples:

• Flask Application with PostgreSQL
• Additional examples coming soon

1. Configuration Validation Errors

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

2. Registry Authentication Failures

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

3. SSH Connection Issues

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

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
• All tests pass
• Documentation is updated
• Commit messages are clear and descriptive

Report security vulnerabilities by opening an issue with the "security" label. We take all security reports seriously and will respond promptly.

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