Introduction

If you haven't read the previous post about setting up a secure VPS with Nginx and Docker, I recommend checking it out first here.

Automating Deployments with GitHub Actions

Following up on my previous post about setting up a secure VPS, let's dive into how to automate your deployments using GitHub Actions. After a few months of being caught up with other commitments, I'm excited to finally revisit this topic and share my refined deployment steps. We'll create a workflow that builds your Docker image, pushes it to Docker Hub, and deploys it to your VPS automatically when you push to the main branch.

Prerequisites

Before we start, make sure you have:

A GitHub repository with your application code
A Docker Hub account
A VPS set up following the previous guide
SSH keys for VPS access

Setting Up GitHub Secrets

First, let's set up the secrets your workflow will need. Go to your GitHub repository's settings, navigate to "Secrets and variables" → "Actions", and add the following secrets:

DOCKER_USERNAME=your-dockerhub-username
DOCKER_PASSWORD=your-dockerhub-password
APP_NAME=your-app-name
VPS_HOST=your-vps-ip
VPS_USER=your-vps-username
VPS_SSH_KEY=your-private-ssh-key
DATABASE_URL=your-database-connection-string

For the SSH key, make sure to include the entire key content including the BEGIN and END markers:

-----BEGIN OPENSSH PRIVATE KEY-----
your_key_content_here
-----END OPENSSH PRIVATE KEY-----

Creating the Workflow Files

We'll need to create two files: the main workflow file and a custom action for environment variable handling.

1. Main Workflow File

Create a new file at .github/workflows/docker-build.yml:

# Name of the workflow
name: 🚀 Deploy
 
# Trigger the workflow only when code is pushed to the main branch
on:
  push:
    branches:
      - main
 
jobs:
  build:
    name: 🏗️ Build Docker image
    runs-on: ubuntu-latest
    steps:
      - name: 📥 Checkout repository
        uses: actions/checkout@v4
      - name: 🛠️ Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: 🔧 Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: 🔑 Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: 📝 Create .env file
        uses: ./.github/actions/create-env
        with:
          APP_NAME: ${{ secrets.APP_NAME }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
      - name: 🏗️ Build and Push Docker image
        run: |
          set -e  # Exit on any error
 
          COMMIT_ID=$(git rev-parse --short HEAD)
          DOCKER_REPO="${{ secrets.DOCKER_USERNAME }}/${{ secrets.APP_NAME }}"
 
          echo "🏗️ Building Docker image with tags: latest and ${COMMIT_ID}"
          if ! docker build --platform linux/arm64 --no-cache -t ${DOCKER_REPO}:latest -t ${DOCKER_REPO}:${COMMIT_ID} .; then
            echo "❌ Failed to build Docker image"
            exit 1
          fi
 
          echo "🚀 Pushing Docker images..."
          if ! docker push ${DOCKER_REPO}:latest; then
            echo "❌ Failed to push latest tag"
            exit 1
          fi
          if ! docker push ${DOCKER_REPO}:${COMMIT_ID}; then
            echo "❌ Failed to push commit tag"
            exit 1
          fi
 
          echo "✅ Build and push completed successfully!"
 
  deploy:
    name: 🚀 Deploy to VPS
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: 📥 Checkout repository
        uses: actions/checkout@v4
      - name: 🔐 Setup SSH Agent
        uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.VPS_SSH_KEY }}
      - name: 📝 Create .env file
        uses: ./.github/actions/create-env
        with:
          APP_NAME: ${{ secrets.APP_NAME }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
- name: 🚀 Deploy to VPS
        run: |
          # Add host key verification
          mkdir -p ~/.ssh
          ssh-keyscan -H ${{ secrets.VPS_HOST }} >> ~/.ssh/known_hosts
          
          # Copy .env file to VPS
          scp .env ${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }}:~/.env
 
          # Run deployment commands via SSH
          ssh ${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }} "
            set -e
            
            # Login to Docker Hub (non-interactive)
            docker login -u '${{ secrets.DOCKER_USERNAME }}' --password-stdin <<< '${{ secrets.DOCKER_PASSWORD }}'
            
            # Pull the latest image
            docker pull ${{ secrets.DOCKER_USERNAME }}/${{ secrets.APP_NAME }}:latest
            
            # Stop and remove existing container
            docker stop ${{ secrets.APP_NAME }}-container || true
            docker rm ${{ secrets.APP_NAME }}-container || true
            
            # Start new container
            docker run -d \
              --name ${{ secrets.APP_NAME }}-container \
              -p 3000:3000 \
              --env-file .env \
              ${{ secrets.DOCKER_USERNAME }}/${{ secrets.APP_NAME }}:latest
            
            # Verify container is running
            if ! docker ps | grep -q '${{ secrets.APP_NAME }}-container'; then
              echo '❌ Container failed to start'
              docker logs ${{ secrets.APP_NAME }}-container
              exit 1
            fi
          "
      - name: 🧹 Delete .env file
        run: |
          rm .env
      - name: ✨ Notify success
        run: echo "🎉 Deployment completed successfully!"

