Self Hosted

This tutorial shows how to deploy self-hosted GitNotebooks to a GitHub Enterprise account

Before we start the tutorial

The tutorial is divided into several sections:

The goal is to create a set of environment variables that look like this:

BASE_URL=https://gitnotebooks.mycompany.com
GITHUB_BASE_URL=https://github.mycompany.com
GITHUB_APP_IDENTIFIER=499732
GITHUB_CLIENT_SECRET=0f2e9190d598624847d2b259b5b567cf981d5072
GITHUB_PRIVATE_KEY=LS0tLS12dJQkFNB2s3emt2dBS0nRzbXQzVCRUdJUUVBc2pzNFRSb0ErUVdWdMbFZUeklyQmtkYkZFURSBTXZiZnlqQW9FHU0EgUFJJVk1YWZWUGxaV1NOKUTiBSbNi9HOUTV0YLRVktLS0tLQpCg==
GITHUB_WEBHOOK_SECRET=d1ae70aaf90bd909ce44927350d9aba8c1136d34
GITHUB_APP_URL=https://github.mycompany.com/apps/gitnotebooks-self-hosted
GITHUB_BASE_URL=https://github.com
GITHUB_CLIENT_ID=Iv1.fed2b15afabbc1a6
DATABASE_URL=postgresql://postgres:somepassword@git-notebooks.database.url.rds.amazonaws.com:5432/postgres
AES_ENCRYPTION_KEY=X9CSf8y7Pw9dYSJNUwV4L7jUqH42/Mb27pHBRTUWceI=
ENTERPRISE=true

In this tutorial, we’ll note an environment variables with this notation: SOME_ENV_VAR

Prerequisites

We’ll assume that you have enough permission to create a new GitHub app and a Postgres database. We’ll also assume that you have access to the private GitNotebooks container image.

If you have not yet received the GitNotebooks container image, you can do so by filling out this form: Self-hosted signup

Choosing an Endpoint

Whether you’re hosting this service at a URL like gitnotebooks.yourcompanydomain.com, or a private IP address, it’s helpful to decide what the endpoint will be up front. We will refer to this URL as the BASE_URL.

# Example base URL
BASE_URL="https://gitnotebooks.yourcompanydomain.com"

Creating a GitHub App

First, click New GitHub App. If you need help finding this button, the GitHub docs can help: Registering a GitHub App Here’s how to fill out the form:

register GitNotebooks GitHub App 1 register GitNotebooks GitHub App 2 register GitNotebooks GitHub App 3 register GitNotebooks GitHub App 4 register GitNotebooks GitHub App 5

You should now have a GitHub App with the following settings:

  • GitHub App Name: GitNotebooks
  • Homepage URL: https://gitnotebook.com
  • Callback URL: https://gitnotebooks.your-domain.com/api/auth/callback/github
  • Post installation: https://gitnotebooks.your-domain.com/dashboard
  • Webhook URL: https://gitnotebooks.your-domain.com/api/event_handler
  • Webhook secret: A custom webhook seceret
  • Permissions
    • Contents: Read and write
    • Pull requests: Read and write
    • Email address: Read only
  • Subscribe to events:
    • Pull request

After creating the GitHub App

We'll need to collect some information for GitNotebooks to identify itself as the GitHub App.

Generate a new client secret GITHUB_CLIENT_SECRET

generate client secret

Generate a private key We will download the key, then convert it to base64.

download private key for GitHub App

Convert the key to base64.

cat path/to/your/key.pem | base64

Note the url of the public page GITHUB_APP_URL

This URL is used to direct users to add repos to the GitHub app installation.

public url link for GitHub App

Making it pretty (optional)

Finally, you can upload a logo which is used as the app's avatar.

Creating a database

Next, we need a Postgres database with the following specifications:

  • 1GB RAM
  • 20GiB storage
  • PostgreSQL 9.4 or higher
  • Username/Password authentication

We recommend that your database not be accessible to the internet, and restrict inbound connections to the web servers hosting the container over TCP port 5432.

Note the connection string, which is the DATABASE_URL

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE"

Reviewing the Environment Variables

We should have all the environment variables we need:

# From `Choosing and Endpoint`
BASE_URL=https://gitnotebooks.mycompany.com

# Your comapany's GitHub Enterprise URL
GITHUB_BASE_URL=https://github.mycompany.com

# From `Creating a GitHub App`
GITHUB_APP_IDENTIFIER=499732
GITHUB_CLIENT_ID=Iv1.fed2b15afabbc1a6
GITHUB_CLIENT_SECRET=0f2e9190d598624847d2b259b5b567cf981d5072
GITHUB_PRIVATE_KEY=LS0tLS12dJQkFNB2s3emt2dBS0nRzbXQzVCRUdJUUVBc2pzNFRSb0ErUVdWdMbFZUeklyQmtkYkZFURSBTXZiZnlqQW9FHU0EgUFJJVk1YWZWUGxaV1NOKUTiBSbNi9HOUTV0YLRVktLS0tLQpCg==
GITHUB_WEBHOOK_SECRET=d1ae70aaf90bd909ce44927350d9aba8c1136d34
GITHUB_APP_URL=https://github.mycompany.com/apps/gitnotebooks-self-hosted

