Introduction

This is a Helm chart for installing Mastodon into a Kubernetes cluster. The basic usage is:

1. edit values.yaml or create a separate yaml file for custom values
2. helm dep install
3. helm install --namespace mastodon --create-namespace my-mastodon ./ -f path/to/additional/values.yaml

This chart is tested with k8s 1.21+ and helm 3.8.0+.

⚠️ NOTICE ⚠️: This chart is deprecated

As of the release of Mastodon v4.6.0, this chart is now deprecated, and will no longer receive new features. It will continue to be updated with new Mastodon releases until 2026-12-31.

We encourage everyone to use our new helm chart going forward. Please refer to the Migration Guide for instructions on how to begin using the new chart.

Configuration

The variables that must be configured are:

• password and keys in the mastodon.secrets, postgresql, and redis groups; if left blank, some of those values will be autogenerated, but will not persist across upgrades.

• SMTP settings for your mailer in the mastodon.smtp group.

If your PersistentVolumeClaim is ReadWriteOnce and you're unable to use a S3-compatible service or run a self-hosted compatible service like Minio then you need to set the pod affinity so the web and sidekiq pods are scheduled to the same node.

Example configuration:

podAffinity:
  requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchExpressions:
          - key: app.kubernetes.io/part-of
            operator: In
            values:
              - rails
      topologyKey: kubernetes.io/hostname

Administration

You can run admin CLI commands in the web deployment.

kubectl -n mastodon exec -it deployment/mastodon-web -- bash
tootctl accounts modify admin --reset-password

or

kubectl -n mastodon exec -it deployment/mastodon-web -- tootctl accounts modify admin --reset-password

Missing features

Currently this chart does not support:

• Hidden services
• Swift

Upgrading

Because database migrations are managed as a Job separate from the Rails and Sidekiq deployments, it’s possible they will occur in the wrong order. After upgrading Mastodon versions, it may sometimes be necessary to manually delete the Rails and Sidekiq pods so that they are recreated against the latest migration.