mirror of
https://github.com/mastodon/chart
synced 2025-05-18 13:03:21 +00:00
123 lines
4.7 KiB
Markdown
123 lines
4.7 KiB
Markdown
# Introduction
|
||
|
||
This is a [Helm](https://helm.sh/) chart for installing Mastodon on a Kubernetes cluster. This is a fork of the official mastodon helm chart, as the upstream repo had some issues with security and order of operations.
|
||
The basic usage is:
|
||
|
||
1. edit `values.yaml` or create a separate yaml file for custom values
|
||
2. `helm repo add https://jessebot.github.io/mastodon-helm-chart`
|
||
3. `helm install --namespace mastodon --create-namespace mastodon -f path/to/values.yaml`
|
||
|
||
This chart is tested with k8s 1.26+ and helm 3.6.0+.
|
||
|
||
Known caveats: Currently in chart version `4.0.8`, you need to run postgresql and redis helm charts independently of this one. This is because there's a helm hook job called db-migrate that I 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 here and let me 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](https://min.io/docs/minio/kubernetes/upstream/index.html)
|
||
then you need to set the pod affinity so the web and sidekiq pods are scheduled to the same node.
|
||
|
||
Example configuration:
|
||
```yaml
|
||
podAffinity:
|
||
requiredDuringSchedulingIgnoredDuringExecution:
|
||
- labelSelector:
|
||
matchExpressions:
|
||
- key: app.kubernetes.io/part-of
|
||
operator: In
|
||
values:
|
||
- rails
|
||
topologyKey: kubernetes.io/hostname
|
||
```
|
||
|
||
# Administration
|
||
|
||
You can run [admin CLI](https://docs.joinmastodon.org/admin/tootctl/) commands in the web deployment.
|
||
|
||
```bash
|
||
kubectl -n mastodon exec -it deployment/mastodon-web -- bash
|
||
tootctl accounts modify admin --reset-password
|
||
```
|
||
|
||
or
|
||
```bash
|
||
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.
|
||
|
||
# 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.
|
||
```yaml
|
||
ingress:
|
||
annotations:
|
||
kubernetes.io/ingress.class: nginx
|
||
kubernetes.io/tls-acme: "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
|
||
`kubernetes.io/tls-acme` to `ingress.annotations` in your `values.yaml`.
|
||
|
||
# Upgrades in 2.0.0
|
||
|
||
## Fixed labels
|
||
Because of the changes in [#19706](https://github.com/mastodon/mastodon/pull/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.
|
||
```yaml
|
||
postgresql:
|
||
auth:
|
||
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```
|