2. Environment Variables Action

Create a new file at .github/actions/create-env/action.yml:

name: "Create Environment File"
description: "Creates a .env file with the necessary environment variables"
inputs:
  APP_NAME:
    description: "Application name"
    required: true
  DATABASE_URL:
    description: "Database URL"
    required: true
runs:
  using: "composite"
  steps:
    - name: Create .env file
      shell: bash
      run: |
        cat > .env << EOF
        APP_NAME=${{ inputs.APP_NAME }}
        DATABASE_URL=${{ inputs.DATABASE_URL }}
        REACT_APP_WAITLIST_ENABLED=true
        NODE_ENV=production
        EOF

Testing the Workflow

To test your workflow:

Make sure all required secrets are set in your repository:
- DOCKER_USERNAME
- DOCKER_PASSWORD
- APP_NAME
- VPS_HOST
- VPS_USER
- VPS_SSH_KEY
- DATABASE_URL
Create the necessary files:
- .github/workflows/docker-build.yml
- .github/actions/create-env/action.yml
Commit and push your changes to the main branch
Go to the "Actions" tab in your GitHub repository
Watch the workflow execute - you'll see nice emoji indicators for each step!
Check your VPS to verify the deployment

Troubleshooting

Common issues and solutions:

Environment Variables Issues
- Verify all secrets are correctly set in GitHub
- Check if the create-env action is properly configured
- Ensure the .env file is being created and cleaned up properly
SSH Connection Failed
- Verify your SSH key is correctly formatted in GitHub secrets
- Check if the VPS_USER has proper permissions
- Ensure your VPS firewall allows SSH connections
Docker Build Failed
- Check if your Dockerfile is in the repository root
- Verify Docker Hub credentials
- Ensure sufficient disk space on the GitHub runner
Deployment Failed
- Check if the container port is available on your VPS
- Verify Docker Hub login credentials
- Check container logs for application errors
- Verify environment variables are correctly set in the container

Best Practices

The updated workflow implements several best practices:

Environment Management
- Separate action for environment variable handling
- Clean up of sensitive files after use
- Production-specific configurations
Security
- Secure secrets management
- Non-interactive Docker login
- SSH key-based authentication
- Proper cleanup of sensitive data
Reliability
- Container health verification
- Detailed error logging
- Proper error handling with set -e
- Version tagging with commit hashes
User Experience
- Clear, emoji-based status indicators
- Descriptive step names
- Helpful error messages
- Clean workspace management

Next Steps

Consider these enhancements for your workflow:

Multiple Environments
- Add staging environment
- Configure environment-specific variables
- Implement deployment approvals
Monitoring and Notifications
- Add Slack/Discord notifications
- Implement deployment tracking
- Set up monitoring alerts
Performance Optimization
- Implement caching for Docker layers
- Optimize build steps
- Configure parallel jobs where possible
Testing Integration
- Add automated tests
- Implement smoke tests post-deployment
- Set up rollback procedures

With these improvements, your deployment workflow is now more robust, secure, and user-friendly. The addition of environment variable management and enhanced feedback makes it easier to maintain and troubleshoot when needed.

Happy coding!

Diogo

Setting Up Automated Deployments with GitHub Actions