Helm chart for Mastodon deployment in Kubernetes
Alternatives To Chart
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
2 months ago48agpl-3.0Mustache
Helm chart for Mastodon deployment in Kubernetes
2 days ago2Smarty
Kubernetes manifests for's Mastodon instance. Managed via ArgoCD, changes are auto-deployed to production.
Mastodon On Kubernetes15
8 months ago1HCL
Setting up Mastodon on DigitalOcean Kubernetes
6 years agomit
A Mastodon conf for Kubernetes / Google Container Engine
Kube Mastodon11
5 years ago
This repository contains everything you need to get a Mastodon server running on Kubernetes.
a month ago1, powered by Kubernetes, Flux and DigitalOcean.
Alternatives To Chart
Select To Compare

Alternative Project Comparisons


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 update
  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.6.0+.


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:

    - labelSelector:
          - key:
            operator: In
              - rails


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


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


Because database migrations are managed as a Job separate from the Rails and Sidekiq deployments, its 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.

Upgrades in 2.1.0

ingressClassName and tls-acme changes

The annotations previously defaulting to nginx have been removed and support for ingressClassName has been added.

  annotations: nginx "true"

To restore the old functionality simply add the above snippet to your values.yaml, but the recommendation is to replace these with ingress.ingressClassName and use cert-manager's issuer/cluster-issuer instead of tls-acme. If you're uncertain about your current setup leave ingressClassName empty and add to ingress.annotations in your values.yaml.

Upgrades in 2.0.0

Fixed labels

Because of the changes in #19706 the upgrade may fail with the following error: Error: UPGRADE FAILED: cannot patch "mastodon-sidekiq"

If you want an easy upgrade and you're comfortable with some downtime then simply delete the -sidekiq, -web, and -streaming Deployments manually.

If you require a no-downtime upgrade then:

  1. run helm template instead of helm upgrade
  2. Copy the new -web and -streaming services into services.yml
  3. Copy the new -web and -streaming deployments into deployments.yml
  4. Append -temp to the name of each deployment in deployments.yml
  5. kubectl apply -f deployments.yml then wait until all pods are ready
  6. kubectl apply -f services.yml
  7. Delete the old -sidekiq, -web, and -streaming deployments manually
  8. helm upgrade like normal
  9. kubectl delete -f deployments.yml to clear out the temporary deployments

PostgreSQL passwords

If you've previously installed the chart and you're having problems with postgres not accepting your password then make sure to set username to postgres and password and postgresPassword to the same passwords.

    username: postgres
    password: <same password>
    postgresPassword: <same password>

And make sure to set password to the same value as postgres-password in your mastodon-postgresql secret: kubectl edit secret mastodon-postgresql

Popular Kubernetes Projects
Popular Mastodon Projects
Popular Virtualization Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.