Environment Specifications

• OS: CentOS 7
• Container Engine: Docker v26.0.0
• Image: twang2218/gitlab-ce-zh

Migration Workflow

Pre-Migration Preparation

Identify the initial launch configuration from the source machine.

docker inspect --format='{{json .HostConfig.PortBindings}}' gitlab > bindings.json

Document volume mounts to ensure consistency on the destination:

docker inspect --format='{{range .Mounts}}{{.Source}} -> {{.Destination}}\n{{end}}' gitlab

Data Transfer

Compress the persistent data directory (e.g., /srv/gitlab) containing etc, data, and log folders.

tar -czvf gitlab_backup.tar.gz /srv/gitlab/
scp gitlab_backup.tar.gz new-host:/tmp/
tar -xzf gitlab_backup.tar.gz -C /srv/gitlab/

Image Transport

Transfer the container image layer without pulling from external registries.

docker save twang2218/gitlab-ce-zh > gitlab_image.tar
scp gitlab_image.tar new-host:/tmp/
docker load < /tmp/gitlab_image.tar

Deployment

Execute the startup command on the target node using mapped ports 80, 443, and 8022 for SSH access.

docker run -d \
  --name 'gitlab-instance' \
  --restart=always \
  -p 8022:22 -p 80:80 -p 8443:443 \
  -v /srv/gitlab/etc:/etc/gitlab \
  -v /srv/gitlab/log:/var/log/gitlab \
  -v /srv/gitlab/data:/var/opt/gitlab \
  twang2218/gitlab-ce-zh

Troubleshooting Common Failure Modes

Issue 1: Service Restart Loops

If the container exits repeatedly, check the boot logs for filesystem errors.

Error: /proc/sys/fs/file-max: Read-only file system
Operation not permitted

Resolution: Adjust permissions on the repository storage path.

chmod 2770 /srv/gitlab/data/git-data/repositories

Issue 2: SSH Key Validation Failures

Logs may indicate permission denials regarding .ssh/authorized_keys.

error: could not open .../authorized_keys: Permission denied

Resolution: Trigger GitLab's internal permission repair utility with in the running container.

docker exec -it gitlab-instance update-permissions
docker restart gitlab-instance

Note: If specific directories are missing during this process (e.g., registry), create them first before retrying the repair command.

mkdir -p /srv/gitlab/data/gitlab-rails/shared/registry

Issue 3: Alertmanager Storage Ownership

In some scenarios, internal service directories retain incorrect group ownership after migration.

Diagnosis: Inspect the alert manager data folder inside the container shell.

docker exec -it gitlab-instance ls -l /var/opt/gitlab/alertmanager/data/
# Current owner might be 'git' instead of 'gitlab-prometheus'

Resolution: Correct the user and group attributes recursively.

docker exec -it gitlab-instance chown -R gitlab-prometheus:gitlab-prometheus /var/opt/gitlab/alertmanager/data/

Verification

Remove any stale containers and restart the instance with the corrected configuration. Access the UI to confirm that project repositories are accessible and services are healthy.