Custom workflow to automate your deployment using Gitlab and Ansible.
If you want to see your changes online every time you push some code, you need a custom workflow. You are at the right place.
Follow this short tutorial, I have the perfect recipe for you !
We will use the most suitable tools for our project, let me introduce our little friends :
- GitLab to host our project and run pipelines
- Ansible to deploy on remote server
- Docker to containerized our app and ship it easily and fast
- ReactJS fontend frameworks for the demo (it could be anything else, but you’ll need to adapt the container)
1. Create a new project with create-react-app and host it on Gitlab
We will create a new react app with CRA:
yarn create react-app <project_name> --template typescript
cd <project_name>
git remote add origin <gitlab_project_url>
git add .
git commit -m “Initial commit”
git push -u origin master
2. Create CI job with GitLab CI
At the root of your project we will create a new file .gitlab-ci.yml to enable the gitlab CI.
Currently this file contains only one stage dedicated to the build. We basically install only the dependencies of our project and not the devDependencies.
Then we build and we cache the build folder for later jobs.
We also cache the node_modules folder so the next time we don’t need to download all the node_modules again.
3. Containerize and release our app with Docker on the GitLab container registry
We have created a production build for our react app but we still need to create a container to ship it.
We added the release stage which build the container. We use the cache again but for the layers of the image so the less the container change the faster it will be built. We need to login to the project registry thanks to predefined variables and simply push the freshly created container to the registry.
4. Deploy and update our app in production
Now we have prepared everything for the deployment but our app is stored in a container registry but still not running in production. We will be a bit hand-made here.
4.1 Create a SSH key
First thing, we need to be able to connect our deployment server through SSH. So let’s create an SSH key !
sh-keygen -t ed25519 -f ~/.ssh/id_ansible -N ''
ssh-copy-id -i ~/.ssh/id_ansible <user>@<ip>
The last command will add your public key on the server.
cat ~/.ssh/id_ansible
This command reveal your ssh private key, copy it we will use it in the next step. But do not share it with anyone !
4.2 Add a SSH Key to GitLab
In order to connect to your server and deploy the container we need to add this private key to the runner.
To upload the key to GitLab, go to Settings > CI/CD > Variables and click on Add variable. In key write ANSIBLE_DEPLOY_KEY and in Value paste the private key. If you have not created protected branches or tags, uncheck Protect variable, click Add Variable and you're done.
4.3 Create a docker-compose file
On your server under /home/<user>/prod create a docker-compose.yml in order to run your container.
4.4 Create an Ansible Playbook
We will use Ansible to execute remote command on the server during the pipelines, this setup does not aims to explain Ansible; it’s a simple setup.
At the root of your project you can create the ansible/ directory.
- in
ansible/hostscopy/paste the file under and replace the<user>and<ip> - in
ansible/roles/deployment/tasks/main.ymlcopy/paste the content of the second file - in
ansible/playbooksagain copy/paste the third file.
4.5 Deploying with Ansible playbook
Last step, we added the deploy stage that will connect to the server, pull from the registry and only restart the container we pulled.
Thoughts
I’m aware that this setup does not cover every use case and does not follow every best practice in terms of security, like importing a ssh private key in GitLab or not handling errors if deployment failed.
But I wanted to keep it simple as a basic setup so you can adapt it to your needs, if you have any advise feel free to write a comment, this is my first try so I will definitely improve it.
Thank you for reading !
Top comments (1)
Easy to read and follow, thanks for sharing