Gitlab on QNAP NAS (Installation & Basic Usage)

System: QNAP TS451D2 with sufficient hard disk storage.

Present Firmware is 4.5.4.1787 (09.10.2021)

Few updates foreseen for QTS 5.1.3.2578 (sorry for being lazy to update). Note some settings might have a diffent look vs. 4.5.4 but I hope most was not changed too drastically.

Notes:

• If not present on your QNAP NAS, install Container Station.
• There's a gitlab installation available in Container Station. This one is not used (Instead a gitlab docker image will be installed).
• Git must be installed on the (mainly Windows / Linux) client PC.
• Remind gitlab V14 and above use main, before it was master branch.
• Some wide images are incorrectly scaled in width, so information seems to be lost when viewing on a browser. The correct view is possible by just clicking those images.

The 1st requirement: your QNAP needs lots of RAM. QNAP / Intel claim the processor used in the T451D2 supports maximal 8G RAM. I inserted 2x Kingston KCP426SS8/8 to replace the single Adata 4Gby RAM module. As the above screenshot shows: the NAS reports (and uses) 16Gby RAM. Probably the installed gitlab edition works with 3-6Gby if only a few / single user access it. However, that would result an 8Gby equipped QNAP NAS has (nearly) no free RAM as the NAS requires about 2Gby for its other tasks.

The 2nd requirement on the NAS is Container Station. Install if not present.

Note QNAP container station has a gitlab version pre-installed. I did not install because it's an older version (V11 or so) vs. the docker images (V14). The pre-installed version also requires 3 'runners' instead of one.

• Open a Web Browser and log in to your QNAP NAS using an administrator account.
• Start Container Station.
• Click on Images as visible in the above screenshot.
• On the top, there's a search-bar. Search for gitlab/gitlab-ee (as can be seen in above screenshot).
• Pull the gitlab image (this is a few Gbytes in size, so it will take some time to download). When ready, the gitlab image is shown (visible in the bottom line of above image).
• There are 2 versions of docker gitlab images:
• gitlab-EE: enterprise edition
• gitlab-CE: community edition

The file size of both variants is about the same. Some things are explained to be easier on the EE, reason why I use this one. But the setup of both is identical, so one is free to select the one of interest.

While waiting for the download, create a shared folder (ex. gitlab) and create 3 sub-directories in it (ex. etc, var and log; in etc, gitlab configuration is stored while var holds the data). One can also consider to create 3 different shared directories: a personal preference. Make sure administrator has only read/write access to this gitlab folder (and all folders created inside of it). Note if one does not want to store the data outside the container storage, this step may be skipped.

Note: if the above isn't working, try the following using docker command line on the NAS.

