Skip to main content

Self-Hosted Installation

This guide will walk you through installing Massdriver's self-hosted version using our Helm chart. The self-hosted version of Massdriver is great for teams that want the all the features of our platform in a private cloud environment.

Prerequisites​

Before beginning the installation, ensure you have the following requirements:

Infrastructure Requirements​

  • Kubernetes cluster running version 1.25 or higher
  • PostgreSQL database version 13.25 or higher
    • The following PostgresQL extensions are required to be installed: citext, uuid-ossp, pg_stat_statements
  • SMTP server for account management and email alerts
  • Domain name where you'll host your Massdriver instance

Access Requirements​

Required from Massdriver Team

You'll need to obtain the following from the Massdriver team before installation:

  • DockerHub access token - Required to pull our application images
  • License key - Required for the application to run

Contact us to request these credentials for your self-hosted deployment.

Dependencies (Included)​

The following dependencies are automatically included in the Helm chart:

  • S3-compatible object storage (via MinIO)
  • Argo Workflows for executing deployments

Installation Steps​

Step 1: Add the Helm Repository​

First, add the Massdriver Helm repository:

helm repo add massdriver https://massdriver-cloud.github.io/helm-charts
helm repo update

Step 2: Download and Configure Values​

Download the default values file to customize for your environment:

curl -o values-custom.yaml https://raw.githubusercontent.com/massdriver-cloud/helm-charts/main/charts/massdriver/values-example.yaml
note

This command downloads the values-example.yaml file, which is available for convenience as it only contains a subset of the Massdriver helm chart values - specifically the values which are mandatory and/or commonly modified. The full set of values is available in the chart's values.yaml file here.

Step 3: Configure Required Values​

Edit your values-custom.yaml file to provide the necessary configuration. Focus on the top section between the # BEGIN Mandatory values and # END Global variables comments:

Required Configuration​

  1. PostgreSQL Connection

    postgresql:
      username: "massdriver_user"
      password: "your-secure-password"
      hostname: "your-postgres-host"
      port: 5432

  2. SMTP Configuration

    smtp:
      username: "your-smtp-username"
      password: "your-smtp-password"
      hostname: "your-smtp-server"
      port: 587
      from: "noreply@your-domain.com"

  3. Domain Configuration

    domain: "your-domain.com"  # e.g., "massdriver.example.com"

  4. Docker Registry Access

    dockerhub:
      accessToken: "your-dockerhub-token"  # Provided by Massdriver team

  5. License Key

    licenseKey: "your-license-key"  # Provided by Massdriver team
Custom Release Name (Optional)

If you plan to use a different release name than massdriver, search for "release name" in the values file and update the associated values accordingly.

Step 4: Configure Ingress and TLS​

The ingress configuration requires special attention for security:

Ingress Controller​

Update the massdriver.ingress section in your values-custom.yaml file:

massdriver:
  ingress:
    enabled: true
    ingressClassName: "nginx"  # Update to match your ingress controller, or leave blank to use the default ingress controller

TLS Configuration​

Massdriver requires a TLS certificate valid for the following subdomains:

  • app.<your-domain>
  • api.<your-domain>
  • identity.<your-domain>

Option 1: Using cert-manager (Recommended)

If you have cert-manager running in the Kubernetes cluster where you are installing Massdriver, and it is configured to manage the domain you specified in the domain value earlier, uncomment and configure the cert-manager annotation:

massdriver:
  ingress:
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"  # Your issuer name
    tls:
      createSecret: true

Option 2: Provide Your Own Certificate Managed By Helm

If you have your own TLS certificate, you can create and manage it via the helm chart by configuring it in the values file:

massdriver:
  ingress:
    tls:
      createSecret: true
      certificate: |
        -----BEGIN CERTIFICATE-----
        # Your certificate content
        -----END CERTIFICATE-----
      key: |
        -----BEGIN PRIVATE KEY-----
        # Your private key content
        -----END PRIVATE KEY-----

Option 3: Provide Your Own Certificate Managed Manually

If you prefer to manage the TLS certificate manually, you can create the TLS secret separately:

kubectl create secret tls massdriver-tls --cert=path/to/tls.crt --key=path/to/tls.key

and simply reference it in the values file:

massdriver:
  ingress:
    tls:
      createSecret: false
      secretName: massdriver-tls

Step 5: Install Massdriver​

Once your values file is configured, install Massdriver:

helm install massdriver massdriver/massdriver \
  -n massdriver \
  --create-namespace \
  -f values-custom.yaml

Step 6: Verify Installation​

Check that all pods are running:

kubectl get pods -n massdriver

Verify that your ingress is configured correctly:

kubectl get ingress -n massdriver

Accessing Your Installation​

Once installed, you can access Massdriver at:

  • Main Application: https://app.<your-domain>
  • API: https://api.<your-domain>/api/graphiql

Updating Your Installation​

Massdriver periodically releases updates to the self-hosted chart. To update your installation:

  1. Update the Helm repository:

    helm repo update

  2. Upgrade your installation:

    helm upgrade massdriver massdriver/massdriver \
      -n massdriver \
      -f values-custom.yaml
Version Management

Always review the changelog before upgrading to check for changes that are required to values.yaml or other configuration settings.

Troubleshooting​

Common Issues​

Pods failing to start

  • Verify your DockerHub access token is correct
  • Check that your license key is valid
  • Ensure PostgreSQL connectivity

Ingress not working

  • Verify your ingress controller is running
  • Check that DNS is properly configured
  • Ensure TLS certificates are valid for all required subdomains

Database connection issues

  • Verify PostgreSQL credentials and connectivity
  • Ensure the database exists and the user has proper permissions

Getting Help​

For assistance with your self-hosted installation:

Next Steps​