---
title: "GitLab CE mit Docker installieren: Vollständige DevOps-Plattform mit Git, CI\/CD und Container-Registry"
date: 2026-07-05T07:42:31+02:00
modified: 2026-11-08T19:26:58+01:00
category: cloud
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/gitlab-ce-docker-devops-plattform
reading_time: 10
variables:
  - name: gitlab_root_pw
    label: "GitLab-Root-Passwort"
    generated_in_browser: true
---

# GitLab CE mit Docker installieren: Vollständige DevOps-Plattform mit Git, CI/CD und Container-Registry

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{gitlab_root_pw}}` | GitLab-Root-Passwort | wird im Browser des Lesers zufällig erzeugt |

Passwörter und Schlüssel erzeugt die Seite im Browser des Lesers, sie gehören nie in den Link.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten, statt die Befehle selbst umzuschreiben.

GitLab Community Edition (CE) bündelt Git-Hosting, Merge Requests, CI/CD-Pipelines, Container-Registry und Package-Registry in einer selbst gehosteten Instanz. Die MIT-lizenzierte Plattform läuft als ein Docker-Container auf Ihrem Linux-Server. Diese Anleitung führt von der leeren VM bis zur laufenden Instanz mit registriertem GitLab Runner für CI/CD-Pipelines.

**Kurzfassung:** GitLab CE (Image `gitlab/gitlab-ce:19.4.1-ce.0`) läuft als Omnibus-Container mit eingebettetem PostgreSQL, Redis, Nginx und Sidekiq, ein separater Datenbank-Container entfällt. Die `.env` enthält `GITLAB_HOME`, `GITLAB_HOSTNAME` und `GITLAB_ROOT_PASSWORD`. Der Port in `external_url` muss zum Port-Mapping passen. Der erste Start dauert 3 bis 5 Minuten, ein 502-Fehler in dieser Zeit ist normal. CI/CD-Pipelines benötigen einen GitLab Runner, den Sie mit einem Runner-Authentifizierungstoken (`glrt-…`) registrieren. Planen Sie mindestens 8 GB RAM ein.

## Voraussetzungen

- [ ] **Linux-Host oder VM**: z. B. Ubuntu 24.04, Debian 12/13 oder Rocky Linux 9. Docker Desktop für Windows unterstützt GitLab nicht.
- [ ] **Docker Engine ≥ 20.10.10** und **Docker Compose Plugin v2** (`docker compose` ohne Bindestrich) installiert. Falls noch nicht vorhanden: [Docker und Docker Compose auf Linux installieren (Ubuntu/Debian)](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage).
- [ ] **RAM:** mindestens 8 GB (Untergrenze laut GitLab für speicherarme Umgebungen), 16 GB als Richtwert für eine Einzelinstanz. PostgreSQL, Redis, Sidekiq und Puma laufen alle im selben Container.
- [ ] **CPU:** 8 vCPU sind der GitLab-Richtwert für eine Einzelinstanz, x86_64 oder ARM64.
- [ ] **Speicher:** mindestens 40 GB auf SSD plus Platz für Repositories und CI/CD-Artefakte.
- [ ] **Statischer Hostname oder FQDN** für den Wert `external_url`; ohne feste Adresse entstehen fehlerhafte Clone-URLs.
- [ ] **Optional:** Reverse Proxy (z. B. [Caddy](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung) oder Nginx) für HTTPS-Terminierung; SMTP-Relay für E-Mail-Benachrichtigungen (GitLab hat keinen eingebauten Mailserver).

## Schritt 1: Projektordner und Verzeichnisstruktur anlegen

Konfiguration, Logs und Repositories liegen unter dem Basispfad `GITLAB_HOME`. GitLab empfiehlt `/srv/gitlab`.

```bash
$ sudo mkdir -p /srv/gitlab
$ sudo mkdir -p /opt/gitlab-compose
$ cd /opt/gitlab-compose
```

`/opt/gitlab-compose` nimmt `compose.yaml` und `.env` auf.

> **Prüfen:** ```bash
> $ ls -la /srv/gitlab /opt/gitlab-compose
> ```
>
> Erwartetes Ergebnis: beide Verzeichnisse existieren, Eigentümer `root`. Die Unterordner `config`, `logs` und `data` legt Docker beim ersten Start an.

## Schritt 2: .env-Datei mit Zugangsdaten anlegen

Die `.env` enthält die variablen Werte und gehört nicht in ein Git-Repository. Erstellen Sie die Datei unter `/opt/gitlab-compose/.env` und passen Sie die drei Pflichtfelder an:

Datei: `/opt/gitlab-compose/.env`

```plaintext
# /opt/gitlab-compose/.env
# Basispfad fuer alle Volume-Mounts auf dem Host
GITLAB_HOME=/srv/gitlab

