Setting Up a GitLab Server (Community Edition) and a GitLab Runner Using Docker Compose

Author: Victor Okonkwo

Overview

Set up a Docker-based GitLab and a GitLab Runner using Docker Compose to create a CI/CD environment. Services will be defined in the docker-compose.yml file, configuring storage, exposing GitLab on a local port, and registering the GitLab Runner to execute CI/CD pipelines. Verify the setup by running a test pipeline with a sample project.

Prerequisites

• A Linux Ubuntu server with 4GB RAM and 10GB of free disk space for GitLab data and logs.
• Docker and Docker Compose installed and running on your system.

Install Docker

1. Update package index:
   

   sudo apt-get update
   

2. Install required packages:
   

   sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
   

3. Add Docker's official GPG key:
   

   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/trusted.gpg.d/docker.gpg > /dev/null
   

4. Set up Docker repository:
   

   sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
   

5. Install Docker:
   

   sudo apt-get update
   sudo apt-get install -y docker-ce
   

Install Docker Compose

1. Download Docker Compose binary:
   

   sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
   

2. Apply executable permissions:
   

   sudo chmod +x /usr/local/bin/docker-compose
   

3. Verify installation:
   

   docker-compose --version
   

Create the docker-compose.yml File

1. Create a directory and navigate into it:
   

   mkdir gitlab-docker-setup
   cd gitlab-docker-setup
   

2. Create a docker-compose.yml file with the following configuration:
   

   version: '3.8'
   
   services:
     gitlab-server:
       image: 'gitlab/gitlab-ce:latest'
       container_name: gitlab-server
       hostname: 'gitlab.example.com'
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           external_url 'http://<your-ec2-public-ip>:8088'  # Put the IP of your server
           gitlab_rails['initial_root_password'] = "my_secure_password"  # Set your initial root password here
       ports:
         - '8088:8088'  # Expose GitLab on port 8088
       volumes:
         - ./config:/etc/gitlab  # Persist GitLab configuration
         - ./logs:/var/log/gitlab  # Persist GitLab logs
         - ./data:/var/opt/gitlab  # Persist GitLab data
       restart: always
   
     gitlab-runner:
       image: 'gitlab/gitlab-runner:latest'
       container_name: gitlab-runner
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - ./runner/config:/etc/gitlab-runner
       restart: always
   

Start the Services

Run the following command to start both the GitLab server and the GitLab Runner:

docker-compose up -d

Ensure that your server has port 8088 open. The GitLab UI should be available at http://<your-EC2-public-IP>:8088. Initially, you might get a 502 error, but this should resolve as the services fully initialize.

Troubleshooting Steps

If GitLab is not displaying on your browser:

1. Verify Docker Containers:
   

   docker ps
   

2. Check Docker Logs for GitLab:
   

   docker logs gitlab-server
   

3. Confirm Port 8088 is Open:
   

   aws ec2 describe-security-groups --group-ids <your-security-group-id> --query "SecurityGroups[*].IpPermissions"
   

4. Check for Firewalls:
   

   sudo ufw status
   

5. Restart Docker Compose:
   

   docker-compose down
   docker-compose up -d
   

Configure the GitLab Runner

1. Access the GitLab UI:
   

   http://<your-EC2-public-IP>:8088
   

2. Log in using root as the username and the password set in the docker-compose.yml file.

3. Create a new project in GitLab.

4. Go to Admin > CI/CD > Runners, and click on New instance runner to obtain the registration token.(tag the Runner; docker)

1. Register the runner:
   

   docker exec -it gitlab-runner gitlab-runner register
   

2. Follow the prompts:

   • URL: http://gitlab-server:8088
   • Token: Enter the token obtained from the GitLab UI.
   • Description: docker
   • Executor: docker

Create a .gitlab-ci.yml File

Create a .gitlab-ci.yml file in your project repository to define a simple CI pipeline:

stages:
  - test

test_node_version:
  stage: test
  image: alpine
  script:
    - apk add --no-cache nodejs  # Install Node.js in Alpine
    - node -v                    # Check Node.js version
  tags:
    - docker

Commit and push this change to trigger the pipeline:

git add .
git commit -m "Add CI pipeline"
git push origin main

And that's it!
Go back to your project page and watch it run.

You now have a fully functional GitLab server and GitLab Runner set up using Docker Compose.