GitLab Continues Deployment tutorial

Are you tired of manually deploying your PHP projects every time you make a push to the repository? Well, I’ve got some great news for you! In this post, I’ll show you how to set up an automatic deployment process using GitLab CI/CD.

Imagine a scenario where with each push to your repository, your application automatically gets built and deployed to your remote server without any hassle. Sounds amazing, right? That’s exactly what we’ll achieve through a simple and effective configuration for the GitLab CI/CD pipeline.

This configuration is designed to handle both the backend and frontend of your PHP application, making it suitable for any project based on popular frameworks like Laravel or Symfony. With GitLab CI/CD, you won’t even need to worry about installing Composer and NodeJS on your production machine. Everything will be prepared and ready for deployment.

By following the steps outlined in this post, you’ll be able to streamline your development process and save valuable time and effort. So let’s dive in and discover the power of GitLab CI/CD in automating the deployment of your PHP projects!

What is CI/CD?

In the realm of modern software development, Continuous Integration (CI) and Continuous Deployment (CD) have emerged as indispensable practices.

Continuous Integration involves the frequent merging of code changes from multiple developers into a shared repository. By automating this process, CI ensures that all modifications are smoothly integrated, thereby detecting and resolving potential conflicts early on. This practice promotes collaboration, fosters a cohesive codebase, and reduces integration issues that may arise when working on complex projects.

On the other hand, Continuous Deployment takes the automation a step further by facilitating the seamless release and deployment of software. With CD, any code change that successfully passes the integration tests can be automatically deployed to production environments. By eliminating the need for manual intervention, CD accelerates the release cycle, enabling faster time-to-market and more reliable software updates.

The combination of CI and CD revolutionizes the software development lifecycle, enabling teams to continuously deliver high-quality applications with greater efficiency. By automating the integration and deployment processes, developers can focus on writing code, while the CI/CD pipeline takes care of building, testing, and deploying the application. This leads to shorter development cycles, enhanced code stability, and increased agility in responding to customer feedback and market demands.

In summary, CI and CD are complementary practices that bring tremendous value to software development projects. By embracing these practices, development teams can streamline their workflows, improve collaboration, and deliver robust and reliable software at an accelerated pace.

Preparing the Webserver for Continuous Deployment

To prepare your webserver for seamless Continuous Deployment, follow these steps:

  1. Start by logging into your webserver using SSH. You can either use an existing user or create a new one specifically for deployment purposes. To create a new user, execute the following command:
sudo adduser deployer
  1. To avoid the need to change file permissions every time, add the web server user (e.g., www-data) to the deployer group:
sudo usermod -a -G deployer www-data
  1. Create a new directory to host your project:
sudo mkdir /var/www/your_project
  1. Next, change the owner of the project directory to the deployer user:
sudo chown -R deployer:deployer /var/www/your_project
  1. If your project requires a specific configuration file, you can place it in the newly created directory. Otherwise, you can omit the cp .env.local $CI_COMMIT_SHA/ command in the configuration steps below.
  1. If you don’t already have an SSH key, generate one by logging in as the deployer user:
su deployer

Then, create the SSH key using the following command (remember to replace email@example.com with your actual email address):

ssh-keygen -t ed25519 -C "email@example.com"
  1. To enable SSH access, add the content of the public key to the authorized_keys file:
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
  1. Finally, copy the content of the private key, as it will be needed for the GitLab configuration:
cat ~/.ssh/id_rsa

By following these steps, you’ll ensure that your webserver is properly set up for Continuous Deployment, allowing for smooth and efficient deployment of your project.

Setting up a GitLab repository for Continuous Deployment

To enable or disable GitLab CI/CD Pipelines for your project, follow these steps:

  1. Open GitLab and navigate to your project.
  2. Click on “Settings” in the sidebar menu.
  3. In the Settings page, select “General” from the tabs on the left.
  4. Scroll down and click on “Visibility, project features, permissions” to access the related options.
  5. Expand the “Repository” section.
  6. Look for the “CI/CD” toggle and enable or disable it based on your desired configuration.

Now, let’s proceed with adding the necessary environment variables:

  1. Go back to your project’s Settings.
  2. This time, select “CI/CD” from the tabs on the left.
  3. Scroll down to find the “Variables” section.
  4. Click on the “Add Variable” button to create a new variable.
  5. For each variable, add the following details:
    • Variable Key: SSH_PRIVATE_KEY
    • Variable Value: Copy the contents of the id_rsa file from the previous step.
    • Variable Key: SSH_USER
    • Variable Value: deployer (or the desired username)
    • Variable Key: SSH_HOST
    • Variable Value: Your server’s IP address
    • Variable Key: PROJECT_FOLDER
    • Variable Value: Enter the desired folder name
  6. Click on the “Add Variable” button to save each variable.

