Installing and Running Launchpad

Page Contents

Data Persistence
Run Launchpad with a Given User
Terminating SSL/TLS Connections
Stardog Unit Usage Tracking (Beta)

This is the general guide to getting Launchpad up and running. For more detailed information, see the Launchpad Configuration guide.

Prerequisites
- Docker
- An SSO provider to log users in with (e.g. Microsoft Entra)
- A Stardog endpoint to connect to
Pull the Launchpad image from Docker Hub.
```
docker pull stardog/launchpad:v4.0.0
```
Pinning an explicit version tag, as above, is recommended so that restarting or rebuilding never changes the version you are running. The current tag always points to the latest release if you would rather track it.

Existing customers with access to Stardog’s private JFrog Artifactory can continue to pull Launchpad images from stardog-stardog-apps.jfrog.io/launchpad:<tag>. Authenticate with docker login stardog-stardog-apps.jfrog.io before pulling if your environment still relies on that registry.
Configure Launchpad and optionally your Stardog servers.
- Launchpad must be configured with a provider to log users in to the Launchpad console.
  - Launchpad supports several SSO login providers.
  - For testing, Launchpad also supports configuring a shared basic authentication user.
- Launchpad can optionally be configured with “SSO Connections”, allowing users to use SSO to connect to Stardog endpoints that have also been configured to accept JWT tokens from the SSO provider. Without SSO Connections, users will need to manually enter their Stardog credentials to connect to Stardog endpoints.
  - The SSO provider for connections can be from the same provider as the main SSO provider or a different provider. They should, however, be different applications in the SSO provider. For example, Microsoft Entra can be used as the Launchpad SSO (main) provider and also as the SSO provider for connections, but Launchpad and each of the SSO connections (the Stardog endpoints) should be different “App Registrations” in Microsoft Entra.
  - The SSO provider must be configured to issue JWT tokens that can be used to authenticate with Stardog.
- See Login Providers for more information on configuring providers.
Create and run the Launchpad container
```
 docker run \
   --env-file /path/to/launchpad/.env.launchpad \
   -p 8080:8080 \
   -v /path/to/launchpad/data:/data \
   stardog/launchpad:<tag>
```
- The --env-file flag should point to a file containing the environment variables for Launchpad. See the Launchpad Configuration section for more information.
- Use the same <tag> you pulled in the previous step to run the expected Launchpad version.
- The container exposes port 8080, which can be mapped to any port on the host machine.
- /data is the directory where Launchpad will persist data. This should be mounted to a volume for persistence.
Starting in v3.9.0, the Launchpad container runs as a non-root user (launchpad, UID 100001) by default. Previously the default was root (UID 0).

Upgrading from v3.8.x or earlier? If your /data volume is owned by root, the container will fail to start. To fix this, either:
- Change ownership on the host: sudo chown -R 100001:100001 /path/to/launchpad/data, or
- Continue running as root by passing --user 0:0 to docker run.
The container’s entrypoint prints this guidance if it detects an unwritable /data directory.

See Run Launchpad with a Given User for more on running with a custom UID.
Access Launchpad in your browser at the BASE_URL you configured.

Data Persistence

As noted above, Launchpad persists data to a local directory that should be mounted to a volume for persistence. This is done by mounting a volume to the /data directory in the Launchpad container.

The volume mounted should be owned and writable by the user that is running the Launchpad container. See Run Launchpad with a Given User for more information.

Run Launchpad with a Given User

You can run Launchpad with a given user by using the --user flag in the docker run command. This is useful if you want to run Launchpad as a specific user instead of the default launchpad user (UID 100001).

docker run \
  --user <user_id>:<group_id> \
  --env-file /path/to/launchpad/.env.launchpad \
  -p 8080:8080 \
  -v /path/to/launchpad/data:/data \
  stardog/launchpad:<tag>

When using the --user flag, the user id and group id must have the appropriate permissions to the directory mounted to /data. This is the directory where Launchpad will persist data. If the user id and group id do not have the appropriate permissions, you may encounter permission errors when trying to access the data in Launchpad. This is especially important if you are running Launchpad on Linux, as Linux handles file permissions differently than macOS for Docker containers.

The following error may be seen in the logs if the user does not have the appropriate permissions to the /data directory:

django.db.utils.OperationalError: unable to open database file

To fix this, you can change the ownership of the directory on the host machine mounted to /data to the user id and group id that you are using to run the Launchpad container. You can do this by running the following command on the host machine:

sudo chown <user_id>:<group_id> /path/to/launchpad/data

Similarly in Kubernetes, you can set the securityContext for the Launchpad pod to run as a specific user.

securityContext:
 runAsNonRoot: true
 runAsUser: 100001
 runAsGroup: 100001

Terminating SSL/TLS Connections

By default, Launchpad listens for HTTP connections on port 8080. Starting with Launchpad v3.7.0, you can configure Launchpad to support SSL/TLS connections without the use of an external reverse proxy.

To enable SSL/TLS termination mode in Launchpad, add the following three environment variables to Launchpad’s configuration:

SSL_ENABLED=true
SSL_CERTIFICATE_FILE=<path_in_the_launchpad_container_to_launchpad-ssl.cert.pem>
SSL_PRIVATE_KEY_FILE=<path_in_the_launchpad_container_to_launchpad-ssl.key.pem>

You need to provide Launchpad with a certificate and the corresponding private key file so that it can terminate SSL/TLS connections originating from a user’s web browser. The certificate and private key files must be included in Launchpad’s container; this can be done by mounting the directory containing the files as a volume in Launchpad’s container.

Launchpad uses Nginx internally as the reverse proxy when SSL_ENABLED=true. The Nginx website provides additional information about its certificate requirements.

When SSL_ENABLED=true in Launchpad’s configuration, Launchpad listens for HTTPS connections on port 8443. You will also need to adjust the value of the BASE_URL environment variable in Launchpad’s configuration, setting it to match the HTTPS-enabled URL that a user will access from the web browser.

Stardog Unit Usage Tracking (Beta)

Launchpad can track and report Stardog Unit (SDU) usage for connections to Stardog servers (v12.0.0+). Usage is aggregated from the Stardog Platform and, where applicable, from Voicebox usage events. Users can download a day-wise usage report as a CSV.

Voicebox Usage

Launchpad collects Voicebox usage daily at 1:30 AM UTC for the previous calendar day (midnight-to-midnight UTC). This includes both in-app Voicebox usage and Voicebox public API endpoints. Platform SDU data is not included in this run; it is synced on demand when users run Sync Stardog Unit Usage.

Sync Platform Usage

Sync pulls SDU usage from the Stardog Platform for the connection, and stores it in Launchpad’s usage metrics. The Sync option is disabled while a sync is in progress or when data is already synced through yesterday midnight UTC.

Download Report

The downloaded report combines platform SDU data (synced from the Stardog server) and Voicebox usage. Usage is aggregated across all connections that share the same endpoint. Once both platform and Voicebox usage data are available for an endpoint, user can download a consolidated report.

Data Persistence
Run Launchpad with a Given User
Terminating SSL/TLS Connections
Stardog Unit Usage Tracking (Beta)