Deploying a Local GitLab Instance with Docker Compose on Ubuntu

Background

To work on an important project whose source repository cannot be accessed directly, a local GitLab instance is deployed on an Ubuntu VM to enable version control and collaborative development.

Environment Dependencies

1. An Ubuntu virtual machine. 2. Docker installed on the VM. 3. Ability to reach Docker Hub (or use an offline installation method).

Deploy GitLab

3.1 Use Docker‑Compose to start the GitLab container

Pull the GitLab image.

Create a docker-compose.yml file.

Start the GitLab container.

3.1.1 Pull the GitLab image

docker pull gitlab/gitlab-ee:latest

3.1.2 Create docker-compose.yml

Run vim docker-compose.yml and add the following content:

version: '3.3'
services:
  web:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
    ports:
      - '8000:80'
      - '8443:443'
      - '2222:22'
    volumes:
      - '/home/wukong/gitlab/config:/etc/gitlab'
      - '/home/wukong/gitlab/logs:/var/log/gitlab'
      - '/home/wukong/gitlab/data:/var/opt/gitlab'
    shm_size: '256m'

Explanation of key fields:

version: '3.3' – Docker‑Compose file version.

services: – Begin service definitions.

web: – Service name (customizable).

image: 'gitlab/gitlab-ee:latest' – Docker image to use.

restart: always – Container restart policy.

hostname: 'gitlab.example.com' – Container hostname.

environment: – Environment variables, including GITLAB_OMNIBUS_CONFIG to set external_url .

ports: – Port mappings (8000→80, 8443→443, 2222→22).

volumes: – Bind mounts for configuration, logs, and data.

shm_size: '256m' – Shared memory size.

Create the required host directories:

/home/wukong/gitlab/config

/home/wukong/gitlab/logs

/home/wukong/gitlab/data

3.1.3 Start the container

From the directory containing docker-compose.yml , run:

docker-compose up -d
docker ps

After a few minutes the container status changes from starting to healthy . See the official documentation for more options: GitLab Docker install guide .

3.2 Access GitLab

GitLab can be accessed via the VM’s IP address or the configured domain name:

IP access: https:// :8443/

Domain access: add gitlab.example.com to /etc/hosts and open https://gitlab.example.com:8443/

3.3 Reset the root password

Since the default root credentials are unknown, reset the password from inside the container:

Find the container ID: sudo docker ps

Enter the container: sudo docker exec -it <container_id> /bin/bash

Navigate to the GitLab bin directory: cd /opt/gitlab/bin

Run the Rails console: gitlab-rails console

Locate the root user: u = User.where(id: 1).first

Set a new password and confirmation: u.password = 'passjava' u.password_confirmation = 'passjava' u.save

After saving, exit the container and log in with username root and password passjava .

Testing GitLab Features

4.1 Register a user

Users can register on the GitLab sign‑up page; registrations require administrator approval.

4.2 Create a group and project

The administrator creates a group, then a project within that group, and adds users as members.

4.3 Add an SSH key

After logging in, users add an SSH key (or generate one) to enable git push and git pull over SSH.

4.4 Clone the project

Clone the repository with HTTPS: git clone https://gitlab.example.com:8443/test-group/passjava.git Or using the VM’s IP address. Enter the username and password when prompted.

4.5 Push changes

After making changes locally, commit and push them back to the GitLab repository.

Appendix: Offline GitLab installation

To install GitLab on a machine without internet access, pull the image, save it as a tar archive, adjust permissions, copy the archive to the target servers, and load it: docker pull gitlab/gitlab-ee:latest sudo docker save -o gitlab-ee.tar gitlab/gitlab-ee:latest sudo chmod 777 gitlab-ee.tar # copy tar to target servers sudo docker load -i gitlab-ee.tar Then follow the same docker‑compose.yml creation and container start steps as in section 3.1.