My recent blog post on setting up a custom vSphere Content Library on my Synology gave me another idea that I had been thinking about regarding Project Keswick, which was announced back at VMware Explore Las Vegas.
If you have network connectivity to the Keswick Cloud Service, you can easily associate a Git repository, which is used for host configurations and workload deployments using GitOps using Github or even a privately managed Gitlab instance. For organizations that have additional compliance, security or air-gapped requirements, using the Keswick Cloud Service may not be an option. With that said, Project Keswick also supports an advanced deployment option where the association of a Git repository, such as GitLab, can also be accomplished without requiring the use of the Keswick Cloud Service.
While I have had experience using both Github as well as GitLab, which VMware uses to host its own code repository, I have actually never setup my own GitLab instance before. I thought this would be a great learning opportunity, especially with the ability to run additional add-on applications on a Synology.
After a bit of researching online, I found that GitLab can easily run as a Container workload and it just so happens that the Synology DiskStation Manager (DSM) has a package for running containers creatively called Container Manager and below are the step by step instructions for setting up GitLab running on Synology DSM 7.2.
Step 1 - Login to the Synology DiskStation Manager (DSM) and open up the Package Center on the desktop. Search for the Container Manager application and initiate the installation.
Step 2 - On the DSM desktop, navigate to File Station and create a new directory that will be used to store our persisted GitLab configuration files. In this example, I named the folder gitlab.
Step 3 - Next, open the Container Manager and click on the Registry tab to download the latest GitLab Enterprise Edition container image. Search for gitlab/gitlab-ee in the search box and which should automatically find our desired package and then click on the download button.
Step 4 - Once the download has completed, which can take a couple of minutes, click on the Container tab to deploy an instance of the container. Select the container image which was downloaded from Step 3 and then provide a name.
Next, we need to map the external ports that we will use to connect to the GitLab instance via our Synology endpoint to the internal container ports as well as the folder mapping to the GitLab configuration files. Below are the configurations for my setup and we will connect to the GitLab instance on port 8080:
- 2222->22->TCP
- 8443->443->TCP
- 8080->80->TCP
- /gitlab/data -> /var/opt/gitlab
- /gitlab/logs -> /var/log/gitlab
- /gitlab/config -> /etc/gitlab
Step 5 - We are now ready to start up our GitLab container and this will take a few minutes to fully initialize.
To verify that everything is working, you should be able to open a browser to the FQDN or IP Address of your Synology on port 8080 and you should eventually see the GitLab login page.
Step 6 - By default, a random root password is generated for the GitLab container image as part of the setup and it will be deleted after 24 hrs. We need to retrieve the initial root password, so we can login to the GitLab instance to change the password.
To do this, we need to run a command inside the container to retrieve the password and the easiest way is to do this by SSH'ing to your Synology. If you do not have SSH enabled, navigate to the Control Panel->Security->Terminal & SNMP and selecting the Enable SSH Service and click on the apply button for change to go into effect.
Once logged in, run the following command (replace gitlab-gitlab-ee-1 with the label you had named your GitLab container instance):
sudo docker exec -it gitlab-gitlab-ee-1 grep 'Password:' /etc/gitlab/initial_root_password
This will output the current root password which you can then use to login to your GitLab instance with username "root" and the password provided in the output above.
Step 7 - Finally, to change the default root password, go to the Admin Area->Users and select the root user and change the password
At this point, you have successfully deployed a private instance of GitLab running as a Docker container on your Synology! 🥳
If you are interested in using your newly deployed GitLab instance with Project Keswick, the remainder of the of instructions will walk you through the required configurations.
Step 8 - Create a new GitLab project that will be used as the repository that your Keswick host will be associated with.
Step 9 - We now need to request a deploy token from our repository, which will be used by the Keswick host to watch for workload deployment and host configuration files. Click on Settings and then click on Repository and expand the Deploy Tokens section to request a token. Only the read_repository scope is required and provide a token name (optional) or make a note of the default token name as that will be required when updating our Keswick ESXi Kickstart deployment configuration file.
Once the token has been created, you will be shown the deployment token string, make a note of the value.
Step 10 - At this point, you can clone your repo to your local machine and start checking in configuration files that will be consumed by your Keswick host.
Note: I have not figured out how to update GitLab or the Synology settings so that the URL provided for cloning uses the Synology FQDN/IP Address rather than just the container name. If anyone happens to know how to change this, please let me know by leaving a comment. You will need to replace the URL shown in the repo page with the Synology FQDN/IP Address which in my example would be http://nas.primp-industries.local:8080/lamw/keswick-nuc13.git (note that this is using HTTP and NOT HTTPS)
Step 11 - Next, sign up and register for a free Project Keswick account if you have not already, which is required to download the Keswick software. Download the Keswick Image, which is available in three different formats:
- ISO - Use this image if you will be booting from a physical/virtual CD-ROM including the use of out-of-band management like BMC/iDRAC/iLO
- OVA - If you do not have physical hardware to try out Project Keswick, you can use the OVA which is a Nested ESXi VM that contains the Keswick image and you can deploy that to vSphere, Workstation or Fusion for testing purposes.
- IMG - Use this image if you will be booting from a USB device
Note: I accidentally made the mistake of assuming the ISO image could also be used to create a bootable USB device as I typically use Unetbootin, which is a multi-platform utility for creating bootable live-CD on USB. If you use the ISO image, the ESXi installer is expecting the embedded ESXi Kickstart to be loaded from CD-ROM rather than USB, which is what the USB image is configured with. If you are familiar with ESXi Kickstart, it is a quick change to efi/boot/boot.cfg file on the USB device or you can simply download the correct image and then create the bootable USB device following directions HERE.
Step 11 - We need to adjust the default KS.CFG, which is located in the root of the USB device and uncomment the following section as shown in the screenshot below and add our deploy token details along with the branch name and GitLab repo.
Note: I also recommend changing the default ESXi root password, as it will be helpful to login after the installation to watch the progress of your deployments and/or troubleshoot any issues.
Step 12 - Plug the USB device into your Keswick host and wait for the deployment to complete and then reboot automatically.
For my Keswick workload, I decided to deploy a pretty important application called Mario 🤪
This is actually based on a really slick project that I had first blogged about back in 2021 where you can run Retro DOS Games using Kubernetes (K8s)! The original setup used port forwarding to access the game via a browser, but if you deploy a simple k8s service load balancer like Metallb, then that additional step is not required and can be accessed by others that also have network connectivity to your Keswick host. I've put together all the required k8s manifest in the following repo: https://github.com/lamw/keswick-mario-demo and yes, the order of deployment does matter, so you will need to have multiple git commits to ensure the required k8s resources are realized before deploying the next resource.
I have not figured out how to update GitLab or the Synology settings so that the URL provided for cloning uses the Synology FQDN/IP Address rather than just the container name.////
In order to fix the problem, just change the conifg in gitlab.rb:
find or add a new line like this : external_rul: 'http://your.domain.nam'
Hello and thank you William for this tutorial.
I did the same 6 months ago and it worked fine. I did not take the time to go further to migrate my repositories, so I started again this week with a clean install.
Unfortunately, I get many issues when I applied the same procedure on my Synology DS920+. Once I configure container and launch it, deployement did not proceed correctly. It run during more than 1 hour and it is completely stuck.
How it works 6 months ago, I did not remember which one I used. So I tried with several versions of gitlab-ee container:
- 13.12.9-ee.0 : Deployement works fine
- 14.10.5-ee.0 : Deployement works fine
- 15.11.9-ee.0 : Deployement crash immediatly and container stop.
- latest version (11th of february it is 16.6.7-ee.0) : it proceed during about 25 minutes and deployement stay stuck. GitLab welcome page is not accessible.
Did you observed same issues? On which version did you proceed to realize your tutorial please?
Thank you again.
Hello, thank you William for this tutorial! I followed and it worked for me.
I was trying to test some recovery scenarios, but unfortunately following the gitlab tutorials, it did not work for me (https://docs.gitlab.com/ee/administration/backup_restore/restore_gitlab.html).
How would you do it with the setup you described in this tutorial? Thanks!