# Hostname oder IP-Adresse der GitLab-Instanz
# Muss mit dem Port in GITLAB_OMNIBUS_CONFIG uebereinstimmen
GITLAB_HOSTNAME=gitlab.example.com

# Initiales Root-Passwort (mind. 12 Zeichen, Sonderzeichen erlaubt)
# Wird bei erstem Start gesetzt; Datei /etc/gitlab/initial_root_password
# wird nach 24 h automatisch geloescht!
GITLAB_ROOT_PASSWORD={{gitlab_root_pw}}
```

Schützen Sie die Datei vor unbefugtem Zugriff:

```bash
$ chmod 600 /opt/gitlab-compose/.env
```

> **Prüfen:** ```bash
> $ ls -la /opt/gitlab-compose/.env
> ```
>
> Erwartetes Ergebnis: Berechtigungen `-rw-------`, Eigentümer `root`.

## Schritt 3: compose.yaml erstellen

Die `compose.yaml` definiert den GitLab-Container und einen GitLab Runner für CI/CD-Pipelines.

```plaintext
# /opt/gitlab-compose/compose.yaml
services:
  gitlab:
    image: gitlab/gitlab-ce:19.4.1-ce.0
    container_name: gitlab
    restart: always
    hostname: ${GITLAB_HOSTNAME}
    # shm_size PFLICHT: ohne diese Zeile schreibt Prometheus in einen
    # zu kleinen /dev/shm-Bereich und erzeugt "unmapped file"-Fehler
    shm_size: '256m'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://${GITLAB_HOSTNAME}:8929'
        # SSH-Port: muss mit dem Host-seitigen Port-Mapping uebereinstimmen
        gitlab_rails['gitlab_shell_ssh_port'] = 2424
        # Root-Passwort aus .env setzen (Alternative: nach Start manuell auslesen)
        gitlab_rails['initial_root_password'] = '${GITLAB_ROOT_PASSWORD}'
        # Optional: Container-Registry aktivieren
        # registry_external_url 'http://${GITLAB_HOSTNAME}:5050'
        # Optional: SMTP (kein Mailserver eingebaut)
        # gitlab_rails['smtp_enable'] = true
        # gitlab_rails['smtp_address'] = "smtp.example.com"
        # gitlab_rails['smtp_port'] = 587
    ports:
      - '8929:8929'
      - '2424:22'
    volumes:
      - '${GITLAB_HOME}/config:/etc/gitlab'
      - '${GITLAB_HOME}/logs:/var/log/gitlab'
      - '${GITLAB_HOME}/data:/var/opt/gitlab'
    logging:
      driver: 'json-file'
      options:
        max-size: '50m'
        max-file: '5'

  gitlab-runner:
    image: gitlab/gitlab-runner:v19.4.1
    container_name: gitlab-runner
    restart: always
    depends_on:
      - gitlab
    volumes:
      - '${GITLAB_HOME}/runner/config:/etc/gitlab-runner'
      - '/var/run/docker.sock:/var/run/docker.sock'
    logging:
      driver: 'json-file'
      options:
        max-size: '20m'
        max-file: '3'