# Base URL of your GitHub instance, if using GitHub Enterprise Cloud, use the following example:
GITHUB_BASE_URL=https://github.com

# From `Creating a database`
DATABASE_URL=postgresql://postgres:somepassword@git-notebooks.database.url.rds.amazonaws.com:5432/postgres

# Generate this value using `openssl rand -base64 32`
AES_ENCRYPTION_KEY=X9CSf8y7Pw9dYSJNUwV4L7jUqH42/Mb27pHBRTUWceI=

ENTERPRISE=true

You are now ready to deploy GitNotebooks Self Hosted.

Deploying a container

The final step is to deploy the GitNotebooks container image with these environment variables. Whle GitNotebooks Self Hosted will not make any network requests apart from GitHub, we recommend the following security settings:

  • Web application servers
    • Container environment variables stored as secrets (e.g. AWS Secrets Manager)
    • Outbound network traffic restrictred to GitHub and Database
    • Inbound traffic restricted to corpotate VPN
  • Database
    • Encrypted at rest
    • Require SSL connections from web server
    • Inbound restricted to web servers via TCP port 5432
    • No outbound network requests
  • Application load balancer
    • Restrict inbound requests to coroporate VPN and GitHub Webhooks
    • Restrict outbound requests to web application

GitNotebooks Enterprise Security

This page offers an overview of GitNotebooks security-related features. Note that while there are many ways to configure GitNotebooks we'll only discuss the most secure configuration here.

Everything on this page applies to both self-hosted and managed Enterprise instances. A managed instance is just a self-hosted instance that we run for you (outside your VPN), configured as follows:

  • GitNotebooks web application servers and image storage run in AWS.
  • All secrets are stored in AWS Secret Manager, with audit trails enabled.
  • All data is stored in RDS with TLS communication required, data encypted at rest, not internet-facing

Architecture

This is the recommended architecture for a self-hosted deployment, which is also used for the managed Enterprise instances. The diagram summarizes the various components and how they communicate:

Architecture diagram

If using GitHub Enterprise Server, all network traffic remains within your corporate VPN.

Note: While we replicate the deployment across two Availability Zones for Managed Enterprise accounts, this is not strictly necessary for Self-Hosted.

Network Security

This is the recommended network security configuration for a self-hosted deployment, which is also used for the managed Enterprise instances. The table summarizes the inbound/outbound rules for each components as well as their internet configuration. In the case of Self-Hosted with GitHub Server, the application load balancer should not be internet facing, and only accept requests within the corporate VPN.

ServiceInboundOutboundInternet-FacingInternet Access
Application Load BalancerTCP:80 (redirect to 443)
TCP:443 GitHub and Corporate VPN
TCP:3000 Web application security groupYesN/A
Web application instanceTCP:3000 ALB security groupTCP:443 GitHub
TCP:443 Bugsnag
NoYes
RDS PostgresTCP:5432 Web application security groupNoneNoNo

Data Encryption

Data Encyption At Rest

There are two pieces of sensitive data stored by the application. Both are AES encypted at rest:

  • GitHub Auth Tokens
  • Comment Body

In the case of self-hosted, the encyption key is generated by you. It's recommended that this key be stored in a secrets manager and mounted into the container image by reference.

Data Encyption in Transit

For Managed Enterprise accounts, the following components use TLS encyption:

  • Application Load Balancer
  • Database
  • GitHub Enterprise

It is recommended that network traffic be encrypted similarly for self-hosted deployments.

Authentication

GitNotebooks relies entirely on GitHub Enterprise (GHE) for authentication. If you've configured your GHE instance to use SSO via SAML then GitNotebooks will use that too. There are no separate local user accounts to maintain within Gitnotebooks.

When a user signs in, GitNotebooks obtains and stores an OAuth token that lets it operatore on the user's behalf within the scopes that were granted. GitNotebooks needs the following scopes:

  • Repo (read and write)
  • Pull requests (write)
  • Metadata (read and write)

Authorization

Authorizations in GitNotebooks are inferred from the permissions granted to users in GHE, i.e. repository read/write/admin and organization owner. There are no separate roles or authorizations maintained within GitNotebooks.

Data Flow

The following diagrams illustrate the two primary workflows of GitNotebooks

Login Data Flow Review Data Flow

Frequently Asked Questions

Does the self-hosted application send any network requests to GitNotebooks?

No, self-hosted installations do not make any network requests except to GitHub. If hosting GitHub Enterprise Server, all network traffic remains within your VPN. It is recommended that you restrict network requests from the application server to your GitHub Enterprise Cloud environment if using GitHub Enterprise Cloud.

Does GitNotebooks have access to any Self Hosted data?

No, all data is stored within your own cloud environment. GitNotebooks does not have access to any of your data.