Setting Up CI/CD Pipeline for Laravel on GitLab with AWS EC2 Deployment

This guide will help you set up a CI/CD pipeline for a Laravel project on GitLab, deploy it to an AWS EC2 instance, and configure SSH keys for remote access to a Git repository. This method will save time by automating the login process to the server, changing the project directory, pulling the latest code from the repository, installing dependencies, and running the necessary build commands.

GitLab CI/CD Configuration

The following .gitlab-ci.yml file is used to define the CI/CD pipeline. It includes stages for deploying the project, setting environment variables for MongoDB, caching dependencies, and executing the deployment script.

stages:
  - deploy

variables:
  DB_CONNECTION: mongodb
  DB_MONGO_DSN: mongodb://host.docker.internal:27017
  DB_MONGO_DATABASE: petra_devs

cache:
  paths:
    - vendor/
    - node_modules/

deploy:
  stage: deploy
  script:
    - mkdir -p ~/.ssh
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan ap-south-1.compute.amazonaws.com >> ~/.ssh/known_hosts
    - ssh -i ~/.ssh/id_rsa [email protected] 'git config --global --add safe.directory /var/www/html/petra-devs && cd /var/www/html/petra-devs && git pull origin main && composer install && npm run dev'
  only:
    - main

Note: The SSH_PRIVATE_KEY variable must be set in GitLab CI/CD Variables in the settings.

Setting SSH_PRIVATE_KEY in GitLab CI/CD for AWS EC2 Deployment

To deploy your application to an AWS EC2 instance using GitLab CI/CD, you need to configure the SSH_PRIVATE_KEY variable. This variable allows the CI/CD pipeline to access your AWS EC2 instance securely. Follow these steps to set it up:

Step 1: Generate or Locate Your PEM File

If you don’t already have an AWS PEM file, you need to generate one. This file is used to securely access your AWS EC2 instance. If you already have a PEM file, you can use that.

Step 2: Convert PEM File to Private Key Format

GitLab CI/CD expects the private key to be in OpenSSH format. If your PEM file is not already in this format, you need to convert it:

openssl rsa -in your-key.pem -out id_rsa

This command will convert the PEM file into a format suitable for SSH use.

Step 3: Base64 Encode the Private Key

Base64 encode the private key file to ensure it can be safely stored as a GitLab CI/CD variable:

cat id_rsa | base64

This will output a Base64 encoded string of your private key.

Step 4: Add SSH_PRIVATE_KEY to GitLab CI/CD Variables

1. Navigate to your GitLab project.

2. Go to Settings > CI/CD and expand the Variables section.

3. Click Add Variable.

4. In the Key field, enter SSH_PRIVATE_KEY.

5. In the Value field, paste the Base64 encoded string of your private key.

6. Check the Protect variable option if you want this variable to be available only to protected branches and tags.

7. Click Add Variable to save the configuration.

This guide provides a detailed explanation of configuring a CI/CD pipeline in GitLab for deploying a Laravel project to an AWS EC2 instance. The setup includes managing environment variables, caching dependencies, and automating the deployment process using SSH keys.

Reference

For more information on setting up SSH keys in GitLab CI/CD, refer to the official GitLab documentation: GitLab CI/CD SSH Keys Setup.

GitLab CI/CD Configuration Explained

The .gitlab-ci.yml file defines the CI/CD pipeline stages and deployment process. Here's a breakdown of the configuration:

stages:
  - deploy

Stages: Defines the stages of the pipeline. In this configuration, there is only one stage named deploy.

variables:
  DB_CONNECTION: mongodb
  DB_MONGO_DSN: mongodb://host.docker.internal:27017
  DB_MONGO_DATABASE: petra_devs

Variables: Defines environment variables used during the deployment:

DB_CONNECTION: Specifies the database connection type (MongoDB in this case).
DB_MONGO_DSN: Defines the MongoDB Data Source Name, pointing to the MongoDB server.
DB_MONGO_DATABASE: Specifies the name of the MongoDB database to use.

cache:
  paths:
    - vendor/
    - node_modules/

Cache: Lists the paths to cache dependencies:

vendor/: Caches Composer dependencies.
node_modules/: Caches Node.js dependencies.

deploy:
  stage: deploy
  script:
    - mkdir -p ~/.ssh
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan ap-south-1.compute.amazonaws.com >> ~/.ssh/known_hosts
    - ssh -i ~/.ssh/id_rsa [email protected] 'git config --global --add safe.directory /var/www/html/petra-devs && cd /var/www/html/petra-devs && git pull origin main && composer install && npm run dev'
  only:
    - main

Deploy Job: This job runs during the deploy stage and includes the following steps:

mkdir -p ~/.ssh: Creates the SSH directory if it doesn't exist.
echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa: Adds the private SSH key to ~/.ssh/id_rsa, removing any carriage return characters.
chmod 600 ~/.ssh/id_rsa: Sets the correct permissions for the SSH key file to ensure it is secure.
ssh-keyscan ap-south-1.compute.amazonaws.com >> ~/.ssh/known_hosts: Adds the AWS EC2 instance's SSH key to the known hosts file to avoid SSH connection prompts.
ssh -i ~/.ssh/id_rsa [email protected] 'git config --global --add safe.directory /var/www/html/petra-devs && cd /var/www/html/petra-devs && git pull origin main && composer install && npm run dev': Connects to the AWS EC2 instance using SSH, configures Git, navigates to the project directory, pulls the latest code from the repository, installs Composer dependencies, and runs the NPM build command.

Only: Specifies that this deployment job should only run when changes are made to the main branch.

Setting Permissions on the Server

To avoid the error cannot open '.git/FETCH_HEAD': Permission denied, set the correct permissions for the project directory on the server:

sudo chown -R ubuntu:ubuntu /var/www/html/petra-devs

Setting Up SSH Keys on the Server for Remote Access

To enable the CI/CD pipeline to access your Git repository remotely, you need to set up SSH keys on your server. Follow these steps:

Generate an SSH key pair on your local machine (if you haven't already):
```
ssh-keygen -t rsa -b 4096 -C "[email protected]"
```

Copy the public key to your server:

ssh-copy-id -i ~/.ssh/id_rsa.pub [email protected]

Add the private key to GitLab CI/CD variables:
```
cat ~/.ssh/id_rsa | base64
```
Copy the output and add it as a variable named SSH_PRIVATE_KEY in your GitLab project settings under CI/CD variables.
Update the .gitlab-ci.yml file to use the SSH key for accessing the repository, as shown in the provided script.

Benefits

This setup automates the process of logging into the AWS EC2 instance, navigating to the project directory, pulling the latest code from the Git repository, installing Composer dependencies, and running the build command (e.g., npm run dev). This automation saves time and reduces the chance of human error during deployment.

Published By: Krishanu Jadiya
Updated at: 2024-07-22 14:47:33