Automatic Deployment

Sommaire

Overview #

We describe here how to automatically deploy your website on the LIRIS webserver. This supposes that the code for your website is hosted on the LIRIS gitlab. The deployment is done by triggering a site rebuild and upload on each commit pushed to gitlab. To do so, build scripts have to be added to your repository, and credentials should be setup to allow the gitlab runner to upload your website on the LIRIS server.

Setup dedicated credentials on your LIRIS account #

To upload the website on the server, we will use rsync. We therefore need valid ssh credentials for the connection. Since these credentials will be provided to gitlab, we don’t want these credentials to provided unrestricted access to your LIRIS account. Fortunately rsync provides the rrsync tool for this specific usage.

To setup your LIRIS account on the web server, you must first login through ssh

ssh <username>@connect.liris.cnrs.fr

Get the rrsync script from the rsync installation #

The rrsync script is distributed along rsync, and is provided in the documentation. You can transfer it to your home directory with

cp /usr/share/doc/rsync/scripts/rrsync ~/

You also need to setup proper permissions on the script to allow its execution.

chmod 700 ~/rrsync

Generate a dedicated pair of ssh keys #

Using a dedicated key ensures that if the key gets compromised, you can just disable it without impacting other services. SSH keys can use various types of encryption. We propose below safe parameters at the time of writing this article, but you should probably upgrade the key type with up to date standards. You can generate a pair of keys using

ssh-keygen -t ed25519 -f deploy-key -C "website-deploy@gitlab.liris.cnrs.fr"

In the above command, deploy-key controls the generated file names, and the -C "..." is optional and adds a comment to the key for you to remember its purpose. The command will ask you to provide a passphrase. Although it is generally good advice to systematically protect SSH keys with a passphrase, since such a passphrase would have to be setup along with the key in the deploy script this is pointless here. Therefore just hit enter and leave the field empty. This should result in an output similar to

Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in deploy-key.
Your public key has been saved in deploy-key.pub.
The key fingerprint is:
SHA256:Aunync4ktv/7/887qMW4hxbOmfjY5ivxUvA0rJ4rZQ4 website-deploy@gitlab.liris.cnrs.fr
The key's randomart image is:
+--[ED25519 256]--+
|                 |
|     .           |
|    o     .      |
|   . .   . +     |
|  . . . S = .    |
|   o . E = +o    |
|    + + * O.=o.  |
|   . * . BoXoo o |
|    ..+.+=XO=..o=|
+----[SHA256]-----+

As mentioned in the output, this generates two files. The deploy-key.pub file is your public key. It is used used to encrypt data before sending it to you, and can be safely distributed to anyone. In the above example, the generated public key looks like

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+3Ox7LsPXTAR/gqy+AVPdHcO8aJfbwH1VIWno8efgL website-deploy@gitlab.liris.cnrs.fr

The deploy-key file is the private key. It is used to decrypt data encoded using the public key. This file is for you only. In our case, the private key looks like

Restricting the key to rsync on a specific directory #

Allowing connection to your account using an ssh key is done by editing the ~/.ssh/authorized_keys file in your home directory on the LIRIS server. Create the file if it does not exist. To edit it, at the time of writing, nano or vim are available on the LIRIS server. Authorizing a key can be done by adding a line formatted as

command="$HOME/rrsync <desired directory>",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding <desired public key>

The <desired directory> should be the path to the directory where the upload will happen. For instance if the website is intended for a project, on the LIRIS server, projects are located in /home-projets and in the project directory, the website should be deployed to the public_html directory. For the present demo website, the path would therefore be

/home-projets/hugo-theme/public_html

Note that only project administrators are allowed to upload in their project directories.

The <desired public key> should be the one you generated. In the above example, this is

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+3Ox7LsPXTAR/gqy+AVPdHcO8aJfbwH1VIWno8efgL website-deploy@gitlab.liris.cnrs.fr

This is where the comment gets useful, to be able to quickly identify what the key is intended for, and remove the line if it gets compromised or obsolete.

With the added line in ~/.ssh/authorized_keys, it is now possible rsync to the specified directory using the private key. We therefore now need to provide the private key to gitlab and setup the build and deploy script.

Setup continuous integration on gitlab #

Gitlab provides tools to automatically run tasks on repositories. This is done by adding a .gitlab-ci.yml file at the root of your repository describing the tasks. We will also need to provide the private key to the deployment script. The key should not be directly written in the deploy script, since anyone able to read the contents of the repository would have the means to smash the website in your name on the LIRIS server.

Setup continuous integration variables #

Variables contain data outside of the repository to be provided to continuous integration tasks. For the deployment, we will need two variables, one to authenticate the LIRIS server to which the website is deployed, and another to provide the private key. Variables can be configured in the Settings > CI/CD panel

From this panel you can navigate to the Variables section, and use the button to add variables.

This opens a side panel to describe the variable. Our first variable will be named SSH_KNOWN_HOSTS and will contain the SSH server keys to ensure that the deploy script connects to the right server. LIRIS server keys can be obtained with

ssh-keyscan connect.liris.cnrs.fr

The example below shows the variable configured with the key at the time of writing this article.

Our second variable will be called SSH_PRIVATE_KEY and will contain the private key you previously generated. Using the private key in the example above, this would be

Build and deploy script #

The continuous integration script is added as a .gitlab-ci.yml file at the root of your repository.

stages:
  - build
  - deploy

build:
  stage: build
  image: floryn90/hugo:ext-alpine-ci
  tags:
    - docker
  variables:
    GIT_SUBMODULE_STRATEGY: recursive
    FF_DISABLE_UMASK_FOR_DOCKER_EXECUTOR: true
  script:
    - hugo build -b "<your website url>"
  artifacts:
    paths:
      - public/

deploy:
  stage: deploy
  image: instrumentisto/rsync-ssh
  tags:
    - docker
  variables:
    GIT_STRATEGY: none
  before_script:
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
    - chmod 600 ~/.ssh/known_hosts
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
  script:
    - rsync -az --delete public/ "<your login>@connect.liris.cnrs.fr:"
  only:
    - main

In the above script, <your website url> should be replaced by the actual url of your website. For this example website, that would be https://projet.liris.cnrs.fr/hugo-theme. The <your login> placeholder should be your LIRIS login.

Beware that the target folder for rsync will be automatically setup by the rrsync command provided in your .ssh/authorized_keys and attached to your SSH key. This means that the target upload directory depends on the key. Therefore do not run the rsync command manually for testing. If you have another SSH key that you usually use to connect to the LIRIS server, and this key gets used for the connection, rsync won’t be redirected to the desired directory and you might wipe your home on the LIRIS server.

Monitoring the deployment #

Once the .gitlab-ci.yml script is installed in your repository, an icon appears after each commit stating whether the deployment tasks ran successfully.

That would be the green circle next to the commit hash in the image above. Clicking this icon allows you to get details on the deployment tasks. Clicking the tasks yields the output log of the corresponding script, and the built site can be browsed or downloaded from the artifacts of the build task.