Docs

Self Hosted

Suggest Edits

Overview

OpsLevel has chosen to partner with Replicated to provide a superior installation & support experience for self-hosting a copy of the OpsLevel application.

Prerequisites

  • A license file provided by OpsLevel
  • A place to host the application (VM or Kubernetes cluster)
  • Admin access in various third party software to setup integrations

Application Architecture

Architecture

Install

Your OpsLevel account manager will provide your license and instructions for how to perform the installation depending on if you are using a VM or a Kubernetes cluster to host the application.

If you would like to know more about the installation methods you can read about them over at Replicated.

Replicated provides you with a Customer Admin Console to manage the lifecycle of the self-hosted OpsLevel application.

Getting Started with OpsLevel Self-Hosted Configuration

Once you have performed the installation and you have logged into the customer admin console, you will be asked to provide your license file before you can begin any of the configuration.

Customer Admin Console

If you have provided a valid license you will then be prompted with a configuration screen to supply any additional configuration for connecting to an external MySQL DB or integrating with third party software like GitHub, Jira, PagerDuty, etc.

Standard defaults have been provided for most critical infrastructure, so you do not need to adjust anything other than the Account Configuration to get started with most features. We recommend configuring your own infrastructure components before your production rollout and the configuration options are provided below.

Note: There are a few features which require configuration before they will be generally available in OpsLevel Self-Hosted installations:

  • Advanced search and Tech Docsrequire you to configure an Elasticsearch cluster that OpsLevel can communicate with.
  • Several integrations require an application or other object to be configured in the third party before you'll be able to use them:
    • Azure DevOps Git
    • BitBucket
    • Pagerduty
    • Slack

Each configuration section is described in greater detail below.

Configuration

Ingress

This section provides you with an easy way to generate a Kubernetes ingress manifest, which exposes the application frontend through your cluster’s ingress controller.

The Ingress Subdomain and Ingress Domain are used to configure the Kubernetes ingress resource and to allow the application to perform link generation for emails.

The Ingress Annotations section must be in YAML format and will be applied to the Kubernetes ingress. There are two default annotations that we recommend to help protect the application from large payloads that could cause the application to consume excessive memory. If you do intend to send larger payloads, then please increase this amount.

MySQL

By default, the installation creates a MySQL container alongside the application for getting started quickly.

This is not recommended for production and as such, this section provides you with the detailed configuration needed to allow the application to connect to an “external” MySQL database that has been hardened for production and is monitored by you.

The MySQL database is where all of the data of the application is stored. If this database is destroyed, all of the data within OpsLevel is also destroyed. We recommend you setup regular backups.

There are a handful of MySQL parameters that need to be set that we have enumerated here, but do also note that we have configured preflight checks to ensure the database OpsLevel connects to will work properly.

    [mysqld]
    init_connect='SET collation_connection = utf8mb4_unicode_ci,NAMES utf8mb4'
    character_set_server = 'utf8mb4'
    collation_server = 'utf8mb4_unicode_ci'

    [client]
    default_character_set = 'utf8mb4'

Our application is configured to perform any pending migrations on this database at startup. Please be aware that this is not an “online” process, and as such may lock the database for a period of time while the migrations complete, thereby preventing use of the application. Note: this is something we are looking into changing in the future.

Redis

By default, the installation creates a container of Redis alongside the application for the purpose of getting started quickly. This is not recommended for production and as such, this section provides you with the configuration needed to allow the application to connect to an “external” Redis database that has been hardened for production and is monitored by you.

The Redis database is used to store pending asynchronous jobs waiting to be processed. If this database is destroyed all that is lost is pending jobs. For the most part many asynchronous tasks will be re-enqueued at a later time, but there are a few cases where losing the job means that specific data that was ingested will never be processed.

Email

This section allows you to configure SMTP settings so that the application may send emails. It is recommended that you give the application access to send email so you may receive the following types of emails:

  • User Invite
  • Password Reset

Elasticsearch

This section allows you to connect an Elasticsearch cluster to OpsLevel to power features related to improved Search and Tech Docs.

When enabling ElasticSearch, OpsLevel requires a full connection url as the Elasticsearch Hostname following the https://<username>:<password>@<hostname>:<port> format. For example: https://elastic:[email protected]:9200

Suggested Configuration

OpsLevel expects that your Elasticsearch cluster version is 8.4.2 or higher. If you don't have an Elasticsearch cluster available, we recommend using a deployment provided by [Elastic](https://www.elastic.co/elasticsearch/) directly.

Integration Configuration

The following third party integrations will require that the application is exposed to the Internet so that the third party software can send data to the application (usually in the form of a webhook).

