Deploylify

A CLI tool that helps developers to set up automated deployment of services to AWS EC2 instances via GitHub Actions.

Features

• Simple configuration file for deployment settings
• Automatic GitHub Actions workflow generation
• Support for Node.js and Docker projects
• Secure deployment using SSH keys
• Zero-config deployment process
• Secure environment variable handling via GitHub secrets

Installation

npm install -g deploylify

Usage

1. Initialize a new configuration:

deploylify init

This will create a deploy.json file with your deployment settings.

2. Generate the GitHub Actions workflow:

deploylify generate

This creates the .github/workflows/deploy.yml file that handles the automated deployment.

3. Add required secrets to your GitHub repository:

   Learn how to add secrets to your repository

   Required secrets:

   • EC2_HOST: Your EC2 instance's public DNS or IP
   • EC2_USER: SSH user (usually 'ubuntu')
   • EC2_KEY: Base64-encoded SSH private key (how to create and encode SSH keys)

     # Generate SSH key
     ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ./deploy_key
          
     # Base64 encode the private key (the content will be your EC2_KEY secret)
     cat deploy_key | base64
          
     # Copy the public key to your EC2 instance's authorized_keys
     cat deploy_key.pub >> ~/.ssh/authorized_keys

   • EC2_DEPLOY_PATH: Path on EC2 where code will be deployed
   • Each variable listed in your config's private array

4. Push your code to trigger the deployment:

git add .
git commit -m "Setup CI/CD with deploylify"
git push

Prerequisites

Before using deploylify, ensure you have:

1. An AWS EC2 instance running:

   • Launch a new EC2 instance
   • Connect to your instance

2. Required software on your EC2 instance:

   • Git: sudo apt-get update && sudo apt-get install git
   • For Node.js projects:
     • Install Node.js
     • Install PM2
   • For Docker projects:
     • Install Docker on Ubuntu
     • Post-installation steps for Linux

3. GitHub repository with:

   • Actions enabled
   • Secrets configured

Configuration

The cicd.config.json file supports the following options:

{
  "type": "node",             // "node" or "docker"
  "build": "npm run build",   // Optional build command
  "test": "npm test",        // Optional test command
  "deployBranch": "main",    // Branch that triggers deployment
  "ec2": {
    "host": "ec2-xx-xx.amazonaws.com",  // Used for local testing
    "user": "ubuntu",                   // Used for local testing
    "deployPath": "/home/ubuntu/app"    // Where to deploy on EC2
  },
  "env": {                    // Optional environment configuration
    "general": {              // Non-sensitive environment variables
      "NODE_ENV": "production",
      "PORT": "3000",
      "LOG_LEVEL": "info"
    },
    "private": [             // Names of sensitive environment variables
      "DATABASE_URL",        // Each name must match a GitHub secret
      "API_KEY",
      "JWT_SECRET"
    ]
  }
}

Note: SSH authentication is handled entirely through the EC2_KEY GitHub secret, not through local SSH keys. This ensures better security and easier setup across different development machines.

Environment Variables

deploylify supports two types of environment variables:

1. General Environment Variables

These are non-sensitive variables that can be directly specified in your cicd.config.json:

"env": {
  "general": {
    "NODE_ENV": "production",
    "PORT": "3000",
    "LOG_LEVEL": "info"
  }
}

2. Private Environment Variables

These are sensitive variables that are stored securely as individual GitHub secrets:

1. List the private variable names in your config:

"env": {
  "private": ["DATABASE_URL", "API_KEY", "JWT_SECRET"]
}

2. Add each variable as a separate GitHub secret:
   • Go to Settings > Secrets and variables > Actions in your repository
   • For each variable in your private array, create a secret with the exact same name
   • Detailed guide on managing repository secrets

Docker Support

For Docker projects ("type": "docker"), ensure you have:

1. A valid Dockerfile in your project root

   • Best practices for writing Dockerfiles
   • Example Node.js Dockerfile

2. Docker installed on your EC2 instance:

   # Install Docker on Ubuntu
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
      
   # Add your user to docker group (requires re-login)
   sudo usermod -aG docker $USER

   Full Docker installation guide

3. Proper permissions to run Docker commands:

   • Post-installation steps for Linux
   • Docker permission best practices

Security Best Practices

1. EC2 Security:

   • AWS security best practices
   • Use security groups to limit access
   • Keep your system updated
   • Use strong SSH keys

2. GitHub Actions Security:

   • Security hardening for GitHub Actions
   • Never print secrets in logs
   • Use minimum required permissions
   • Regularly rotate secrets

3. Docker Security:

   • Docker security best practices
   • Keep base images updated
   • Use multi-stage builds
   • Run containers with least privilege

Troubleshooting

Common issues and solutions:

1. SSH Connection Issues:

   • Troubleshoot EC2 SSH connections
   • Verify security group settings
   • Check SSH key permissions

2. Docker Issues:

   • Docker troubleshooting guide
   • Check Docker service status
   • Verify user permissions

3. GitHub Actions Issues:

   • Troubleshooting GitHub Actions
   • Check workflow run logs
   • Verify secret names and values

License

MIT