Mastodon Helm Chart

small-hack/mastodon-helm-chart is a fork of the official mastodon helm chart for installing Mastodon on a Kubernetes cluster. We'll maintain this at least till some of the security features PRs are merged in the upstream repo and the upstream repo is officially released in a way that you can run helm repo add. The basic usage for our chart is:

# add the chart repo to your helm repos
helm repo add mastodon https://small-hack.github.io/mastodon-helm-chart

# download the values.yaml and edit it with your own values such as YOUR hostname
helm show values mastodon/mastodon > values.yaml

# install the chart
helm install --namespace mastodon --create-namespace mastodon/mastodon --values values.yaml

This chart is tested with k8s v1.31+ and helm 3.16.0+.

Known caveats for this chart

Currently, you need to run PostgreSQL and Redis (or Valkey) helm charts independently of this one, because there's a helm hook job called db-migrate that we can't figure out how to make run after the dependency charts are fully installed, but before everything else. If you know the answer to this, please open an issue/pr here and let us know!

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. If you're upgrading from a version before 3.x to a version before 4.x, please see the upstream mastodon chart as that is before our fork.

Note

If bitnami merges in our volumeMount fix and fixes #20904 and #20902 and everything else works, we may be less active on this helm chart. Feel free to take what you need and we'll still eventually get around to issues and pull requests regardless :)

Note

UPDATE: Acorrding to mastodon/chart#129 mastodon should have a new official helm chart at mastodon/helm-charts but as of Oct 21, 2024 it is not yet ready so we'll continue to maintain this chart :)