docker-gitlab

Docker Compose stack for deploying GitLab CE on a development server behind nginx-proxy.

How it works

Internet ──► nginx-proxy :443 (TLS) ──► gitlab container :80 (HTTP)
                                     ──► gitlab container :22 (SSH, host port 2222)

nginx-proxy auto-detects the GitLab container and routes traffic to it based on the hostname. TLS certificates are issued automatically by acme-companion if it is running alongside nginx-proxy.

---

Prerequisites

Before deploying, make sure the target server has:

• Docker and Docker Compose installed
• The nginx-proxy stack running (see its repo for setup instructions)
• A Docker network named nginx-proxy already created by that stack
• A DNS A record pointing your GitLab hostname to the server's public IP
• Ports 443 and 2222 open in the server firewall

---

Deploying to a server

1. Clone this repository

git clone <this-repo-url> docker-gitlab
cd docker-gitlab

2. Create the environment file

cp .env.example .env

Open .env and fill in every value:

nano .env   # or use your preferred editor

Variable	Description	Example
GITLAB_VERSION	GitLab EE image version	17.10.0
GITLAB_HOSTNAME	FQDN for GitLab — must match your DNS record	gitlab.example.com
GITLAB_SSH_PORT	Host port for SSH access (avoid 22 — it's the server's own SSH)	2222
GITLAB_HOME	Absolute path on the host for persistent data	/srv/gitlab
LETSENCRYPT_EMAIL	Email for Let's Encrypt certificate notifications	admin@example.com
NGINX_PROXY_NETWORK	Docker network shared with nginx-proxy	nginx-proxy

3. Create the data directories

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

If you changed GITLAB_HOME in .env, replace /srv/gitlab with that path.

4. Start GitLab

docker compose up -d

GitLab takes 2–3 minutes to fully initialize on first boot. Monitor progress with:

docker logs -f gitlab

Once you see gitlab Reconfigured! in the logs, GitLab is ready.

5. Retrieve the initial root password

On the first boot, GitLab generates a temporary root password:

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

This file is automatically deleted after 24 hours. Change the root password immediately after logging in.

6. Log in

Open https://<GITLAB_HOSTNAME> in a browser and sign in with:

• Username: root
• Password: the value from step 5

---

SSH access for Git

Because port 22 on the server is reserved for the server's own SSH daemon, GitLab's SSH is exposed on port 2222 (or whatever you set GITLAB_SSH_PORT to).

Add this to ~/.ssh/config on developer machines so Git over SSH works normally:

Host gitlab.example.com
    Port 2222

---

Updating GitLab

Always check the GitLab upgrade path before upgrading — do not skip major versions.

1. Edit .env and bump GITLAB_VERSION to the new version.
2. Pull and restart:

docker compose pull
docker compose up -d

---

Useful commands

# Check the status of all GitLab services inside the container
docker exec -it gitlab gitlab-ctl status

# Tail GitLab application logs
docker exec -it gitlab gitlab-ctl tail

# Run a GitLab reconfigure (after manual config changes)
docker exec -it gitlab gitlab-ctl reconfigure

# Stop GitLab gracefully
docker compose down

# Back up GitLab data
docker exec -it gitlab gitlab-backup create

---

File reference

.
├── docker-compose.yml   # Service definition
├── .env.example         # Configuration template — copy to .env and fill in
├── .env                 # Your local config (git-ignored, never commit this)
├── .gitignore
├── CLAUDE.md            # Context for AI-assisted development
└── README.md            # This file