Set Up Your Own Local GitLab Server | Self-hosted GitLab

Ever wondered how to run your own Git on local server? Is it even possible? 🤷🏻‍♀️
Ans: Yes, possible

Do you want full control over your repositories, CI/CD pipelines, and user access? Setting up a self-hosted GitLab instance will help!
It may appear difficult, but it's more easier than you think—and I'll walk you through it step by step!

This is the part 1 of Git on localhost! Local GitLab Server series. This article(part 1) contains only the git version control setup on the local machine, We will dive further on the upcoming series.

Why Host Your Own GitLab Server?

While services like GitHub and GitLab.com offer excellent hosted solutions, sometimes you just want full control. Running your own GitLab server can provide:

• Complete autonomy over your code and repositories.
• Unlimited private repositories without cost.
• Custom user access management for your team or projects.
• Full control of CI/CD pipelines.
• Data privacy and security—everything stays on your machine or network.

Prerequisites

Before we begin, make sure you have the following:

• Docker installed (we'll use Docker to easily run GitLab in a container).
• Admin privileges on your machine.
• Minimum hardware requirements(given here).

Installation Process

Step 0: Install Docker

ignore this step if docker is already installed on your machine.

Install Docker from its official website for your desired OS.
Also, we can use any other open source container management tools (eg: Rancher Desktop) instead of Docker

Tip: Before proceeding to the next step, ensure that Docker is running.

Step 1: Download the GitLab CE Docker Image

Open your terminal and write this command to pull the latest gitlab image

docker pull gitlab/gitlab-ce:latest

By doing this, the GitLab CE image that we need to run the server is downloaded.

Step 2: Create Directories for Persistent Storage

To guarantee that GitLab data (such as repositories, settings, and logs) are saved between restarts, establish folders on your own system for these files.

mkdir -p /code/gitlab/config /code/gitlab/logs /code/gitlab/data

Tips: On Windows, you’ll need to use Windows-style paths:

mkdir D:\code\gitlab\config D:\code\gitlab\logs D:\code\gitlab\data

Step 3: Start the GitLab Container

Now it is time to start the GitLab server!
To launch & configure GitLab within a container, we'll use the docker run command:

docker run --detach 
    --hostname localhost 
    --publish 8443:443 
    --publish 8080:80 
    --publish 6022:22 
    --name gitlab 
    --restart always 
    --volume code/gitlab/config:/etc/gitlab 
    --volume code/gitlab/logs:/var/log/gitlab 
    --volume code/gitlab/data:/var/opt/gitlab 
    gitlab/gitlab-ce

Breakdown

1. Hostname:
   • --hostname localhost: We’ve set the hostname to localhost, which should be fine for local testing. You can change this to a custom domain if needed.
2. Ports:
   • --publish 8443:443: Exposes GitLab’s HTTPS (443) to port 8443 on your host machine.
   • --publish 8080:80: Exposes GitLab’s HTTP (80) to port 8080 on your host.
   • --publish 6022:22: Exposes SSH access (22) to port 6022 (used for cloning repositories via SSH).
3. Volumes: The volumes map your local directories to the container.
   • --volume code/gitlab/config:/etc/gitlab: Maps the configuration files to the host’s directory.
   • --volume code/gitlab/logs:/var/log/gitlab: Stores the logs.
   • --volume code/gitlab/data:/var/opt/gitlab: Stores GitLab repositories and other persistent data.

Make sure to replace the code/gitlab/ with the actual absolute path on your system.

Note: on Windows, volume paths need to be D:/code/github/ instead of code/gitlab/for absolute path.

Step 4: Access GitLab Instance

Now that your GitLab container is running, open a web browser and go to http://localhost:8080
You should see the GitLab login screen! Since this is the first time you're logging in, The initialization process could take a lengthy time. You can monitor this process with:

docker logs -f gitlab

After that, you will see this page:

For logging in for the very first time, GitLab provides a default user root and its password.
The default password can be found inside the /etc/gitlab/initial_root_password.
Run the below command to get the password:

docker exec -it gitlab cat /etc/gitlab/initial_root_password

Or, you can use this:

docker exec -it gitlab grep 'Password:' 
/etc/gitlab/initial_root_password

Note: This password file will delete automatically when the first container restart happens afer 24 hours.

After login, This will be our homepage:

Our Project installation is completed. Now We can use this as our local git without internet.
In the next article, i will try push a small test project to our local git server & clone from there.

Alternative Approach

In the Installation Process, we install the server by running several docker commands in our cli.
But now in this approach, we can replace the Step 1 & Step 3 by adding a docker-compose file.

This procedure has been recommended by the GitLab documentation.

1. Create a docker-compose.yml file & copy this below lines:

version: '3.8'

services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    restart: always
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        # Add any other gitlab.rb configuration here, each on its own line
        external_url 'http://localhost:8080'
        gitlab_rails['gitlab_shell_ssh_port'] = 6022
        gitlab_rails['time_zone'] = 'Asia/Tokyo'

    hostname: localhost
    ports:
      - "8443:443"   # HTTPS
      - "8080:80"    # HTTP
      - "6022:22"    # SSH for Git access
    volumes:
      - code/gitlab/config:/etc/gitlab   # Configuration storage
      - code/gitlab/logs:/var/log/gitlab  # Logs storage
      - code/gitlab/data:/var/opt/gitlab  # Data storage (repositories, etc.)

Note: For Windows, change path to C:/path/to/code/gitlab/** instead of code/gitlab/**

1. In the same directory as docker-compose.yml, Run the docker compose command to start GitLab:

docker compose up -d

Common Troubleshooting Tips

If you get a 404 Page Not Found or have issues accessing GitLab, here are some things to check:

1. Is the container running?: Run docker ps to verify the GitLab container is up. If not, check the logs with docker logs gitlab to troubleshoot.
2. Wait for initialization: GitLab can take several minutes to initialize on first launch. Check the container logs with docker logs -f gitlab and wait for the message saying GitLab is ready.
3. Check port mappings: Ensure you’re accessing the correct ports (80 for HTTP or 443 for HTTPS). If there's a conflict, adjust the ports in the docker run command.
4. Firewall/Antivirus: On Windows, ensure Docker is allowed through the firewall and no other security software is blocking the ports.

🎉 Now We have finished configuring our self-hosted GitLab server. We can now manage our code using this as our git server.
In the upcoming sections, we will commit a project onto our local self-hosted GitLab server and set up a CICD pipeline on it.
Let's catch up on the next section! ✨