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 Update package index: sudo apt-get update Install required packages: sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common 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 Set up Docker repository: sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" Install Docker: sudo apt-get update sudo apt-get install -y docker-ce Install Docker Compose 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 Apply executable permissions: sudo chmod +x /usr/local/bin/docker-compose Verify installation: docker-compose --version Create the docker-compose.yml File Create a directory and navigate into it: mkdir gitlab-docker-setup cd gitlab-docker-setup 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://: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://: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: Verify Docker Containers: docker ps Check Docker Logs for GitLab: docker logs gitlab-server Confirm Port 8088 is Open: aws ec2 describe-security-groups --group-ids --query "SecurityGroups[*].IpPermissions" Check for Firewalls: sudo ufw status Restart Docker Compose: docker-compose down docker-compose up -d Configure the GitLab Runner Access the GitLab UI: http://:8088 Log in using root as the username and the password set in the docker-compose.yml file. Create a new project in GitLab. Go to Admin > CI/CD > Runners, and click on New instance runner to obtain the registration token.(tag the Runner; docker) Register the runner: docker exec -it gitlab-runner gitlab-runner register 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.

Feb 20, 2025 - 16:43

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

Update package index:
```
sudo apt-get update
```

Install required packages:

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

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

Set up Docker repository:

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

Install Docker:

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

Install Docker Compose

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

Apply executable permissions:

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

Verify installation:
```
docker-compose --version
```

Create the `docker-compose.yml` File

Create a directory and navigate into it:

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

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://: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://: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:

Verify Docker Containers:
```
docker ps
```
Check Docker Logs for GitLab:
```
docker logs gitlab-server
```

Confirm Port 8088 is Open:

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

Check for Firewalls:
```
sudo ufw status
```

Restart Docker Compose:

docker-compose down
docker-compose up -d

Configure the GitLab Runner

Access the GitLab UI:
```
http://:8088
```
Log in using root as the username and the password set in the docker-compose.yml file.
Create a new project in GitLab.
Go to Admin > CI/CD > Runners, and click on New instance runner to obtain the registration token.(tag the Runner; docker)

docker exec -it gitlab-runner gitlab-runner register

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.