```

Port in `external_url` (`:8929`) und Port-Mapping (`8929:8929`) müssen übereinstimmen, sonst zeigt GitLab falsche Clone-URLs. Werte aus `GITLAB_OMNIBUS_CONFIG` landen nicht in `/etc/gitlab/gitlab.rb`, sondern werden bei jedem Container-Start neu ausgewertet.

Port 8929 überträgt unverschlüsselt HTTP und ist auf allen Schnittstellen erreichbar. Geben Sie ihn per Firewall nur im internen Netz frei; für Zugriff aus dem Internet gehört ein Reverse Proxy mit HTTPS davor. Der Runner erhält über `/var/run/docker.sock` Vollzugriff auf Docker und damit faktisch Root-Rechte auf dem Host. Lassen Sie deshalb nur vertrauenswürdige Projekte Jobs auf diesem Runner ausführen.

> **Prüfen:** ```bash
> $ docker compose -f /opt/gitlab-compose/compose.yaml config
> ```
>
> Erwartetes Ergebnis: Docker Compose gibt die vollständig interpolierte Konfiguration ohne Fehler aus; alle `${...}`-Variablen sind durch Werte aus der `.env` ersetzt.

## Schritt 4: GitLab starten und Initialisierung abwarten

Starten Sie den Stack aus dem Compose-Verzeichnis heraus:

```bash
$ cd /opt/gitlab-compose
$ docker compose up -d
```

Docker lädt das Image (ca. 1,2 GB komprimiert) und startet den Container. Die erste Initialisierung dauert **3 bis 5 Minuten**, auf langsamerer Hardware bis zu 10 Minuten. In dieser Zeit zeigt der Browser „502 Whoops, GitLab is taking too much time to respond“. Das ist der normale Initialisierungsablauf.

```bash
# Logs live verfolgen (mit Ctrl+C abbrechen)
```

```bash
$ docker compose logs -f gitlab
```

```bash
# Auf das Signal warten, dass GitLab bereit ist:
```

```bash
$ docker compose logs -f gitlab | grep -i 'server booted'
```

**Eckdaten im Überblick:**

| Parameter | Wert |
| --- | --- |
| Image | gitlab/gitlab-ce:19.4.1-ce.0 |
| Web-UI (HTTP) | Port 8929 → http://HOSTNAME:8929 |
| HTTPS | über Reverse Proxy (siehe Häufige Fragen) |
| Git SSH | Host-Port 2424 → Container-Port 22 |
| Config-Volume | ${GITLAB_HOME}/config:/etc/gitlab |
| Logs-Volume | ${GITLAB_HOME}/logs:/var/log/gitlab |
| Daten-Volume | ${GITLAB_HOME}/data:/var/opt/gitlab |
| shm_size | 256m (Pflicht) |
| Min. RAM | 8 GB (Richtwert 16 GB) |
| CPU | 8 vCPU (Richtwert) |
| ARM64 | ab v18.1/v18.2 offiziell multi-arch |

> **Prüfen:** ```bash
> $ docker compose ps
> ```
>
> Ausgabe:
>
> ```plaintext
> NAME            IMAGE                           STATUS          PORTS
> gitlab          gitlab/gitlab-ce:19.4.1-ce.0    Up 5 minutes (healthy)   0.0.0.0:2424->22/tcp, 0.0.0.0:8929->8929/tcp
> gitlab-runner   gitlab/gitlab-runner:v19.4.1    Up 5 minutes
> ```
>
> Sobald GitLab vollständig gestartet ist:
>
> ```bash
> $ curl -I http://localhost:8929
> ```
>
> Erwartetes Ergebnis: `HTTP/1.1 302 Found` mit `Location: http://HOSTNAME:8929/users/sign_in`.

## Schritt 5: Erst-Einrichtung im Browser und Root-Passwort sichern

Rufen Sie `http://HOSTNAME:8929` im Browser auf. GitLab leitet auf die Login-Seite weiter. Melden Sie sich mit dem Benutzernamen `root` und dem in der `.env` gesetzten Passwort an.

