Installing the Gitea code hosting solution on a Synology Array using Docker and the Gitea Rootless container image.
Running Gitea on Synology Arrays
I continue to find that my Synology NAS arrays are the most versatile devices in my home lab. I run many small “helper” services on my arrays through the use of the Docker service built into the 6.x and 7.x releases of the Synology DSM. What are these helper services that I am running? Things like “Grafana”, “Prometheus”, “Minio” and the topic for discussion today “Gitea”.
What is Gitea? From their website it is “Gitea is a community managed lightweight code hosting solution written in Go.” You can think of Gitea as a self hosted GitHub or GitLab service. Gitea is written in Go, and it can run on Windows, macOS, and Linux on both x86 and ARM platforms making it a very versatile application. It can also run without the need for an external database server such as MySQL or Postgres by leveraging SQLite. If you are planning to deploy a large Git hosting solution, you should probably look to use one of these more versatile database servers, but for a small home lab, using the SQLite will work just fine.
Why run your own Git server you might be asking? Well, there are three main reasons from my point of view:
Git was designed to be a distributed source control system… however what we have in place today is all Open Source code is consolidated into one of two places, GitHub and GitLab. Running Git in your own environment helps to minimize this code consolidation
Sometimes you need to have a local service for testing code/integrations that you don’t want to have out in the public. By running an internal code repository you can ensure that the code stored in it is private.
Creating a local mirror so your code doesn’t just exist in a “Cloud Service” like GitHub or GitLab as a backup
I am planning to start doing more Infrastructure as code in the future, and having the code internal to my network will be key to getting things set up.
We will be installing the “rootless” version of Gitea. By using the rootless version we are deploying a more secure version of Gitea, which does not run as a privileged user, thus narrowing the attack surface. If you want to learn more about running rootless containers be sure to check out Boosting Container Security with Rootless Containers.
This blog article will assume that you have already set up your Synology device and are familiar with how to move around in the UI. In addition the following additional requirements exist:
You have access to your DNS server and can create DNS records
Create a git user on Synology
The first step we will need to take is to create the “git” user. This user will be used to run the Gitea service and will own all the files on the Synology. You can call the account anything you want, however if you change the name from “git” you will need to update the commands to use the proper name later in the instructions.
Log into Synology
Select Control Panel
Select Users & Groups
Create New User called “git”
Set a password, or use a randomly generated one, click Next
Ensure that it is only part of the “Users” group and click Next
Leave Settings for “Folder Permissions”, “User Quota”, “Application permissions”, and “User speed limit” at default
When we configure our Docker container we are going to need to pass in the UID/GID for the “git” user. This is not available in the DSM UI, so we will need to ssh to the Synology.
ssh <admin user>@<synology ip address>
run id git
In the example above the uid is 1027 and the gid is 100. We will need this information in the Deploy Gitea with Docker section below.
Since we are already logged into the Synology array over ssh, lets create the directory structure for deploying Gitea. The commands below will assume that you have a central location that you store all Docker containers data. In the example below this will be /volume1/docker. We will create a gitea/config and gitea/data directory structure and ensure that the git user is the only account with directory permissions.
We will now use the Reverse Proxy service built into Synology DSM which will allow us to have a vanity url for our service (such as git.example.com). We can also rely on the TLS certificate built into the Synology to host the application over HTTPS.
NOTE: This step is optional, but will make accessing Gitea easier to access.
Log into Synology
Select Control Panel -> Login Portal -> Advanced
Select “Reverse Proxy”
Give it a name “Gitea”
Set source protocol to HTTPS
Set host name to git.
Set port to 443
Set destination protocol to HTTP
Set hostname to localhost
Set port to 3030
Note: You will need to update your DNS to properly resolve git.<your domain>.com for the reverse proxy to work. This activity is left up to the reader based on your own processes.
Deploy Gitea with Docker
We can now deploy Gitea to our Synology using Docker. Due to the limitations of the Synology Docker UI we have to do this from the command line.
Note: be sure to update the USER, USER_ID, USER_GID as well as the volume paths to match your environment needs.
Check to ensure that the Gitea container has started:
$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
858f6680ca77 gitea/gitea:1.17.3-rootless "/usr/local/bin/dock…"19 hours ago Up 19 hours 0.0.0.0:3022->2222/tcp, 0.0.0.0:3030->3000/tcp gitea
Expand the “Administrator Account Settings” section
Create an Administration user
Click Install Gitea
Note: If you are using the Reverse Proxy setup once Gitea configuration completes, you may get an error page from the synology. Click refresh and the site should load correctly.
Validate Your Install
With your Gitea instance configured and running, its time to test it out.
Configure your Profile
Select your profile Avatar in the upper right-hand corner and select “Settings”.
We are going to validate that commits via SSH work, so select the SSH/GPG Keys tab, and click Add Key.
Add your SSH key and click “Add Key”
You can also check and change other setting in your profile as you need.
Create new Repo and Test Commit
Using the “+” sign in the upper right hand corner create a “New Repository”. Give your repository a name (eg. myfirstrepo) and click Create Repository. Follow the instructions for “Creating a new repository on the command line” to validate that your ssh key is working and that you can commit code to your repository.
Maintaining your Gitea Instance
Upgrading your instance
You should ensure that you keep your Gitea instance up to date. Upgrading your Gitea instance can be completed with the following steps:
Log into the DSM Gui
Open the Docker Application
Stop the gitea container
select Actions->Delete Container and delete the Gitea container
(don’t panic, all your data is safe)
SSH to your array
Run the docker deployment command from the Deploy Gitea with Docker section above making sure to update the container image version (eg. gitea:1.17.3-rootless)
Connect to your Gitea instance, you are now running an upgraded version
Note: Make sure you continue to use the “rootless” version. If you change to the non-rootless version your deployment will not work.
Running a private Git service can be easily achieved with the use of Synology DSM, Docker and the Gitea rootless container. From here you can start adding integrations such as Drone, or Jenkins. You can also configure Gitea to mirror other Git repos from places like GitLab or GitHub. You can configure Gitea to pull from other repos or push to those repos.
One final note. Be sure you are also backing up your config and data directories if your Synology is the only place your code resides. Happy “git-ing”