docs/articles/enterprise/components/gitlab.md

GitLab CE

GitLab CE powers the Stoplight backend, including file storage and database. GitLab is the backing datastore for all files stored within Stoplight. In addition to storing files, GitLab is responsible for:

• Interfacing with the Stoplight API
• User-facing notifications (including password reset emails, group/project invitations, etc)
• Tracking all changes between different files, and storing them within a Git repository

Packaged within the GitLab CE is an embedded installation of PostgreSQL and Redis. These two sub-components can be broken out into external services if your organization is already familiar with running these (or similar) services. You may also break out these services if you plan on using a managed hosting solution, for example, Amazon RDS (for PostgreSQL) or Amazon ElastiCache (for Redis).

Storage Requirements

GitLab requires persistent storage in order to store Stoplight file data (in Git), and optionally PostgreSQL data (when using the omnibus package).

Networking Details

The default GitLab ports are 80 (HTTP) and 443 (HTTPS). These ports can be customized via the gitlab.rb configuration file (discussed below).

GitLab must be able to receive incoming connections from the following components:

• App

GitLab must be able to make outgoing connections to the following components:

• PostgreSQL
• Redis

Component Dependencies

Make sure the following components are available before starting the GitLab service:

• PostgreSQL
• Redis

Note, for Omnibus users using the embedded PostgreSQL and Redis instances, these services will be started by the GitLab process.

Installation

GitLab can be installed with Docker or via RPM package.

RPM Package

Prior to installing the RPM package, you will need to have the Stoplight package repository installed and configured with your user-specific credentials.

You can do this by copying-and-pasting the contents below into a terminal:

# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"

# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF

Make sure that the repository credentials are set before issuing the cat command above.

Once the repository is configured properly, you can install the GitLab component using the command:

sudo yum install stoplight-gitlab -y

Docker Installation

To install the app component with Docker, run the command below:

docker pull quay.io/stoplight/gitlab

Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials

Configuring and Running

To configure the Stoplight GitLab component, you will need to provide connection details to the other necessary components.

Package-based Installations

Configuring the Service

The Stoplight GitLab configuration is located at:

/etc/gitlab/gitlab.rb

The above file encompasses all of the different configuration options exposed by GitLab. This guide only covers those specific to Stoplight.

For documentation on other GitLab configuration options, see the official documentation here

Starting the Service

To start GitLab for the first time, run the commands:

# one-time configuration (needed on new installs and upgrades)
sudo gitlab-ctl reconfigure

# start the services
sudo gitlab-ctl start

Once started, you can see the status of the service using the command:

sudo gitlab-ctl status

Docker Installations

Configuring the Container

The GitLab container should be configured nearly identically to the package installation described above. The easiest way to do this is to mount the GitLab configuration directory inside the container.

To mount the configuration inside the container, use the -v argument to the docker run command:

docker run -v /data/gitlab-config:/etc/gitlab ...

Where /data/gitlab-config is a directory containing your gitlab.rb configuration file.

See here for more information on how to configure GitLab

Starting the Container

To start the app container, run the command:

docker run \
        --restart on-failure \
		-v /my/config:/etc/gitlab \
		-p 8080:8080 \
		quay.io/stoplight/gitlab:latest

If started properly, the container should be marked with a healthy status within 90 seconds (sometimes a little longer on first boot). Use the docker ps command to verify the container was started and is running properly.

Post-install Validations

Once the GitLab component is running, you can verify the installation was successful by using the methods below.

GitLab Environment Check

GitLab comes with it's own check that can be useful for catching any improperly configured components. To run this check, use the command:

sudo gitlab-rake gitlab:check RAILS_ENV=production

If you are using a from-source installation, the command is modified to:

sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production

GitLab UI

If the environment check is successful, then you are ready to load up the GitLab UI. In a web browser, visit the host and port that you are running GitLab's HTTP port on.

For example, if you are running GitLab on host gitlab.example.com on port 8080, you can visit the following URL in a web browser to see the GitLab UI:

http://gitlab.example.com:8080/

If the installation was successful, you will be greeted by a GitLab-branded login screen similar to what is displayed on their hosted login screen.

If you have enabled SSL, make sure to use https:// when typing the GitLab URL.

FAQ

Can I use the embedded Redis or PostgreSQL for other services?

Yes! To expose the embedded Redis instance to the outside world, use the configuration:

redis['bind'] = '127.0.0.1'
redis['port'] = 6379

Similarly, for PostgreSQL, use the configuration:

postgresql['listen_address'] = '127.0.0.1'
postgresql['port'] = 5432

Once the configuration changes are made, issue a gitlab-ctl reconfigure for the changes to take effect.

If running GitLab in Docker, be sure to expose the Redis/PostgreSQL ports with the -p command-line option

For more information on configuring Redis, see the official GitLab documentation here.