I have wanted to set up a Git repository of my own for some time now. Not just for the sake of source code version control, but also for other purposes that I plan to write about on this blog in the future. In this article I will show how to set up a local Git repository using GitLab CE running in Docker and how to set up a user and push a project to the local GitLab instance.
I assume you have the latest version of Docker and Docker Compose installed – if not, use the links below. In addition, I also assume that you have the installed the git command. When writing this article, I used Docker version 18.03.1-ce and Docker Compose version 1.21.2 both running under Ubuntu 18.04.
- Install Docker CE
To upgrade Docker CE, first uninstall the current version you have and then install the latest version.
- Install Docker Compose / Upgrade Docker Compose
- Git can be obtained from this webpage.
- If you want to use SSH to connect to your GitLab instance, you will need SSH keys.
Please refer to this section in the GitLab user guide for information on SSH keys.
In this article I will use only plain HTTP to connect to my GitLab instance, so setting up SSH is not required.
Docker Compose File
I started out creating a Docker Compose file since I want to be able to start GitLab with a simple “docker-compose up”.
# GitLab CE deployment using two external volumes; one for data and another
# for configuration. These volumes needs to be created prior to starting GitLab
# using the following commands:
# docker volume create gitlab-data
# docker volume create gitlab-config
# In addition you may want to change the hostname value in the Docker-Compose
# configuration below to match the name of your server/computer on which
# GitLab is to be run.
# Once started, access GitLab using the URL http://localhost:8880.
# The following ports are exposed by GitLab:
# 8880 (HTTP)
# 443 (if you configure HTTPS)
# 8080 (used by Unicorn)
# 8822 (used by the SSH daemon)
# The GitLab documentation suggests the following line to be added to the
# GITLAB_OMNIBUS_CONFIG environment variable.
# external_url 'http://hostname:8880'
# However, with this line present I am unable to access the GitLab webpage.
gitlab_rails['gitlab_shell_ssh_port'] = 8822
# The logs directory can be mapped to the logs directory in the same director
# as the docker-compose file using the following entry under volumes:
# - ./logs:/var/log/gitlab
- On row 28, change the value to the name of the server/computer on which you will run GitLab.
If you do not have a hostname, leaving the “hostname” value is fine.
- On row 33, change the first “443” to the port on which you want to expose the GitLab HTTPS endpoint.
In this example I use plain HTTP only and thus leave this port unchanged.
- On row 34, change the port number 8880 to the port on which you want to expose the GitLab HTTP endpoint.
I have used 8880, since port 80 is already used on my computer.
- On row 35, change the port number 8822 to the port on which you want to expose the GitLab SSH endpoint.
Port 22 is already used on my computer, so I use port 8822.
If you modify the SSH port number, you also need to modify row 31 so that the port number there match your new port number.
- If you want to map the directory containing the GitLab logs to the host, then create a directory next to your docker-compose.yml file and add the following line after line 41 in the docker-compose.yml file:
- Save any modifications to the docker-compose.yml file.
With the docker-compose.yml file ready and the optional logs-directory created, if desired, we are now ready to run GitLab.
- Open a terminal window.
- Go to the directory containing your docker-compose.yml file.
- Create a Docker volume for the GitLab data using this command:
sudo docker volume create gitlab-data
This is a one-time setup and need not be repeated, as long as you do not delete this Docker volume.
- Create a Docker volume for the GitLab configuration using this command:
sudo docker volume create gitlab-config
This is also a one-time setup and need not be repeated, as long as you do not delete this Docker volume.
- Start GitLab using Docker Compose:
sudo docker-compose -d up
It takes quite some time for GitLab to finish all the setup, so have patience.
- Open this URL in your browser:
- Enter a new password for the root user twice when requested.
- Log in to your GitLab instance using “root” as username and the password you entered in the previous step.
Congratulations, you now have your own instance of GitLab up and running!
Creating a User
Under normal circumstances you only use the root user to administer your GitLab instance and never to push source-code to it. In order to use GitLab as it is usually used, we will now create a new user in GitLab.
- If you are not already logged in to GitLab with your root user, then log in.
- Click the wrench in the menu bar.
This should take you to the Admin Area in GitLab.
- Click the Users item in the Admin Area menu on the left.
- Click the New user button in the upper right corner of the window.
- Fill in at least the required fields with information about the user.
If you want the user to be able to administer GitLab, then select Admin access level, otherwise leave access level at Regular. For the sake of this article, regular access level is enough. Note down the username, since it will come in handy later when you are to log in to GitLab using this user.
- Scroll down and click the Create user button in the lower left corner of the window.
- Click the Users item in the Admin Area menu on the left.
Yes, this is a repetition of an earlier step but it is required.
- Locate the new user in the list of users displayed.
- Click the Edit button on the far right of the line displaying the new user’s name.
- Scroll down to the Passwords section on the user information page.
- Enter a password for the user in the Password field.
Note down the password – it will also come in handy when logging in to GitLab with this user.
- Enter the same password again in the Password confirmation field.
- Scroll down and click the Save changes button.
The GitLab user is now ready and can connect to GitLab using the username and password you have chosen.
Creating and Pushing a Project
The final example describes how to create a project in GitLab and push existing contents to this project.
- Log out of GitLab if you are logged in as root.
- Log in to GitLab with the user you created in the previous section.
- Click the Projects item in the menu and then click Your projects in the sub-menu that appears.
- Click the New project button to the right in the window.
- If it is not already selected, chose to create a blank project.
- Enter a name for the project.
- Click the Create project button.
- Open a terminal window and enter the directory in which the project you want to push to GitLab reside.
If you don’t have a project to experiment with, you can download one of mine here.
In the new project created in GitLab, there are command line instructions telling you how to push your local project to the new project in GitLab.
I am going to modify these slightly, since I am not using my own GitLab instance as the only Git repository.
- Initialize the Git repository using the following command:
- Configure the username and email of the Git user that will push the project using the following commands in the terminal window, replacing “someone” with the name of the user you created and “email@example.com” with the email address of the user:
git config –local user.name “someone”
git config –local user.email “firstname.lastname@example.org”
- On the project-page of the new project in GitLab locate the URL of the project.
In my case, it is: http://localhost/ivan/my-superproject.git
- Set the location of the remote project by issuing this command in the terminal window (replace the URL with your URL from the previous step and add the GitLab HTTP port):
git remote add origin http://localhost:8880/ivan/my-superproject.git
- Add the contents of the project-directory to the list of files that are to be committed using this command:
git add .
- Commit the files locally using this command:
git commit -m “Initial commit”
- Push the changes to the remote repository:
git push -u origin master
- Enter the username and password of the GitLab user you created earlier when requested.
In the terminal window, it should look something like this:
Username for 'http://localhost:8880': ivan
Password for 'http://ivan@localhost:8880':
Counting objects: 67, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (58/58), done.
Writing objects: 100% (67/67), 24.29 KiB | 2.43 MiB/s, done.
Total 67 (delta 11), reused 0 (delta 0)
* [new branch] master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.
- In the web browser, refresh the GitLab project page.
Files should appear in the project.
As earlier, I will get back to GitLab in a future article – stay tuned!