Maintenance commands

The following commands can be run after installation.

Get service status

Run sudo gitlab-ctl status; the output should look like this:

run: nginx: (pid 972) 7s; run: log: (pid 971) 7s
run: postgresql: (pid 962) 7s; run: log: (pid 959) 7s
run: redis: (pid 964) 7s; run: log: (pid 963) 7s
run: sidekiq: (pid 967) 7s; run: log: (pid 966) 7s
run: unicorn: (pid 961) 7s; run: log: (pid 960) 7s

Tail process logs

See settings/logs.md.

Starting and stopping

After Omnibus GitLab is installed and configured, your server will have a runit service directory (runsvdir) process running that gets started at boot via /etc/inittab or the /etc/init/gitlab-runsvdir.conf Upstart resource. You should not have to deal with the runsvdir process directly; you can use the gitlab-ctl front-end instead.

You can start, stop or restart GitLab and all of its components with the following commands.

# Start all GitLab components
sudo gitlab-ctl start

# Stop all GitLab components
sudo gitlab-ctl stop

# Restart all GitLab components
sudo gitlab-ctl restart

Note that on a single-core server it may take up to a minute to restart Unicorn and Sidekiq. Your GitLab instance will give a 502 error until Unicorn is up again.

It is also possible to start, stop or restart individual components.

sudo gitlab-ctl restart sidekiq

Unicorn supports zero-downtime reloads. These can be triggered as follows:

sudo gitlab-ctl hup unicorn

If you are using Puma, Puma does support almost zero-downtime reloads. These can be triggered as follows:

sudo gitlab-ctl hup puma

Note that you cannot use a Unicorn/Puma reload to update the Ruby runtime.

Puma and Unicorn have different signals to control application behavior:

SignalUnicornPuma
HUPreloads config file and gracefully restart all workersreopen log files defined, or stop the process to force restart
INTstops request processing immediatelygracefully stops requests processing
USR1reopen all logs owned by the master and all workersrestart workers in phases, a rolling restart, without config reload
USR2reexecute the running binaryrestart workers and reload config
QUITexit the main processexit the main process

The behavior of graceful restart (gitlab-ctl hup unicorn and gitlab-ctl hup puma) is defined as follow:

  1. Unicorn: a sequence of SIGUSR2 and SIGQUIT signals are sent to Unicorn,
  2. Puma: a sequence of SIGINT and SIGTERM (if process does not restart) signals are sent to Puma.

There are structural differences in handling of graceful restart (gitlab-ctl hup) between Unicorn and Puma:

  1. Unicorn starts a new process, but continues processing requests on old master, it stops accepting connections once SIGQUIT is received,
  2. Puma stops accepting new connections as soon as SIGINT is received. It finishes all running requests. Then runit restarts the service.

Invoking Rake tasks

To invoke a GitLab Rake task, use gitlab-rake. For example:

sudo gitlab-rake gitlab:check

Leave out sudo if you are the git user.

Contrary to with a traditional GitLab installation, there is no need to change the user or the RAILS_ENV environment variable; this is taken care of by the gitlab-rake wrapper script.

Starting a Rails console session

If you need access to a Rails production console for your GitLab installation you can start one with the command below. Please be warned that it is very easy to inadvertently modify, corrupt or destroy data from the console.

# start a Rails console for GitLab
sudo gitlab-rails console

This will only work after you have run gitlab-ctl reconfigure at least once.

Starting a PostgreSQL superuser psql session

If you need superuser access to the bundled PostgreSQL service you can use the gitlab-psql command. It takes the same arguments as the regular psql command.

# Superuser psql access to GitLab's database
sudo gitlab-psql -d gitlabhq_production

This will only work after you have run gitlab-ctl reconfigure at least once. The gitlab-psql command cannot be used to connect to a remote PostgreSQL server, nor to connect to a local non-Omnibus PostgreSQL server.

Starting a PostgreSQL superuser psql session in Geo tracking database

Similar to the previous command, if you need superuser access to the bundled Geo tracking database (geo-postgresql), you can use the gitlab-geo-psql. It takes the same arguments as the regular psql command. For HA, see more about the necessary arguments in: Checking Configuration

# Superuser psql access to GitLab's Geo tracking database
sudo gitlab-geo-psql -d gitlabhq_geo_production

Container Registry garbage collection

Container Registry can use considerable amounts of disk space. To clear up unused layers, the registry includes a garbage collect command.

Read on how to use the Container Registry garbage collection.