Automating the deployment of your website on your VPS via GitLab CI/CD

Objective

Automating the deployment of your website on a VPS greatly simplifies the management of updates. With GitLab CI/CD, you can configure an automatic deployment pipeline, avoiding manual deployments. This method ensures fast and reliable deployments, while reducing the risk of human error. Whether you are a beginner or an experienced developer, this tutorial will help you set up a professional solution adapted to your needs.

Find out how to automate the deployment of your web applications with GitLab CI/CD on an OVHcloud VPS.

Requirements

• A functional VPS in your OVHcloud account
• An active GitLab account
• A GitLab project containing your website code
• A VPS configured with the necessary services (e.g. Apache/Nginx, PHP, DBMS, etc.)
• Administrative access to the VPS (via SSH)
• Ensure the rsync package is installed on the VPS (required for file synchronization)

Instructions

Content overview

• Configure SSH access for GitLab CI/CD
• Add private key to GitLab
• Configure GitLab CI/CD for automatic deployment
• Test and verify pipeline
• Conclusion

Configure SSH access for GitLab CI/CD

To allow GitLab CI/CD to automatically deploy your website, configure a secure SSH access to your VPS.

Create an SSH key pair

Log in to your VPS via SSH and generate a dedicated SSH key pair for GitLab CI/CD:

ssh-keygen -t rsa -b 4096 -C "gitlab-ci" -f /home/<user>/.ssh/deploy_key

Replace <user> with the user configured to connect to your VPS.

Press Enter when prompted for a passphrase (leaving the passphrase empty simplifies automating deployment with GitLab CI/CD. However, it is imperative to secure the private key by limiting it to this use and storing it securely).

You get two files:

• /home/<user>/.ssh/deploy_key: private key
• /home/<user>/.ssh/deploy_key.pub: public key

Refer to the official GitLab documentation for more details on generating an SSH key pair.

Configure the public key on the VPS

To allow GitLab CI/CD to connect to your VPS via SSH and deploy your website’s code there, add the generated public key to the list of authorized keys on the VPS.

1. Create the .ssh directory:

mkdir -p /home/<user>/.ssh
chmod 700 /home/<user>/.ssh

2. Add the public key to the authorized_keys file:

cat /home/<user>/.ssh/deploy_key.pub >> /home/<user>/.ssh/authorized_keys
chmod 600 /home/<user>/.ssh/authorized_keys

3. Test the SSH connection with the private key to confirm that the access is functional:

ssh -i /home/<user>/.ssh/deploy_key <user>@<VPS_IP>

Replace <user> with the user configured to connect to your VPS and <VPS_IP> with the IP address of your VPS.

Add the public key to GitLab

Once you have configured the public key on your VPS, add it to your GitLab account. Copy the content of the generated public key from your VPS with:

cat /home/<user>/.ssh/deploy_key.pub

Follow the steps in the "Add an SSH key to your GitLab account" section of the GitLab official documentation to add your public key to your GitLab account.

Configure SSH access to GitLab on the VPS

To ensure that GitLab uses the generated private key to establish a secure SSH connection, configure the ~/.ssh/config file. This step facilitates subsequent commands by eliminating the need to manually specify the private key each time you interact with GitLab.

On your VPS, create or modify the file ~/.ssh/config:

nano ~/.ssh/config

Add this configuration for access to GitLab:

Host gitlab.com
    HostName gitlab.com
    User git
    IdentityFile /home/<user>/.ssh/deploy_key

Save and exit the editor.

Test the SSH connection with GitLab:

ssh -T git@gitlab.com

The following message should appear:

Welcome to GitLab, <username>!

Add the private key to GitLab

Copy the content of the generated private key to your VPS with:

cat /home/<user>/.ssh/deploy_key

To add the SSH private key as a CI/CD variable, see the official GitLab documentation.

Configure GitLab CI/CD for automatic deployment

Create a .gitlab-ci.yml file for the pipeline

1. In your local GitLab project, create a .gitlab-ci.yml file at the root:

nano .gitlab-ci.yml

2. Add the following configuration to the file to automatically deploy your website:

stages:
  - deploy

deploy:
  stage: deploy
  image: debian:bullseye
  before_script:
    - apt-get update && apt-get install -y rsync openssh-client
    - mkdir -p ~/.ssh
    - echo "$DEPLOY_PRIVATE_KEY" > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -H <VPS_IP> >> ~/.ssh/known_hosts
  script:
    - rsync -avz --delete ./ <user>@<VPS_IP>:/var/www/html/
  only:
    - main

Replace:

• <VPS_IP> by your VPS IP address
• <user> by the SSH user configured on your VPS

3. Add the file, commit it then push the changes to the remote repository:

git add .gitlab-ci.yml
git commit -m "Add GitLab CI/CD pipeline configuration"
git push origin main

Check and test the pipeline

Check execution of the first pipeline

Go to the Build > Pipelines tab in the side menu of GitLab to check that your first pipeline ran successfully.

If an error occurs, click on the failed pipeline to view the logs.

Insufficient permissions

During the first deployment, errors can occur concerning permissions (Permission denied (13), rsync: failed to set times, etc.)

1. Ensure that the user has the required permissions

Ensure that the SSH user configured on your VPS has write permissions to the entire Git directory (/var/www/html) and its subdirectories:

sudo chown -R <user>:www-data /var/www/html
sudo chmod -R 775 /var/www/html

2. Test locally with rsync

Before relaunching the GitLab pipeline, test the rsync command manually from your local machine. This will allow you to confirm that the permissions are correctly configured:

rsync -avz --no-times --exclude='.git*' -e "ssh -i ./deploy_key -o StrictHostKeyChecking=no" ./ <user>@<VPS_IP>:/var/www/html/

If this command succeeds, then restart the pipeline on GitLab.

Conclusion

By following this guide, you have set up an automatic deployment pipeline between your GitLab project and your OVHcloud VPS using GitLab CI/CD. This workflow streamlines website updates, eliminating time-consuming manual deployments.

Go further

Getting started with a VPS

Secure a VPS

For specialized services (SEO, development, etc.), contact the OVHcloud partners.

Join our community of users.