The deployment feature gives you the ability to deploy a branch of your GitLab repository into your development environment.
Deployment context
When deploying to a hyperlane environment, anything that is not present:
- in mounted directories: img, override, upload, modules, mails, themes, translations, config, download
- Or versioned by .gitignore
WILL BE DELETED
If you need to keep large folders without versioning them, you can create symbolic links by following the following documentation: Create symbolic links (symlink)
Automatic commits
The developer environment has a feature to always automatically commit the latest changes.
This allows you to always have a trace on git of local changes.
These commits are made on the branch hyperlane-master
If you do not want to keep this functionality you can add a file .no-file-watch in /vol/site/current/
How to deploy with the repository
System configuration
This feature is only available if you have set Git to deployment mode, DEPLOY tab.
The configuration is only accessible in the development environment, you cannot deploy to any other environment.
Configuring the feature
In the same tab, you can set the automatic deployment option. This gives you the ability to synchronize your development environment with the branch selected in the tab credentials. By default, it ismaster which is selected.
Every time you push something into your currently selected branch, a deployment is performed. This is also true if there is a merge request (MR) commit on the branch.
In the tab credentials, you will find a drop-down list with the list of branches available in the repository.
You can update it whenever you want.
Deployment steps
To deploy something, you must first commit and push something.
Clone the project to your local machine
Here is an example of the user interface. You can easily clone the project to your machine.
Take a look at the SSH connection to facilitate the process.
Use git to commit and push
Here is an example of basic git commands, after file updates.
# Add your updates in the index
git add .
# Comment your commit please :thank:
git commit -m "my usefull comment"
# Send your updates into your repository
git push origin my-branch
Deploy in development
In the same tab (DEPLOY), new commits (never deployed) appear.
You need to press the DEPLOY NOW button to deploy the new commits pushed to the branch. This will deploy it into the environment. This is not necessary if you have enabled Automatic Deployment.
🚨 Be careful, sometimes updates were made directly on the server (via SFTP, a module, etc.). In the DEPLOY tab you will find a new window called "Unmerged changes detected" in which you will find the details of the updates (on a new branch hyperlane-my-branch ).
Two options, first, don't use it and clear the updates with a new (forced) deployment, second, click the "Review and merge" button to get the detail and use the GitLab link to go to the temporary branch created in order to compare with the latest version. You can easily merge and deploy.
Verify that the deployment worked correctly
Now you need to check in the deployment in the EVENTS tab and a new line should be there with Deploy latest code from Git with the name of the user who deployed it and the date when it happened. For example :
A deployment may fail, you should be careful and use the documentation for debugging (see below).
How does repository deployment work?
Deployment goes through a few steps to ensure everything should work fine once completed, like checking your PrestaShop configuration, installing dependencies with composer and autoload regeneration and much more.
A deployment creates a new build directory in your development environment. It does not simply overwrite the existing one.
If the deployment is successful, no action is required.
# Go to the approot directory or /vol/site
cd /opt/approot;
# List the builds
ls -la
Repository best practices
Use a workflow
As you should know, it is really not advisable to work directly on the master branch. The best practice is to use a new branch to develop a new feature, but you can also go further with a workflow, a way of managing your work in the repository. On PS Hosting, we use Git Flow but this way of working is not mandatory, it is a concrete example to understand how a workflow can work with Git.
Install git flow on your local machine
# Linux
apt-get install git-flow
Initialize git flow
Go to the root directory of your project.
# This will init the workflow on your current project
git flow init
A few questions are asked about the name you want to give to the feature, the version (…) you are free to configure it as you wish, with a default configuration or not.
The default configuration on git flow:
develop → The reference branch to start/finish a new feature
release → A version to be delivered
master → The production environment
However, with PS Hosting and its multiple environments and the repository linked to the development environment, it would be better to configure it like this:
The configuration you should have in mind for PS Hosting:
develop → The reference branch to start/finish a new feature
release → A version to be delivered
master → The development environment
Simple example with git flow
The project is already configured on your local machine (git clone, git flow installation, etc.)
# Go to the right branch
git checkout develop
# Start new feature
git flow feature start my-super-feature
# Live your life (updates files, commit & push)
# ...
# Finish a feature
git flow feature finish my-super-feature
Read the official documentation and avoid a lot of errors.
Clean your server of failed deployments
After a failed deployment, you may see build directories that are not used at all. We need to clean them up before the next clone, after a successful deployment. You can list these constructions here:
# Go to the approot directory or /vol/site
cd /opt/approot;
# List the builds
ls -la
The builds in use are those with a symbolic link to the current & previous directories. Two important rules you should keep in mind:
The current and previous directories should never be deleted! Never.
Do not delete build directories until the volumes have been unmounted. Never.
To unmount volumes, we will unmount and delete them one by one. Here's how to do it:
Select the one that is neither related to the current nor to the previous one, as in this example, the construction “build.20220406-105238-b5f54fe1”
Now we need to unmount everything in "build.20220406-105238-b5f54fe1", we start by listing what is mounted:
cat /proc/mounts | grep [build_name]
You should get something like this:
We need to unmount each subdirectory listed, one by one, with this command:
umount /vol/site/[build_name]/[img|override|....]
The commands will look like this:
umount /vol/site/build.20220406-105238-b5f54fe1/img;
umount /vol/site/build.20220406-105238-b5f54fe1/upload;
umount /vol/site/build.20220406-105238-b5f54fe1/modules;
umount /vol/site/build.20220406-105238-b5f54fe1/themes;
umount /vol/site/build.20220406-105238-b5f54fe1/translations;
umount /vol/site/build.20220406-105238-b5f54fe1/download;
umount /vol/site/build.20220406-105238-b5f54fe1/vendor;
umount /vol/site/build.20220406-105238-b5f54fe1/override;
If you want to save time, here is an empty example you can use, replace build_name
# replace build-name by your build name :)
umount /vol/site/build-name/img;
umount /vol/site/build-name/upload;
umount /vol/site/build-name/modules;
umount /vol/site/build-name/themes;
umount /vol/site/build-name/translations;
umount /vol/site/build-name/download;
umount /vol/site/build-name/vendor;
umount /vol/site/build-name/override;
Check that everything went well by listing again:
cat /proc/mounts | grep [build_name]
The result should be empty. You can now safely delete the actual build directory:
rm -rf [build_name]