Most failures of an instance in a container appear at start, and the reason is in the container output or in the logs on the log volume. Each section below gives the symptom, the cause and the action.
The web interface answers 502 after a start
Cause. every start runs gitlab-ctl reconfigure, and the application accepts requests only after it. The first start takes several minutes, a later one takes one or two.
Action. follow the start in the container output and wait for the configuration to finish:
docker logs -f code
docker exec code gitlab-ctl statusA 502 that holds for longer means the application is not starting: read its log and check the free memory on the host.
docker exec code gitlab-ctl tail pumaThe container health stays unhealthy
Cause. the health check runs every 60 seconds and turns the container unhealthy after five failures in a row, which a first start reaches while the configuration is still running. A health that stays unhealthy after that means the services have not started.
Action. run the same check by hand and look at the services and at the configuration log:
docker exec code gitlab-healthcheck --fail --max-time 10
docker exec code gitlab-ctl status
docker exec code ls /var/log/gitlab/reconfigureServices do not start after the volumes were copied or restored
Cause. the owner and the mode of the files in the volumes do not match the accounts inside the image, which are created with fixed identifiers.
Action. restore the ownership with the command the image ships and restart the container:
docker exec -it code update-permissions
docker restart codeThe database upgrade failed and the container exited
Where it appears. the container output holds Upgrading the existing database failed and was reverted.
Cause. the start runs gitlab-ctl pg-upgrade, the upgrade failed and the database was rolled back to its previous version.
Action. create the container again with -e GITLAB_SKIP_PG_UPGRADE=true added to the command from Quick start. The instance starts on the current PostgreSQL version, and the database upgrade is then handled as described in Upgrade.
The instance does not answer over HTTPS
Cause. the image exposes port 443, but a port is reachable only when the container publishes it, and ports are fixed when the container is created.
Action. remove the container and create it again from the command in Quick start, with -p 443:443 and the same volumes; the data stays on the volumes:
docker stop code
docker rm codeLinks and clone URLs name the container identifier
Cause. the address of the instance is not set, and the image builds it from the host name of the container, which Docker sets to the container identifier.
Action. set external_url in /etc/gitlab/gitlab.rb and restart the container, or create the container again with the address in GITLAB_OMNIBUS_CONFIG, as described in Quick start.
The container stops at the upgrade check
Where it appears. the container output reports the version found in the data and the version to upgrade to first.
Cause. the start compares the version on the data volume with the version in the image and stops when the instance cannot move to it in one step.
Action. run the tag of the intermediate version first, then the target one, as described in Upgrade.
A configuration change has no effect
Where it appears. the container output holds Skipped reconfigure because GITLAB_SKIP_RECONFIGURE is set.
Cause. the variable GITLAB_SKIP_RECONFIGURE is set to true, so the start leaves the configuration as it is. The same symptom without that line means the setting is present in GITLAB_OMNIBUS_CONFIG and is overridden by /etc/gitlab/gitlab.rb.
Action. run the configuration by hand, or create the container without the variable:
docker exec code gitlab-ctl reconfigureGit over SSH is refused
Cause. port 22 of the container is not published, or GITLAB_DISABLE_OPENSSH is set to true and the sshd service is not prepared, or the client connects to a host port that the clone URL does not name.
Action. check the published ports and the variables of the container, then set the SSH port as described in Post-installation setup:
docker port code
docker inspect --format '{{.Config.Env}}' codeA client that reports a changed host key after a restart works against a new configuration volume: the host keys were generated anew.
General diagnostics
These commands read the state of a running container:
docker logs -f code
docker exec code gitlab-ctl status
docker exec code gitlab-ctl tail <SERVICE>
docker exec code gitlab-rake gitlab:check SANITIZE=true
docker inspect --format '{{.State.Health.Status}}' codeThe logs of every service are on the log volume, /srv/code/logs on the host, and the log of each configuration run is in /var/log/gitlab/reconfigure.