Haben Sie das Root-Passwort nicht über `GITLAB_OMNIBUS_CONFIG` gesetzt, lesen Sie das generierte Passwort aus:

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

> **Wichtig:** GitLab löscht diese Datei nach 24 Stunden automatisch. Sichern Sie das Passwort sofort. Nehmen Sie nach dem ersten Login diese Grundkonfiguration im Bereich *Admin* vor:

1. **Sign-up deaktivieren** (Admin → Settings → General → Sign-up restrictions, Häkchen bei *Sign-up enabled* entfernen).
2. **E-Mail-Benachrichtigungen:** SMTP-Einstellungen in `GITLAB_OMNIBUS_CONFIG` ergänzen.
3. **Root-Passwort ändern:** Avatar oben → Edit profile → Password.

> **Prüfen:** Login mit `root` funktioniert, Dashboard lädt ohne Fehler, der Admin-Bereich ist erreichbar unter `http://HOSTNAME:8929/admin`.

## Schritt 6: GitLab Runner registrieren für CI/CD-Pipelines

Der GitLab-Runner-Container läuft seit Schritt 4, ist aber noch nicht mit der GitLab-Instanz verbunden. CI/CD-Jobs bleiben in der Warteschlange, bis ein Runner registriert ist. Seit GitLab 16 erzeugen Sie den Runner zuerst in der Oberfläche und erhalten ein Runner-Authentifizierungstoken; das frühere Registrierungstoken („Register an instance runner“) gilt als veraltet:

1. Admin → CI/CD → Runners → **Create instance runner**, Betriebssystem Linux wählen, Tags setzen oder **Run untagged** aktivieren, **Create runner**.
2. Das angezeigte Token mit Präfix `glrt-` kopieren. GitLab zeigt es nur während der Registrierung an.

Registrieren Sie den Runner dann im Container:

```bash
$ docker exec -it gitlab-runner gitlab-runner register
```

Die interaktiven Abfragen:

```plaintext
Enter the GitLab instance URL:
# Eingabe: http://gitlab.example.com:8929

Enter the registration token:
# Eingabe: glrt-... (Token aus der Oberfläche)

Enter a name for the runner:
# Eingabe: docker-runner

Enter an executor:
# Eingabe: docker

Enter the default Docker image:
# Eingabe: alpine:3.22
```

Der Runner speichert seine Konfiguration unter `${GITLAB_HOME}/runner/config/config.toml`.

> **Prüfen:** ```bash
> $ docker compose logs gitlab-runner | tail -20
> ```
>
> Erwartetes Ergebnis: keine `ERROR`-Zeilen; unter Admin → CI/CD → Runners erscheint der Runner als online. Legen Sie eine einfache `.gitlab-ci.yml` ins Repository, um einen Test-Job auszulösen:
>
> Datei: `.gitlab-ci.yml`
>
> ```plaintext
> test-job:
>   script:
>     - echo "Pipeline funktioniert!"
> ```

## Schritt 7: Container-Registry aktivieren (optional)

Die Container-Registry ist standardmäßig deaktiviert. Ergänzen Sie `registry_external_url` und ein Port-Mapping:

```plaintext
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://${GITLAB_HOSTNAME}:8929'
        gitlab_rails['gitlab_shell_ssh_port'] = 2424
        gitlab_rails['initial_root_password'] = '${GITLAB_ROOT_PASSWORD}'
        registry_external_url 'http://${GITLAB_HOSTNAME}:5050'
    ports:
      - '8929:8929'
      - '2424:22'
      - '5050:5050'
```

Anschließend den Stack neu starten:

```bash
$ cd /opt/gitlab-compose
$ docker compose up -d
```

