Docker Quickstart

The guide below covers setting up the Stoplight Next platform in a local/test environment using the docker-compose tool. This guide assumes you already are familiar with Docker and have been provided access to the Stoplight Docker registry by the Stoplight Support team.

Before starting, review the docker-compose.yml file in the Stoplight Enterprise repository.

If deploying Stoplight on a remote instance (for example within an AWS VPC), be sure to review the docker-compose.yml file and update the URL/hostnames according to your environment.

Logging into the Docker Container Registry

The first thing you’ll need to do is to login to the Stoplight container registry. You should have been provided credentials by Stoplight as part of your agreement with us.

If you do not have credentials, please send us an email at [email protected]

To login to the container registry, run the command:

docker login -u="$DOCKER_USERNAME" -p="$DOCKER_PASSWORD"

A Note About DNS

Note this section only applies if you are bringing up Stoplight locally (accessing it and running it on the same machine) - otherwise skip ahead

Due to the way the Stoplight components communicate, you will need to update your local DNS settings in order for your browser and the running Docker containers to be able to communicate with the same hostnames.

If running on macOS or Linux, the easiest way to do add the following line to your /etc/hosts file:   app.stoplight.local api.stoplight.local prism.stoplight.local gitlab.stoplight.local pubs.stoplight.local tasker.stoplight.local

Editing the /etc/hosts file can only be done with administrative access (ie, sudo)

You can accomplish the same goals with a custom DNS server (or something like dnsmasq), however that is outside the scope of this document.

Starting Stoplight

To bring up the Stoplight platform, from the root of this repository run the command:

docker-compose up -d

Note that the -d argument sends the containers into the background. To see the status of containers in the background, run either docker-compose ps or docker-compose logs --tail=10 -f.

After Gitlab is up and has finished its initial configuration (it should be reporting “healthy”), run the following commands to initialize the database:

docker exec -it gitlab gitlab-rake db:migrate VERSION=20180710120850
docker exec -it gitlab gitlab-rake db:migrate

Configuring Pubs

Pubs requires a GitLab admin API token in order to know which project to publish documentation under.

Once GitLab is up, login as the root user (or any other administrative user) and navigate to the user settings page as shown below:

Generating an API token

Create an API key called ‘pubs’ with both api and sudo scopes.

Collecting the API token

Once the API key is generated, set it as the value of PUBS_SL_API_TOKEN in docker-compose.yml.

Once set, recreate the Pubs service with:

docker-compose up -d pubs

Logging into Stoplight

If everything worked, then navigating to the app URL (which defaults to http://app.stoplight.local:3100, but may vary depending on your setup) should bring up the typical Stoplight login screen:

The Stoplight login screen

If you run into any errors, be sure to check the container log output with docker-compose logs to see what might have gone wrong.