There are lots of complicated ways to install a local GitLab instance, however for small environments it is easiest to simply use the supplied container image. Instructions on installing that are at https://docs.gitlab.com/omnibus/docker/ and are simple to follow.
Install, start, configure
For my home lab environment installing the GitLab container was simply a case of
- create a new KVM based on CentOS-8 with 4Gb of memory, 2 vcpus, and a 50Gb qcow2 disk
- install docker
dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo dnf list docker-ce dnf install docker-ce --nobest usermod -aG docker root usermod -aG docker mark systemctl enable docker systemctl start docker
- in /etc/profile add the required ‘export GITLAB_HOME=”/srv”‘ line (it does not have to be in the global profile but I did not want to have to add it in multiple places)
- docker pull gitlab/gitlab-ce:latest
- start it
docker run --detach \ --hostname gitlab-local.xxx.xxx.org \ --publish 443:443 --publish 80:80 --publish 5522:22 \ --name gitlab \ --restart always \ --volume $GITLAB_HOME/gitlab/config:/etc/gitlab:Z \ --volume $GITLAB_HOME/gitlab/logs:/var/log/gitlab:Z \ --volume $GITLAB_HOME/gitlab/data:/var/opt/gitlab:Z \ gitlab/gitlab-ce:latest
note that I use port 5522 for ssh as the server running the container is already using port 22 for it’s ssh server, also the :Z appended to the volume lines are because selinux is on my server
Then point a web browser at the ip-address of the server (http://xxx.xxx.xxx.xxx rather than https) and using the userid root create a new password for the GitLab root user. At that point you can configure a few of the options, such as not letting new users create their own accounts.
Create a normal non-admin user, and setup ssh keys
You will then want to create a non-root/non-admin user for day to day use for your projects.
When defining a new user GitLab wants to send an email to the new user to allow them to create their new password, by default the GitLab container does not support outbound email. If that is an issue for you documentation on setting up email is at https://docs.gitlab.com/omnibus/settings/smtp.html#example-configuration, however it is not required (see next paragraph).
After defining a new user you just “edit” the user, which allows you to set an initial password for the user, when they use it at first logon they are required to change it; so having email is not actually required to define a new user. If you are going to run the container in your home lab you probably do not want emails out of GitLab enabled anyway.
Once done log out from the root user.
Setup a ssh key for the new user, fully documented at https://docs.gitlab.com/ee/ssh/, but briefly covered in the following paragraphs.
Logon to the GitLab interface using the new user you created using the password set when you edited the user above. You will be required to change the password, and then logon again with the new password.
Once logged on go to the user settings and select ssh keys.
On a terminal window on your Linux development desktop use ssh-keygen -t ed25519 -C “some meaningful comment” to create a new ssh key, note that I changed the name of the default file when prompted from id_ed25519 to id_ed25519_local_gitlab so I can clearly identify it, this raises issues also covered below.
Once you have generated the key done copy the contents of the .pub file created for the key to your clipboard.
Paste the ssh key in your clipboard into the ‘Key’ field provided, give it a meaningfull title and add the new key.
Back in the terminal window test the key works with “ssh -T git@xxx.xxx.xxx.xxx”, or in my case as I mapped port 5522 “ssh -p 5522 -T git@xxx.xxx.xxx.xxx”; reply yes to accept the fingerprint; you should see a ‘Welcome to GitLab @username!’ message before being returned to your own hosts shell. Repeat to ensure the fingerprint has been accepted and prompts will not interfere with workflow anymore.
For those used to using ssh to jump around machines it is worth pointing out that the command is in fact git@xxx.xxx.xxx.xxx and not the username of the GitLab account; that can be confusing at a first glance but the userid used must be git, and it magicaly determines what username to map to based on the key used.
It should also be noted that by default one of the key files ssh looks for is ~/.ssh/id_ed25519 whch is the default filename used when generating the key. If like me you have many idendity key files discretely seperated the command for me is “ssh -p 5522 -i ~/.ssh/id_ed25519_local_gitlab -T git@xxx.xxx.xxx.xxx” to select the key I want to use.
Create a project as the new user
While logged on as the newly created user you may want to create groups, but if it is for a home lab environment you probably want to jump directly to starting a new project.
The main reason new users should create a new project via the browser interface is that when a new project is created a ‘help page’ for the new project is displayed showing the git commands needed to setup the git environment and create a new local repository on your development desktop by cloning the new empty project or pushing an existing git repository to your new project. It does assume you are using default ssh identity files however.
Workarounds needed for using a container
The documentation recomends mapping port 22:22 which if used means the host running the container would have to provide ssh services on another port; to me that is silly. So as noted in my example of running the container above I mapped 5522:22 so the host running the container can still provide normal ssh services on port 22. It does mean port 5522 (or whatever port you chose) needs to be opened in your firewall).
If you need to use git with multiple ssh identity files as I do there are a few interesting answers at https://superuser.com/questions/232373/how-to-tell-git-which-private-key-to-use.
I prefer the use of ~/.ssh/config myself to provide different keys to different hosts as that also allows the port to be changed. It does mean you need a seperate dns entry for the hostname and gitlab-hostname as you only want to switch ports when accesing the GitLab ssh port and not interfere with the host running the container providing its normal ssh service on port 22.
Assuming a /etc/hosts file entry as below (or dns entry where both hosts map to the same ip-address)
xxx.xxx.xxx.xxx gitlab-local.xxx.xxx.org realservername.xxx.xxx.org
Using the below example of a ~/.ssh/config file any ssh to gitlab-local.xxx.xxx.org will use the specified key in the users .ssh directory instead of the default plus use port 5522 to connect to the remote hosts ssh service. And ssh to any other host (including realservername.xxx.xxx.org) will (as no overrides have been added for the ‘host *’ catch-all entry) use the normal port and all default ssh parameters.
Host gitlab-local.xxx.xxx.org IdentityFile ~/.ssh/id_ed25519_local_gitlab Port 5522 Host *
Actually using your project from the standard git command line
Then on your development server to push files you are already working on to the project you created earlier is simply a case of following the git instructions that were shown on the web page displayed when your project was created (obviously it would be easier if you added a hostname to your /etc/hosts or dns rather than use the ip-address, but either work).
cd existing_folder git init git remote add origin git@xxx.xxxx.xxxx.xxxx:user_name_you_created/project_name_you_created.git git add . git commit -m "Initial commit" git push -u origin master
And your Gitlab browser interface will show the files are in the project now.
To use any of the devops features you will need a bit more work, but for simply installing a local git based software repository users can work on that’s all that is needed.
So excluding the time it takes to download a CentOS-8 install iso, it takes less than 15mins to create a new CentOS-8 VM (remember to asign a static ip-addr), and about another 15mins to get it all working; so give it a try.