> **Prüfen:** ```bash
> $ curl -I http://localhost:5050/v2/
> ```
>
> Erwartetes Ergebnis: `HTTP/1.1 401 Unauthorized`. Das zeigt, dass die Registry läuft und eine Authentifizierung erwartet. Anmeldung mit `docker login HOSTNAME:5050` und GitLab-Zugangsdaten. Docker akzeptiert eine Registry ohne HTTPS nur, wenn sie auf dem Client als `insecure-registries` eingetragen ist; für den Produktivbetrieb gehört HTTPS davor.

## Schritt 8: Updates und Backups

### Updates durchführen

GitLab erlaubt **keine Sprünge über Major-Versionen** (z. B. nicht 17.x direkt auf 19.x). Prüfen Sie den Upgrade-Pfad unter [docs.gitlab.com/update/upgrade_paths/](https://docs.gitlab.com/update/upgrade_paths/). Minor-Updates (z. B. 19.3.x auf 19.4.x) laufen so:

```bash
# 1. Backup erstellen (siehe unten)
# 2. Image-Tag in compose.yaml auf neue Version aendern, dann:
```

```bash
$ cd /opt/gitlab-compose
$ docker compose pull
$ docker compose up -d
```

Datenbankmigrationen laufen beim Start automatisch, GitLab ist dabei einige Minuten nicht erreichbar.

### Backups erstellen

Ein vollständiges Backup besteht aus zwei Teilen:

```bash
# Teil 1: Repositories, Issues, CI/CD-Konfigurationen
```

```bash
$ docker exec -t gitlab gitlab-backup create
```

```bash
# Teil 2: Secrets-Datei (wird von gitlab-backup create NICHT gesichert!)
# Ohne diese Datei sind alle CI/CD-Variablen und 2FA-Secrets verloren
```

```bash
$ cp /srv/gitlab/config/gitlab-secrets.json /pfad/zum/backup-ziel/gitlab-secrets.json
```

Die Backup-Datei liegt unter `/srv/gitlab/data/backups/`. Eine Backup-Strategie mit Kopie außer Haus zeigt die Anleitung [3-2-1-Backup-Strategie umsetzen: Restic, USB-Disk und S3-Cloud](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen).

> **Prüfen:** ```bash
> $ ls -lh /srv/gitlab/data/backups/
> ```
>
> Erwartetes Ergebnis: Datei mit Namensschema `TIMESTAMP_gitlab_backup.tar` vorhanden.

## Troubleshooting / Typische Fehler

**„writing value to /dev/shm/gitlab/sidekiq/gauge... failed with unmapped file“**

`shm_size: '256m'` fehlt. Ergänzen und `docker compose up -d` ausführen.

**Falsche Clone-URLs**

Port in `external_url` passt nicht zum Port-Mapping (siehe Schritt 3).

**„502 Whoops“ nach dem ersten Start**

GitLab initialisiert sich noch. 3 bis 5 Minuten warten und Logs beobachten: `docker compose logs -f gitlab | grep -i booted`.

**Root-Passwort verloren**

Reset über die Rails-Konsole: `docker exec -it gitlab gitlab-rails console` → `user = User.find_by(username: 'root'); user.password = 'NeuesPasswort12!'; user.save!`

**CI/CD-Jobs warten endlos**

Runner nicht registriert, falsche URL oder Job-Tags passen nicht zum Runner. Schritt 6 wiederholen, `docker compose logs gitlab-runner` prüfen.

**Container startet nicht, „ThreadError: Operation not permitted“**

Docker älter als 20.10.10. Docker aktualisieren: `apt-get upgrade docker-ce docker-ce-cli containerd.io`.

**OOM-Killer beendet Prozesse**

Zu wenig RAM (mindestens 8 GB). Mit `docker stats gitlab` prüfen.

**Host-Festplatte läuft voll**

Log-Rotation fehlt. Die `logging`-Sektion der obigen `compose.yaml` übernehmen.

**Upgrade schlägt fehl**

Pflicht-Zwischenversion übersprungen. Backup einspielen und Upgrade-Pfad unter [docs.gitlab.com/update/upgrade_paths/](https://docs.gitlab.com/update/upgrade_paths/) einhalten.

## Häufige Fragen

### Wie lange dauert der erste Start von GitLab CE?

3 bis 5 Minuten, auf langsamer Hardware bis zu 10 Minuten (Details in Schritt 4).

### Wie unterscheidet sich GitLab CE von GitLab EE?

Die Community Edition (CE) ist MIT-lizenziert und enthält Git-Hosting, Merge Requests, CI/CD, SAST, Container-Registry, Issue-Tracking, Wiki und Package-Registry. Der Enterprise Edition vorbehalten sind unter anderem DAST, das Security-Dashboard, GitLab Geo und erweiterte Compliance-Funktionen. Für die meisten KMU-Teams reicht CE.

### Funktioniert GitLab CE auf ARM64-Servern?

Ja. Seit GitLab 18 gibt es offizielle Multi-Arch-Images (`amd64` und `arm64`) unter `gitlab/gitlab-ce`, Docker wählt die passende Architektur automatisch. Die RAM-Anforderung von mindestens 8 GB gilt auch hier.

### Wie richte ich HTTPS ein?

Entweder über Let's Encrypt im Container (in `GITLAB_OMNIBUS_CONFIG`: `external_url 'https://…'` und `letsencrypt['enable'] = true`, erfordert öffentlich erreichbare Ports 80 und 443 mit entsprechendem Port-Mapping) oder über einen Reverse Proxy wie [Caddy](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung) oder Nginx, der Anfragen an den internen Port 8929 weiterleitet. Bei mehreren Diensten auf einem Server ist der Reverse Proxy die bessere Wahl.

### Wie führe ich ein Backup durch?

Mit `docker exec -t gitlab gitlab-backup create` plus einer Kopie von `${GITLAB_HOME}/config/gitlab-secrets.json`, die das Backup nicht enthält (siehe Schritt 8).

### Wie aktualisiere ich GitLab auf eine neue Version?

Backup erstellen, Image-Tag in `compose.yaml` auf die Zielversion setzen, `docker compose pull && docker compose up -d` ausführen (siehe Schritt 8). Prüfen Sie vorher den offiziellen Upgrade-Pfad unter [docs.gitlab.com/update/upgrade_paths/](https://docs.gitlab.com/update/upgrade_paths/) prüfen.

### Warum braucht GitLab keinen separaten Datenbank-Container?

Das Omnibus-Paket bündelt PostgreSQL, Redis, Sidekiq, Puma, Nginx und Prometheus in einem Container. Das vereinfacht den Betrieb und erklärt den hohen RAM-Bedarf.

## Fazit

GitLab CE vereint Git-Hosting, CI/CD-Pipelines und Container-Registry in einem Docker-Container und ersetzt damit mehrere separate Dienste. Dafür brauchen Sie **mindestens 8 GB RAM**, Upgrades entlang des offiziellen Upgrade-Pfads und eine Sicherung von `gitlab-secrets.json` vor jedem Upgrade.

Als schlankere Alternative ohne eingebaute CI/CD eignet sich [Gitea mit Docker: eigener Git-Server als GitHub-Alternative](https://s-edv.com/anleitungen/gitea-self-hosted-git-server-docker).

## Weiterführende Anleitungen und Quellen

1. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
2. [Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung)
3. [Gitea mit Docker: eigener Git-Server als GitHub-Alternative](https://s-edv.com/anleitungen/gitea-self-hosted-git-server-docker)
4. [3-2-1-Backup-Strategie umsetzen: Restic, USB-Disk und S3-Cloud](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen)
5. [Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root)

Offizielle Quellen: [GitLab Docs: Install GitLab in a Docker container](https://docs.gitlab.com/install/docker/installation/) · [GitLab Docs: Configure GitLab running in a Docker container](https://docs.gitlab.com/install/docker/configuration/) · [Docker Hub: gitlab/gitlab-ce](https://hub.docker.com/r/gitlab/gitlab-ce)
