Hubs Server (Pubs)

The Pubs component serves and catalogs Hubs published through Stoplight.

Networking Details

The default ports for the Pubs component are TCP ports 8080 (HTTP), 8443 (HTTPS), and 9098 (HTTPS optional). All ports can be customized.

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

  • User Clients (on the public-facing ports, which default to 8080 and 8443)
  • API (on the private admin port, which defaults to 9098)
  • Tasker (on the private admin port, which defaults to 9098)

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

  • API

Component Dependencies

Pubs has no component dependencies.


Pubs 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.

Setting up the Package Repository

You can setup the Stoplight package repo by copying-and-pasting the contents below into a terminal:

# expose credentials to environment first

# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
name=Stoplight Package Repository

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

Installing the Pubs Package

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

sudo yum install pubs -y

Docker Installation

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

docker pull

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


To configure the Pubs component, you will need to provide connection details and runtime settings.



The http_bind variable denotes the bind address/port to use when serving HTTP traffic.

http_bind: ""


The https_bind variable denotes the bind address/port to use when serving HTTPS traffic.

https_bind: ""


The ssl_enabled variable denotes whether SSL should be enabled when serving Hub requests.

ssl_enabled: yes

If ssl_enabled is set to true, then HTTP requests will automatically be redirected to HTTPS.


The admin_bind variable denotes the address/port to bind to when serving the admin API.

admin_bind: ""


The admin_ssl_enabled variable denotes whether the admin API should accept connections over HTTPS (as opposed to HTTP).

admin_ssl_enabled: no


The admin_ssl_cert_path variable is the path to the SSL certificate to use when serving TLS over the admin API.

admin_ssl_cert_path: /path/to/cert

This configuration option has no effect if admin_ssl_enabled is not set to true


The admin_ssl_key_path variable is the path to the SSL key (matching the admin_ssl_cert_path option) to use when serving TLS over the admin API.

admin_ssl_key_path: /path/to/key

This configuration option has no effect if admin_ssl_enabled is not set to true


The admin_ip_whitelist variable is a list representing IP addresses that should be allowed to connect to the admin API.


If admin_ip_whitelist is not set, all IP addresses will be allowed to connect to the API.


The data_dir variable is the directory to use when storing builds, build metadata, and the pubs sqlite database.

data_dir: /var/lib/pubs


The static_ssl_domains variable can be used to serve static SSL certificates for specific domain requests.

  - domain: "*"
    cert-path: /path/to/example_com/certificate
    key-path: /path/to/example_com/key

Include a leading star (*) in the domain if the certificate is wildcarded (ie, * for a wildcard certificate on the domain).

RPM Package

The Pubs default configuration is located at the path:


Be sure to customize any variables as needed to match your environment before starting the Pubs service.

Any changes to the Pubs configuration requires a service restart in order to take effect.


The Pubs configuration can be mounted into a Docker container. As an example, if a Pubs configuration file is located on the host system at the path:


This file can be mounted into the running Pubs container using the -v argument.

docker run -v /data/pubs.yml:/etc/pubs/pubs.yml ...


RPM Package

To start the Pubs server, run the command:

sudo systemctl start pubs

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

sudo systemctl status pubs

Docker Installations

To start the Pubs container, use the command:

docker run \
	--restart on-failure \
	-v /path/to/pubs.yml:/etc/pubs/pubs.yml \
	-p 80:8080 \
	-p 443:8443 \
	-p 9098:9098 \

If started properly, the container should be marked with a healthy status after 30 seconds. Use the docker ps command to verify the container was started and is running properly.

Post-install Validations

Once the Pubs service is running, you can verify the installation was successful issuing an HTTP GET request to the /health URL on the HTTP admin port (set with admin_bind):

curl -v http://localhost:9098/health

Be sure to update the URL above to match your local installation

If Pubs was installed and configured properly, you will receive an HTTP 200 response back.