• Make sure you have an account on docker hub (https://hub.docker.com/)

• SSH login to your NAS using admistrator account. From Windows, I recommend to use MobaXterm. If you never used it before:
  • Create SSH session.
  • For remote host, provide the IP Address from the NAS.
  • Click Specify username and provide an administrator account name
  • Leave Port at 22.
  • Log in using this session on the NAS. MobaXterm will request for the login credentials.

  From Linux, one typically logs in using command line ssh. Type in a terminal -for example- ssh admin@192.168.1.40 if your NAS is on that IP address and you use admin account name.
  

• If successful, this opened a command line terminal as if you run it directly on the NAS. There you type:
• docker login
• Provide the username and password from your docker hub account. Next execute on the NAS command line:
• docker pull gitlab/gitlab-ce
• (or docker pull gitlab/gitlab-ee depending on the version you want to use). Your NAS will now download the image and when ready, it becomes visible in Container Station. Once the download is completed, one can delete / export the image from container station.

Select the gitlab image and click the + button to start the container creation.

The initial window that opens when creating the container is shown above. The name can be changed to anything (that is accepted by container station).

Some notes / tips:

• I don't start the container automatic after power on:
  • I prefer to shut down gitlab before the NAS is turned off. Should the gitlab container start automatically I might forget to shut it down when I turn off the NAS manually. More info how to shut down gitlab can be found later.
  • gitlab may use considerable CPU resources, even when nobody uses it.
  • The disks never seem to sleep when gitlab is running, so power consumption and disk wear will also be negatively affected if gitlab runs all the time..
  • As a hobbyist, I don't use gitlab every time I start the NAS.
• I limit CPU use to 75%.
• Memory is limit to 8192Mbyte (8G).
• Click Advanced Settings.

In the Advanced Setup tabs, select Network.

It's recommended to fill in the ports (above screenshot shows possible values). I recommend to add a large offset to the port numbers: that's easier to remember (in this example, 20000 was added to each host port). These ports will be used by your Windows/Linux client to communicate with the gitlab server.

Based on some web-searches: port 80 is used for the web-interface, port 22 for the shell (git command line on your client PC) and 443 is used by pages/registry. A web access to the gitlab server using above settling would require this URL in your browser: https://yourNasIPAddress:webPort. For example: 192.168.40.40:20080.

Don't forget gitlab server credentials are stored on the client PC in a file called known_hosts (located .ssh directory of your home drive). I noticed if the ports are not filled in manually, the gitlab runner may use different ports each re-start. This is somewhat troublesome as the origin in your gitlab manage project must be updated in such case.

In one of the first steps, I recommended to create 3 folders for gitlab storage. As shown in above image, the gitlab container creator proposes 3 directories as mount points for data, settling & logs. First time, one may consider to leave these entries open. In that case, the container creator will store this data somewhere in the "container storage dungeons".

Instead, I prefer to know where the gitlab data is stored (= outside the container storage). As shown in above screenshot:

- Press "Add" above the "Volume from Host" row. Then select the 3 directories (etc, log and var) for gitlab, and redirect to identical mount points that are about to be deleted (I postpone the deletion of these 3 predefined mount points since I use copy/paste in the browser to make sure the newly created mount points are correct).

- When the 3 'outside container storage' locations are filled in, delete the 3 predefined mount points.

Now one can press the Create button. This takes +10 minutes to complete the first time.

One has to remind the gitlab runner runs with administrator account. Reason why I provided write permission to the above 3 directories (and excluded from access by all other users). My administrator account is disabled for login. As a result, I have no access to the gitlab directories unless I first re-enable briefly my admin account for login during the time I want access. But it's also safe to prevent accidental data corruption by users since they cannot access the gitlab directories from outside the NAS).

[Update] New view Container Station | Use the gear tooth wheel to start the container.

When the container is ready, this is visible in 2 ways:

• Next to the name, a link icon appears that directs your browser to the gitlab web-interface.
• Click on the docker container name, and the terminal view opens. This shows the complete URL.

The first time, I was unable to determine the default gitlab root password (remind I have disabled my administrator account as explained in previous step). There's a initial root password file in /etc (but one needs to be NAS administor to access and connect using SSH, as explained in step 2). One may briefly re-enable the QNAP administrator account & use SSH, but my work-around was to force a new gitlab root password:

• Click on the Container Station specific for the gitlab runner on Terminal button (or icon).See above screenshot on the right hand side: the ">" icon.
• Type /bin/bash in the displayed text box.
• A new browser window (tab) opens with a root terminal interface for your gitlab runner on the NAS.
• Type in this root terminal window:
• gitlab-rake "gitlab:password:reset[root]"
• (including the quotes). After some time, gitlab will request a new root password and confirmation. Now one can log into the gitlab runner for the first time.

Above window shows the 2nd option to find the gitlab weblink and access to the gitlab container command line terminal. Remind this is the IP address of your NAS followed by a double point and the redirected port 80 (from the initialization).

Note:

Container Station has a nice feature to export the image you just downloaded. This may be useful if you want to port the identical gitlab image to another NAS / back it up. Click on the middle of the left hand side "Export". At the top right click on the button "+ Export Image". On the dropdown list, select your image you want to export. Provide a file name and select the location. It makes sense to enable compression (for gitlab the typical compression ration is about 50%, so one saves about 1Gbyte of storage). Taken the images size into account, the export will take some time to complete.

• The gitlab root user can create additional user(s).
• A unique SSH key must be generated for each user (recommended is to use an ED25519 key as RSA is often no longer accepted / considered safe). The SSH key is formatted as something shown above.
• On a Linux machine use ssh-keygen -t ed25519 -C "your_email@example.com". On Windows, one may try something like PuttyGen but I prefer Linux machines for this step.
• When the SSH key was created with a passphrase, that passphrase must be provided every time the client PC uses the key the 1st time of the session. This is considered safer, but don't forget the extra hassle every start.
• On a Windows PC, the SSH key must be stored in this file
• %UserProfile%\.ssh\id_ed25519.pub
• On an Ubunty Linux PC it's something like this:
• ~/.ssh/id_ed25519.pub
• If one has multiple computers, the easiest solution may be to use the same SSH key for all computers. But one may also generate one unique SSH key for each computer. This is somewhat more work during setup, but when a specific computer / SSH key must be removed this is easier later on..

One may create Template / empty project(s) for the specific user. Default gitlab will use your user name to store projects, but I typically create groups to distinguish projects better (like AVR, STM32, C, Cpp, CS, VB and so on). This is also a personal preference and certainly when a user is allowed to host the project, this can be moved later on.

To clone a project, open a git bash in the project target directory on the client PC. The following is tested on Windows 10 but the command line interface is probably identical with Linux:

• git clone ssh://git@NAS_IP_ADDRESS:PORT/yourgitaccount-group/test.git

The first time one connects to the QNAP gitlab runner, an additional message may appear on the client "add to known hosts". Confirm with typing yes and press <Enter>. In this case, the host information is added to the known_hosts file located in the.ssh directory of your client computers' home drive. Remind if something gets changed in your installation, that known-host question pops up again. It's not a bad idea to clean out the known_hosts file from time to time if one makes a lot of changes in the network configuration.

Clone Example:

• git clone ssh://git@192.168.40.40:20022/myGitGroup/myGitTest.git

Since gitlab restricts user access to projects, make sure you have the proper access (otherwise one will get a message the repository doesn't exist or cannot be accessed). Note the gitlab interface uses port 22 for cloning and we use the redirected port instead.

For users not familiar with git:

• Easiest is to create the project first on gitlab web interface.
• Clone the project to your client PC (see previous step).
• Create a branch name (this shouldn't exist in that project at this time):
• git checkout -b myNewBranchName
• For people more familiar with CVS/SVN: git checkout changes between branches, it doesn't check out the repository (in git, that's called cloning).
• Create / copy / move files to the repository.
• Repeat below git add till all files you want to commit are included; wildcards may be used).
• git add myFile.extension
• Use git status to check if all files one wants to include in the repository are in.Git status flags these files in green. Files ignored / not committed ("untracked") are reported in red. Use a .gitignore file to hide files in git status.
• git differs from CVS that a local commit is performed first. Below -am option requires an additional commit description (put between quotes):
• git commit -am 'my Commit Description'
• At this time, the client PC has a newer version, but it's not known to the remote gitlab server yet. In order to do that, you'll have to push the local repository:
• git push origin myNewBranchName or git push origin HEAD if the actual branch is also the HEAD.
• Make sure the branch name used matches your previous created branch name. If you get error messages here and you have no idea I recommend web searches to resolve the issue(s) before one can continue.
• Your git command line terminal on the client PC now shows a link where the merge request can be handled in a web browser. Since your browser may not be aware of the gitlab runner, this may not work. Easiest is to open the gitlab runner link from the QNAP Container (see previous steps).
• Browse to the project you just pushed (if you know for sure gitlab is running, that is the IP address of your QNAP NAS followed by double point and the host port that routes to port 80 (in this example 20080)).
• As shown in top of above image, the project now has a button Create Merge Request.
• When pressed, the next screen in your browser has the option to Approve the changes. In case of multiple users, one may also assign the merge request to another user so (s)he reviews the changes (I consider this one of the major git advantages). Merge requests also allow to provide additional comments (it's a good practice to add all related information).
• gitlab now performs a check if the merge can be performed. This may take considerable time since the NAS has only limited computing power.
• Press the Merge button when it becomes available in the web interface (or fix the merge conflicts. In you don't know what to do, a web search is recommended to fix issues; sometimes git(lab) may give reasonable good instructions what to do to resolve the problem but this is certainly not always true).
• One has to remind the gitlab main repository is at this time 'one step ahead' vs. the local PC main repository. To keep things clean, I typically perform the following actions on the client PC (in the git bash terminal):
• git checkout main This reverts back to the last known local main status. So if you added files in the latest commit, these files are removed. If the merge was a success, nothing to worry since this confirms the local main leaps behind vs. the remote main (the git checkout main reverted back to the local main).
• git pull updates the local main with the remote main. Files previously removed are restored (this confirms the local main was updated to the status of the remote one).
• If you no longer need the branch name, you can delete it using git branch -D myNewBranchName I tend to preserve all branches and use new ones every time I modify the code.

Before shutting down the QNAP NAS,

Log off from all gitlab web interfaces.

Now open the Container Station gitlab runner (via terminal as mentioned above) /bin/bash.

[Update] screenshot shows how to open a shell via "Execute" option. Select "/bin/bash" and press Execute.

Type in this window:

gitlab-ctl stop

Observe the terminal in the Container Station till it reports it has stopped. This doesn't take long.

It's now safe to shut down Container Station and the NAS. Without proper shutdown, gitlab seems to perform some sanity check the next time it gets started: this may require a considerable amount of additional time.

Note: in the new container station, above user interface has changed.

• Click in container station on the left tab "Containers". There one will see gitlab-ee. Click on the name (it's displayed as a link).
• On the top, an "Execute" button appears in the overview.
• Select /bin/bash and execute it.
• Now one can stop gitlab as described above.

If one installs Windows winmerge, one may add the following in the .gitconfig file located in your home drive (If git is already configured, this file contains your email & user name). Winmerge is a far better tool for comparing source code and since quite some time it's completely updated for use with git. Add all bold statements:

[diff]

tool = winmerge

[difftool "winmerge"]

cmd = "'C:/Program Files/WinMerge/WinMergeU.exe'" -e "$LOCAL" "$REMOTE"

[core]

longpaths = true [credential]

helper = manager-core

[mergetool]

prompt = false

keepBackup = false keepTemporaries = false

[merge]

tool = winmerge

[mergetool "winmerge"]

name = WinMerge

trustExitCode = true

cmd = "/c/Program\\ Files/WinMerge/WinMergeU.exe" -u -e -dl \"Local\" -dr \"Remote\" $LOCAL $REMOTE $MERGED

[diff]

tool = winmerge

[difftool "winmerge"]

name = WinMerge

trustExitCode = true

cmd = "/c/Program\\ Files/WinMerge/WinMergeU.exe" -u -e $LOCAL $REMOTE