By configuring these environment variables, you provide essential information for your CI/CD pipeline to connect and deploy to the target server. The SSH_PRIVATE_KEY variable allows secure authentication, SSH_USER specifies the username (e.g., deployer), SSH_HOST indicates the server’s IP address, and PROJECT_FOLDER denotes the desired folder name.

Remember to save the settings after adding each variable. With these variables in place, your CI/CD pipeline will have the necessary information to deploy your project seamlessly.

Prepare CI/CD Project Configuration

To establish a smooth and efficient CI/CD process for your project, you’ll need to create a .gitlab-ci.yml file at the root of your project directory. This file serves as the configuration blueprint for your CI/CD pipeline.

Open a text editor and create a new file named “.gitlab-ci.yml”. Then, populate the file with the appropriate content based on your project’s specific requirements. Below is a sample template that you can modify as needed:

image: bogkonstantin/php-7.4-node-12-debug:latest

stages:
    - build
    - deploy

build:
    stage: build
    only:
        - master
    artifacts:
        paths:
            - ./
    script:
        - export APP_ENV=prod
        - composer install --no-dev --optimize-autoloader
        - yarn install
        - yarn encore production
        - rm -r node_modules
        - mkdir -p var && chmod -R 777 var

deploy:
    stage: deploy
    only:
        - master
    before_script:
        - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
        - eval $(ssh-agent -s)
        - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
        - mkdir -p ~/.ssh
        - chmod 700 ~/.ssh
        - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config'
    script:
        - zip -r $CI_COMMIT_SHA.zip .
        - scp -p $CI_COMMIT_SHA.zip $SSH_USER@$SSH_HOST:/var/www/$PROJECT_FOLDER/
        - ssh $SSH_USER@$SSH_HOST "cd  /var/www/$PROJECT_FOLDER/ && unzip -q $CI_COMMIT_SHA.zip -d $CI_COMMIT_SHA && rm $CI_COMMIT_SHA.zip && cp .env.local $CI_COMMIT_SHA/ && ln -sfn $CI_COMMIT_SHA current && exit"

Providing Detailed Explanations:

  • image - this attribute specifies the Docker image utilized within the CI/CD pipeline. In this case, the image is a custom creation, based on the Debian operating system. It incorporates PHP 7.4, NodeJS 12, Composer 2, npm, and Yarn, pre-installed for your convenience. For more comprehensive insights into the specificities of this image, you can refer to the Dockerfile, available for examination here.
  • stages - this section defines the stages of the CI/CD pipeline. In the given configuration, there are two stages: “build” and “deploy”. It is often considered a good practice to include a separate stage for testing your application.
  • build - within the “build” stage, various tasks are performed. The first task involves installing Composer packages without dev dependencies. Additionally, the frontend is built, and the “node_modules” folder is removed to reduce the package size, as it is typically not required in the production environment. If you are using npm instead of Yarn, you can modify the command accordingly.
  • deploy - the “deploy” stage is responsible for deploying the application to the desired environment. In this case, the SSH key is added to the running container to enable secure authentication. Then, the built application is archived, uploaded to the remote server, unpacked, and finally, the symlink is updated to point to the new build. This ensures a smooth transition to the latest version of your application.

By utilizing the .gitlab-ci.yml file and its configurations, you can automate essential tasks, enhance collaboration, and streamline your development workflow. It empowers you to build, test, and deploy your project efficiently, while maintaining a high level of quality and reliability.

A Wrap-Up of Key Steps and Considerations

Once you are ready to proceed, you can initiate a commit and push it to the remote repository. This triggers the CI/CD pipeline, automatically executing the defined stages and actions. It’s important to ensure that your changes are properly committed and pushed, as this enables the pipeline to detect and incorporate the latest updates into the deployment process.

Additionally, don’t forget to update the folder configuration within your Nginx or Apache settings. This step ensures that the web server correctly points to the appropriate folder where your application is deployed. By adjusting the folder configuration, you guarantee that your web server serves the updated version of your project, reflecting the latest changes introduced through the CI/CD pipeline.

That covers the essential steps for setting up your CI/CD configuration. If you wish to test the configuration locally, you can utilize GitLab Runner, which facilitates the execution of jobs defined in the .gitlab-ci.yml file. For detailed information about GitLab Runner and its functionalities, you can refer to the comprehensive documentation available here.

With these steps completed, you can seamlessly leverage the power of continuous integration and deployment to streamline your development process and deliver reliable software with efficiency and ease.

Afterword

If you encounter any issues or have suggestions for improving the configuration, please don’t hesitate to reach out. Feel free to contact me directly, and I’ll be happy to help. Alternatively, you can also leave a comment on Twitter to share your thoughts and ideas. Your feedback is valuable, and I’m open to exploring better approaches or addressing any concerns you may have.


Related posts: