Setting up a GitLab CI/CD Pipeline for Deployment to Synology NAS Link to heading

Introduction Link to heading

When deploying a Hugo static website via GitLab’s CI/CD to a Synology NAS, challenges can arise. This post delves into setting up the pipeline, troubleshooting, and, ultimately, successfully deploying the site.

Initial Setup Link to heading

  • GitLab Runner Configuration: Our journey began with setting up the GitLab Runner. For CI/CD pipelines to run, a runner must be assigned to the specific pipeline. Using shared runners is a simpler way to get started, but specific runners can offer more control.

  • .gitlab-ci.yml Configuration: This file defines the pipeline’s behavior. We initially set it to use the klakegg/hugo:latest image to build the Hugo site and then attempt a deploy to a local network location.

Challenges and Solutions Link to heading

  • Docker Permissions: Docker can require sudo permissions to run containers, leading to the error message about the Docker daemon socket. The solution was to adjust Docker group permissions or change the runner configuration.

  • Runner Configuration and Version Issues: Our runner wasn’t using the Docker executor, and the URL was defaulting to gitlab.example.com. After adjusting the runner’s config.toml file and ensuring we had the latest runner version, these issues were resolved.

  • Disk Space & Helper Images: A common error with GitLab Runner and Docker is the runner trying to fetch gitlab-runner-helper images. If disk space is limited, pulling images can fail. Ensuring adequate disk space and the correct runner version is essential.

  • Hugo Image Troubles: We faced a hurdle with the klakegg/hugo:extended image not being recognized. Switching to klakegg/hugo:ext-ubuntu resolved this.

  • DNS and Domain Resolution: The runner kept defaulting to gitlab.example.com. By adjusting DNS settings and ensuring the runner’s configuration pointed to the correct GitLab instance, we overcame this.

  • Deployment to Synology NAS: This was a significant challenge. Initially, the net use command for SMB wasn’t recognized. Trying to use CIFS led to “Operation not supported” errors. Eventually, the focus shifted to NFS.

  • NFS Configuration: NFS required specific services and settings on both the runner side and the Synology NAS. After installing necessary NFS packages, starting services, and configuring Synology to accept NFS connections from the runner’s IP, the deployment succeeded.

Key Takeaways Link to heading

  • Understand the Tools: Grasping how GitLab runners, Docker, and Synology NAS work is vital. Each has its quirks and requirements.

  • Logs are Vital: Many of the challenges were uncovered by carefully reading error messages and logs.

  • Synology Settings: If deploying to Synology, understand its security and network settings. In our case, adjusting NFS permissions on Synology was the final step to success.

  • Stay Updated: Ensure tools and software are up-to-date. Outdated versions can lead to unexpected errors.

Conclusion Link to heading

Setting up a CI/CD pipeline, especially one that interfaces with hardware like a Synology NAS, can be challenging. However, with persistence, knowledge, and a systematic approach to troubleshooting, success is achievable. Whether you’re deploying a Hugo site or another application, the principles remain: understand your tools, pay attention to details, and never stop learning.