GitHub Cloud

If you use GitHub Cloud and would like to use the GitHub integration within the application you will need to create your own GitHub App.

To create a GitHub App follow these instructions. Then provide the configuration options which can be found on the settings page of the created GitHub App.

Post Installation Settings

The Setup URL should be set to <Self-Hosted OpsLevel Domain>/integrations/github/finish_setup

Webhook Settings

Webhooks should be Active for the application.

  1. The Webhook URL should be set to <Self-Hosted OpsLevel Domain>/integrations/github/webhook
  2. The Webhook Secret should be copied to be used the Configuration settings in Replicated for Github Cloud
  3. SSL Verification should be enabled.

You can refer to the image below as a reference for Post Installation and Webhook settings:

Permissions Settings

OpsLevel expects the following Repository Permissions:

  • Administration: Read and Write
  • Checks: Read and Write
  • Contents: Read and Write
  • Metadata: Read Only
  • Pull Requests: Read and Write

Subscriptions Settings

OpsLevel also needs the following Subscriptions:

  • Pull Requests
  • Push
  • Repository

You can refer to the image below to view the required settings in the GitHub configuration page:

Gitlab Cloud

If you use Gitlab Cloud and would like to use the Gitlab integration within the application you will need to create a User Owned App.

To create a User Owned Gitlab App follow these instructions. OpsLevel requires the following settings:

  1. You will need to ensure that /integrations/gitlab/finish_setup has been added to the redirect uri.
  2. The app should have Confidential enabled.
  3. The following scopes:
    - api
    - read_repository
    - write_repository

You can refer to the image below to view the required settings in the GitLab configuration page:

Bitbucket Cloud

If you use Bitbucket Cloud and would like to use the Bitbucket integration within the application you will need to create a Bitbucket Webhook

To create a Bitbucket Webhook follow these instructions.

Azure DevOps Git

If you use Azure DevOps Git Repositories and would like to use the Azure DevOps Git integration with Self-Hosted OpsLevel, you will need to create an Azure DevOps OAuth2 application.

In order to register a new application and integrate OpsLevel successfully, your Azure DevOps user must have access to View and Edit Subscriptions. This access is granted by the Project Administrators group which is a built-in, project-level group.

When logged in with the correct permissions, navigate here to create the application.

Many of the Company and Application settings are optional and will not impact the integration, however OpsLevel requires the following settings:

  1. The Application website should be your OpsLevel Self-Hosted domain
  2. The Authorization Callback URL should be <Self-Hosted OpsLevel Domain>/integrations/azure_devops/finish_setup

You can refer to the screenshot below for details:

In order for the integration to function, OpsLevel requires the following scopes:

  • Identity (read)
  • Code (read)
  • Project and team (read)

See the screenshot below for reference:

Once the application is created, copy the App ID and Client Secret for use in Replicated's Self-Hosted OpsLevel configuration.

PagerDuty (US)

If you use PagerDuty and would like to use the PagerDuty integration within the application you will need to create your own PagerDuty App.

To create a PagerDuty App follow these instructions to setup the application.

Create PagerDuty App

Once the app is created you’ll need to add OAuth2 functionality. Enter the callback url of your exposed OpsLevel application and click save. Copy the Client ID and Client Secret and set them in the configuration.

Preflight Checks

Once you have completed all the needed configurations you can click next and the preflight checks will begin to run. The purpose of these checks is to ensure the provided configuration and application hosting location have the best chance of starting up correctly. If any of the preflight checks fail you will need to fix them before completing the installation.

GraphQL

Once you have completed the install and the application is running there are many ways to interact with it. One such way is through our GraphQL API. We have many tools that are built ontop of our GraphQL API such as our CLI, Terraform Provider, Kubernetes Sync and if you need something a bit more low level you can even use our client library opslevel-go. You can also use an in browser graphical interface to playing with the API at the endpoint /graphiql - https://self-hosted.example.com/graphiql

Each of these tools by default is configured to talk to our SaaS GraphQL API - https://app.opslevel.com/graphql

Each of these tools has way to override this default usually in the form of an environment variable OPSLEVEL_API_URL or a command line flat \--api-url. The following are examples for each.

CLI

opslevel --api-url=https://self-hosted.example.com list services

Kubernetes Sync

kubectl opslevel --api-url=https://self-hosted.example.com service preview

Terraform Provider

provider "opslevel" {
  api_url = "https://self-hosted.example.com"
}

If you are having trouble setting up your self-hosted OpsLevel in any way, send us an email at [email protected] and we’ll be happy to help debug and diagnose any issues.

Updated 26 days ago