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.

Pre Steps

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:

• Synology DSM 6.x or 7.x
• Install the Docker Package
• Enable SSH Access
• You have Administrator privileges on the system
• 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.

1. Log into Synology
2. Select Control Panel
3. Select Users & Groups
4. Create New User called “git”
5. Set a password, or use a randomly generated one, click Next
6. Ensure that it is only part of the “Users” group and click Next
7. Leave Settings for “Folder Permissions”, “User Quota”, “Application permissions”, and “User speed limit” at default
8. Click Done

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.

1. ssh <admin user>@<synology ip address>
2. 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.

Create Filesystem

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.

$ sudo mkdir -m700 {/volume1/docker/gitea,/volume1/docker/gitea/data,/volume1/docker/gitea/config}
$ sudo chown -R git:users /volume1/docker/gitea

Create Reverse Proxy

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.

1. Log into Synology
2. Select Control Panel -> Login Portal -> Advanced
3. Select “Reverse Proxy”
4. Click Create
5. Give it a name “Gitea”
6. Set source protocol to HTTPS
7. Set host name to git.
8. Set port to 443
9. Set destination protocol to HTTP
10. Set hostname to localhost
11. Set port to 3030
12. Click Save

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.

$ ssh admin@<synology>
$ sudo docker run -d --name=gitea \
  -p 3030:3000 \
  -p 3022:2222 \
  -e USER='git' \
  -e USER_UID='1027' \
  -e USER_GID='100' \
  -v /volume1/docker/gitea/data:/var/lib/gitea \
  -v /volume1/docker/gitea/config:/etc/gitea \
  --restart always \
  --user="1027:100" \
  gitea/gitea:1.17.3-rootless

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

Configure Gitea from UI:

With the Gitea URL that you created in the Create Reverse Proxy section:

1. Browse to the URL (eg. https://git.example.com)
2. If prompted for an unsigned certificate, accept the security risk to continue
3. Configure settings as required. You should ensure that the following settings are updates:
   • Site Title
   • server domain (eg. git.example.com)
   • base url (eg. https://git.example.com/)
   • SSH Server Port - this should be set to “3022”
4. Expand the “Administrator Account Settings” section
5. Create an Administration user
6. 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

1. Select your profile Avatar in the upper right-hand corner and select “Settings”.
2. We are going to validate that commits via SSH work, so select the SSH/GPG Keys tab, and click Add Key.
3. 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:

1. Log into the DSM Gui
2. Open the Docker Application
3. Stop the gitea container
4. select Actions->Delete Container and delete the Gitea container (don’t panic, all your data is safe)
5. SSH to your array
6. 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)
7. 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.

Conclusion

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”

• synology
• git
• gitea
• S3