### Install Mastodon Chart from Source Source: https://context7.com/mastodon/chart/llms.txt Installs the Mastodon chart and its dependencies, requiring specific secret overrides for security and functionality. Ensure Helm dependencies are updated before installation. ```bash helm dep update helm install my-mastodon . \ --namespace mastodon \ --create-namespace \ --set mastodon.local_domain=social.example.com \ --set mastodon.secrets.secret_key_base="$(openssl rand -hex 64)" \ --set mastodon.secrets.otp_secret="$(openssl rand -hex 64)" \ --set mastodon.secrets.vapid.private_key="" \ --set mastodon.secrets.vapid.public_key="" \ --set mastodon.secrets.activeRecordEncryption.primaryKey="$(openssl rand -hex 32)" \ --set mastodon.secrets.activeRecordEncryption.deterministicKey="$(openssl rand -hex 32)" \ --set mastodon.secrets.activeRecordEncryption.keyDerivationSalt="$(openssl rand -hex 32)" \ --set postgresql.auth.password="db-password" \ --set redis.auth.password="redis-password" \ --set mastodon.smtp.server=smtp.mailgun.org \ --set mastodon.smtp.from_address=notifications@example.com ``` -------------------------------- ### Install Mastodon with Helm Source: https://github.com/mastodon/chart/blob/main/README.md Basic installation command for the Mastodon Helm chart. Ensure `values.yaml` is configured or an additional values file is provided. ```bash helm install --namespace mastodon --create-namespace my-mastodon ./ -f path/to/additional/values.yaml ``` -------------------------------- ### Test Mastodon Helm chart locally Source: https://context7.com/mastodon/chart/llms.txt Commands for linting, rendering, validating, and installing the Mastodon Helm chart locally. Requires `helm` CLI and a local Kubernetes cluster for full install tests. ```bash # Lint the chart helm lint . --values dev-values.yaml ``` ```bash # Render templates to disk for inspection helm template my-mastodon . \ --values dev-values.yaml \ --output-dir /tmp/rendered-mastodon ``` ```bash # Validate rendered manifests against a live cluster API server helm template --validate my-mastodon . \ --values dev-values.yaml ``` ```bash # Full install test (requires k3s or similar local cluster) helm install mastodon . \ --values dev-values.yaml \ --timeout 15m ``` -------------------------------- ### Install Mastodon Chart with Custom Values Source: https://context7.com/mastodon/chart/llms.txt Deploys the Mastodon chart using a custom values file for production configurations. This method allows for pre-defined secrets and SMTP settings. ```yaml mastodon: local_domain: social.example.com secrets: existingSecret: "mastodon-app-secrets" # pre-created k8s Secret smtp: server: smtp.mailgun.org port: 587 from_address: notifications@example.com existingSecret: "mastodon-smtp-secret" # keys: login, password postgresql: auth: password: "" existingSecret: "mastodon-pg-secret" redis: auth: existingSecret: "mastodon-redis-secret" ``` ```bash helm install my-mastodon . \ --namespace mastodon \ --create-namespace \ -f values-prod.yaml ``` -------------------------------- ### Configure Pod Affinity in Helm Chart Source: https://github.com/mastodon/chart/blob/main/README.md Example configuration for setting pod affinity, required when using `ReadWriteOnce` PersistentVolumeClaims and not using S3-compatible storage. ```yaml podAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchExpressions: - key: app.kubernetes.io/part-of operator: In values: - rails topologyKey: kubernetes.io/hostname ``` -------------------------------- ### Get Application URL with NodePort Service Source: https://github.com/mastodon/chart/blob/main/templates/NOTES.txt For NodePort services, this script exports the NodePort and Node IP, then constructs the application URL. It assumes a single service port. ```bash export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "mastodon.fullname" . }}) export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}") echo http://$NODE_IP:$NODE_PORT ``` -------------------------------- ### Get Application URL with LoadBalancer Service Source: https://github.com/mastodon/chart/blob/main/templates/NOTES.txt This snippet retrieves the LoadBalancer IP address and constructs the application URL. Note that it may take time for the LoadBalancer IP to become available. Use 'kubectl get svc -w' to monitor. ```bash export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "mastodon.fullname" . }} --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}") echo http://$SERVICE_IP:{{ .Values.service.port }} ``` -------------------------------- ### Get Application URL with Ingress Enabled Source: https://github.com/mastodon/chart/blob/main/templates/NOTES.txt When Ingress is enabled, this template generates the application URL based on configured hosts and paths. Ensure your Ingress controller is properly set up. ```go-template {{- if .Values.ingress.enabled }} {{- range $host := .Values.ingress.hosts }} {{- range .paths }} http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }} {{- end }} {{- end }} {{- end }} ``` -------------------------------- ### Retrieve Generated Password or Reset Admin Password Source: https://context7.com/mastodon/chart/llms.txt Commands to retrieve the generated admin password from job logs after installation or to reset the password at any time using `kubectl`. ```bash # After install, retrieve the generated password: # kubectl -n mastodon logs job/my-mastodon-create-admin # Or reset the password at any time: # kubectl -n mastodon exec -it deployment/my-mastodon-web -- \ # tootctl accounts modify admin --reset-password ``` -------------------------------- ### Configure Initial Admin Account Job Source: https://context7.com/mastodon/chart/llms.txt Set up a `post-install` Helm Hook Job to create the first Owner-role admin account using `tootctl accounts create`. Configure `enabled`, `username`, `email`, and `nodeSelector`. ```yaml mastodon: createAdmin: enabled: true username: admin email: admin@example.com nodeSelector: {} ``` -------------------------------- ### Configure Database Lifecycle Jobs Source: https://context7.com/mastodon/chart/llms.txt Manage database schema creation, migrations, and search index rebuilding using Helm pre-install/pre-upgrade Jobs. Configure `dbPrepare`, `dbMigrate`, `deploySearch`, and `s3Upload` hooks as needed. ```yaml mastodon: hooks: # Runs on `helm install` — creates the initial DB schema. # Disable for GitOps tools (Argo CD) that don't distinguish install vs upgrade. dbPrepare: enabled: true # Runs on `helm upgrade` — applies pending Rails migrations. dbMigrate: enabled: true # Rebuild Elasticsearch indices — expensive, enable only when required. deploySearch: enabled: false # enable once per upgrade when needed: --set mastodon.hooks.deploySearch.enabled=true resetChewy: true only: "" # optionally target one index: accounts, tags, statuses, etc. concurrency: 5 resources: requests: cpu: 250m memory: 256Mi limits: cpu: 500m # Pre-upgrade: upload compiled assets to S3 to avoid serving stale files. s3Upload: enabled: true endpoint: https://s3.us-east-1.amazonaws.com bucket: mastodon-assets acl: public-read secretRef: name: mastodon-s3-secret keys: accesKeyId: access-key-id secretAccessKey: secret-access-key ``` -------------------------------- ### Configure Node.js Streaming Server Deployment Source: https://context7.com/mastodon/chart/llms.txt Sets up the real-time streaming API server. Uses a separate image and supports extra CA certificates for self-signed database TLS. Configure worker count based on allocated CPU cores. ```yaml mastodon: streaming: image: repository: ghcr.io/mastodon/mastodon-streaming tag: "" # defaults to Chart.AppVersion (v4.5.9) port: 4000 workers: 2 # STREAMING_CLUSTER_NUM — set to number of CPU cores allocated replicas: 2 base_url: null # set if streaming is on a separate subdomain, e.g. wss://stream.example.com resources: requests: cpu: 250m memory: 128Mi limits: cpu: 500m memory: 512Mi pdb: enable: true minAvailable: 1 # Trust a self-signed CA for DB TLS extraCerts: existingSecret: "db-ca-secret" # Secret with key ca.crt sslMode: "require" extraEnvVars: DB_SSLMODE: "require" ``` -------------------------------- ### Configure Bundled PostgreSQL Source: https://context7.com/mastodon/chart/llms.txt Enables the bundled PostgreSQL chart. Passwords must be set explicitly. Use `existingSecret` for password management if not providing inline. ```yaml postgresql: enabled: true auth: database: mastodon_production username: mastodon password: "strong-db-password" existingSecret: "" direct: hostname: pg-primary.internal port: 5432 readReplica: hostname: pg-replica.internal port: 5432 auth: existingSecret: "mastodon-pg-replica-secret" ``` -------------------------------- ### Enable OpenTelemetry Tracing Source: https://context7.com/mastodon/chart/llms.txt Configures OpenTelemetry (OTLP) for distributed tracing. Component-level settings for `web` and `sidekiq` can override global configurations. ```yaml mastodon: otel: enabled: true exporterUri: http://otel-collector.observability.svc:4317 namePrefix: mastodon nameSeparator: "-" web: otel: enabled: true exporterUri: http://otel-collector:4317 sidekiq: otel: enabled: true ``` -------------------------------- ### Configure Mastodon Web Server Deployment Source: https://context7.com/mastodon/chart/llms.txt Sets up the Rails/Puma web server deployment. Configure replica count, thread pool, worker processes, update strategy, resource limits, and pod affinity. ```yaml mastodon: web: replicas: 3 minThreads: "5" maxThreads: "5" workers: "2" # WEB_CONCURRENCY (Puma worker processes) persistentTimeout: "20" port: 3000 updateStrategy: type: RollingUpdate rollingUpdate: maxSurge: 10% maxUnavailable: 25% resources: requests: cpu: 250m memory: 768Mi limits: cpu: "1" memory: 1280Mi pdb: enable: true minAvailable: 1 # Pin web pods to nodes labelled role=web nodeSelector: role: web affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app.kubernetes.io/component: web topologyKey: kubernetes.io/hostname otel: enabled: true exporterUri: http://otel-collector:4317 namePrefix: mastodon nameSeparator: "-" ``` -------------------------------- ### Access Application with ClusterIP Service via Port-Forward Source: https://github.com/mastodon/chart/blob/main/templates/NOTES.txt For ClusterIP services, this script identifies the pod name and container port, then sets up port-forwarding to access the application locally at http://127.0.0.1:8080. ```bash export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "mastodon.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}") export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}") echo "Visit http://127.0.0.1:8080 to use your application" kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT ``` -------------------------------- ### Configure Bundled Redis Source: https://context7.com/mastodon/chart/llms.txt Enables the bundled Redis instance. Separate instances can be configured for Sidekiq and caching. Ensure passwords are set securely. ```yaml redis: enabled: true auth: password: "strong-redis-password" existingSecret: "" existingSecretKey: redis-password sidekiq: enabled: true hostname: redis-sidekiq.internal port: 6379 auth: existingSecret: "mastodon-redis-sidekiq-secret" cache: enabled: true hostname: redis-cache.internal port: 6379 auth: existingSecret: "mastodon-redis-cache-secret" ``` -------------------------------- ### Configure Weekly Media Cleanup CronJob Source: https://context7.com/mastodon/chart/llms.txt Schedule a `batch/v1 CronJob` to run `tootctl media remove` for purging cached remote media. Configure `enabled`, `schedule`, and `nodeSelector` for the job. ```yaml mastodon: cron: removeMedia: enabled: true schedule: "0 0 * * 0" # Every Sunday at midnight UTC nodeSelector: role: jobs ``` -------------------------------- ### Enable Prometheus Metrics Exporter Source: https://context7.com/mastodon/chart/llms.txt Enables Prometheus metrics collection for web and Sidekiq pods. Set `detailed: true` for more granular metrics. ```yaml mastodon: metrics: prometheus: enabled: true port: 9394 web: detailed: true sidekiq: detailed: true ``` -------------------------------- ### Run `tootctl` commands in Mastodon web pod Source: https://context7.com/mastodon/chart/llms.txt Execute administrative `tootctl` commands within the Mastodon web deployment pod. This is useful for tasks like resetting admin passwords, rebuilding search indices, or managing media. ```bash # Open an interactive shell in the web pod kubectl -n mastodon exec -it deployment/my-mastodon-web -- bash ``` ```bash # Reset an admin password kubectl -n mastodon exec -it deployment/my-mastodon-web -- \ tootctl accounts modify admin --reset-password ``` ```bash # Rebuild Elasticsearch indices manually kubectl -n mastodon exec -it deployment/my-mastodon-web -- \ tootctl search deploy ``` ```bash # Remove old remote media (runs automatically via CronJob) kubectl -n mastodon exec -it deployment/my-mastodon-web -- \ tootctl media remove ``` ```bash # Check federation with another instance kubectl -n mastodon exec -it deployment/my-mastodon-web -- \ tootctl federation status mastodon.social ``` -------------------------------- ### Configure S3-compatible object storage Source: https://context7.com/mastodon/chart/llms.txt Enable and configure S3-compatible object storage for assets and uploads, replacing local PersistentVolumeClaims. Credentials can be provided inline or via an existing Kubernetes Secret. ```yaml mastodon: s3: enabled: true bucket: mastodon-media endpoint: https://s3.us-east-1.amazonaws.com hostname: s3.us-east-1.amazonaws.com protocol: https region: us-east-1 permission: public-read alias_host: cdn.example.com # CDN fronting the bucket multipart_threshold: "16777216" # 16 MB # Use an existing Secret instead of inline credentials: existingSecret: "mastodon-s3-secret" # keys: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY # Inline credentials (alternative): # access_key: "AKIAIOSFODNN7EXAMPLE" # access_secret: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` -------------------------------- ### Configure Bundled Elasticsearch Source: https://context7.com/mastodon/chart/llms.txt Enables the bundled Elasticsearch chart for full-text search. For external clusters, set `enabled: false` and provide connection details. ```yaml elasticsearch: enabled: true image: repository: bitnamilegacy/elasticsearch tag: 7 ``` -------------------------------- ### Configure Kubernetes Ingress Resource Source: https://context7.com/mastodon/chart/llms.txt Creates a Kubernetes Ingress resource to route traffic to the Puma and streaming services. Supports TLS termination and cert-manager integration. Streaming can be split to a separate Ingress. ```yaml ingress: enabled: true ingressClassName: nginx annotations: cert-manager.io/cluster-issuer: "letsencrypt-prod" nginx.ingress.kubernetes.io/proxy-body-size: 40m hosts: - host: social.example.com paths: - path: "/" tls: - secretName: mastodon-tls hosts: - social.example.com # Split streaming onto a dedicated ingress streaming: enabled: true ingressClassName: nginx hosts: - host: stream.example.com paths: - path: "/" tls: - secretName: mastodon-streaming-tls hosts: - stream.example.com ``` -------------------------------- ### Configure Sidekiq Background Worker Deployments Source: https://context7.com/mastodon/chart/llms.txt Defines Sidekiq Deployments for processing specific queues. Each worker entry creates an independent Deployment. The 'scheduler' queue must have exactly 1 replica. Workers inherit global settings unless overridden. ```yaml mastodon: sidekiq: updateStrategy: type: Recreate # recommended to reduce duplicate job execution on deploy readinessProbe: enabled: true path: /opt/mastodon/tmp/sidekiq_process_has_started_and_will_begin_processing_jobs workers: # Default catch-all worker - name: all-queues concurrency: 25 replicas: 1 queues: - default,8 - push,6 - ingress,4 - mailers,2 - pull - scheduler # only ONE replica allowed when scheduler is present - fasp resources: requests: cpu: 250m memory: 512Mi limits: cpu: "1" memory: 768Mi # Dedicated high-throughput push/pull worker - name: push-pull concurrency: 50 replicas: 2 queues: - push - pull resources: requests: cpu: 500m memory: 768Mi # Dedicated mailer worker - name: mailers concurrency: 25 replicas: 2 queues: - mailers ``` -------------------------------- ### Configure Persistent Volume Claims for Mastodon Source: https://context7.com/mastodon/chart/llms.txt Define Persistent Volume Claims for assets and user media. Use `ReadWriteMany` access mode for multi-node scaling. `keepAfterDelete: true` preserves data on Helm uninstall. ```yaml mastodon: persistence: assets: accessMode: ReadWriteMany # use RWX to allow multi-node scaling keepAfterDelete: true resources: requests: storage: 10Gi # storageClassName: fast-ssd existingClaim: "" # supply a pre-created PVC name to skip creation system: accessMode: ReadWriteMany keepAfterDelete: true resources: requests: storage: 100Gi existingClaim: "" ``` -------------------------------- ### Configure OIDC External Authentication Source: https://context7.com/mastodon/chart/llms.txt Enables Single Sign-On (SSO) using OpenID Connect. Ensure `client_secret` is securely managed, preferably via a Kubernetes Secret. ```yaml externalAuth: oidc: enabled: true display_name: "My SSO" issuer: https://auth.example.com/realms/mastodon discovery: true scope: "openid,profile,email" uid_field: sub client_id: mastodon client_secret: "OIDC_CLIENT_SECRET" redirect_uri: https://social.example.com/auth/auth/openid_connect/callback assume_email_is_verified: true ``` -------------------------------- ### Configure LDAP External Authentication Source: https://context7.com/mastodon/chart/llms.txt Enables SSO via LDAP. Use `passwordSecretRef` to avoid storing the bind password directly in the configuration. ```yaml externalAuth: ldap: enabled: true host: ldap.corp.example.com port: 636 method: simple_tls base: "dc=corp,dc=example,dc=com" bind_dn: "cn=mastodon,ou=services,dc=corp,dc=example,dc=com" passwordSecretRef: name: mastodon-ldap-secret key: password uid: sAMAccountName mail: mail search_filter: "(|(sAMAccountName=%{email})(mail=%{email}))" ``` -------------------------------- ### Configure Global OAuth Settings Source: https://context7.com/mastodon/chart/llms.txt Disables local password login when `omniauth_only` is set to `true`, forcing users to authenticate via an external provider. ```yaml externalAuth: oauth_global: omniauth_only: false ``` -------------------------------- ### Configure HTTPRoute for Gateway API Source: https://context7.com/mastodon/chart/llms.txt Use this to configure Kubernetes Gateway API HTTPRoute resources for web and streaming traffic. Ensure parent references are correctly set for your gateway deployments. ```yaml httproute: enabled: true parentRefs: - name: prod-gateway namespace: gateway-namespace sectionName: https hostnames: - social.example.com rules: - matches: - path: type: PathPrefix value: / # Route streaming via a separate gateway streamingParentRefs: - name: streaming-gateway namespace: gateway-namespace sectionName: https streamingHostnames: - stream.example.com streamingRules: - matches: - path: type: PathPrefix value: /api/v1/streaming ``` -------------------------------- ### Configure Legacy StatsD Metrics Source: https://context7.com/mastodon/chart/llms.txt Configures StatsD for metrics export. Note that StatsD support was dropped in Mastodon v4.3.0. Set `exporter.enabled: true` to use a sidecar exporter when no external agent address is provided. ```yaml mastodon: metrics: statsd: address: "" exporter: enabled: false port: 9102 ``` -------------------------------- ### Upgrade Mastodon Chart Deployment Source: https://context7.com/mastodon/chart/llms.txt Upgrades an existing Mastodon deployment to incorporate new chart versions or configuration changes. It's recommended to update chart dependencies first and may require manual pod restarts for migrations. ```bash helm dep update helm upgrade my-mastodon . \ --namespace mastodon \ -f values-prod.yaml \ --timeout 15m # If pods were not recreated after a migration, force a rollout: kubectl rollout restart deployment/my-mastodon-web -n mastodon kubectl rollout restart deployment/my-mastodon-sidekiq-all-queues -n mastodon ``` -------------------------------- ### Inject Custom Environment Variables into Mastodon Pods Source: https://context7.com/mastodon/chart/llms.txt Use `extraEnvVars` for inline key-value pairs or `extraEnvFrom` to reference a ConfigMap for custom environment variables across all Mastodon pods. ```yaml mastodon: # Inline key-value pairs extraEnvVars: RAILS_SERVE_STATIC_FILES: "true" TRUSTED_PROXY_IP: "10.0.0.0/8,172.16.0.0/12" PREPARED_STATEMENTS: "false" # disable for pgbouncer transaction mode # Reference an existing ConfigMap by name (all keys become env vars) extraEnvFrom: "mastodon-extra-config" ``` -------------------------------- ### Mastodon Application Secrets Configuration Source: https://context7.com/mastodon/chart/llms.txt Defines Mastodon's cryptographic secrets within the `values.yaml` file. Auto-generation is possible but can cause session issues on upgrades; using `existingSecret` is recommended for stability. ```yaml mastodon: secrets: secret_key_base: "a1b2c3..." # 128-char hex; export SECRET_KEY_BASE=$(openssl rand -hex 64) otp_secret: "d4e5f6..." # 128-char hex vapid: private_key: "VAPID_PRIVATE" public_key: "VAPID_PUBLIC" activeRecordEncryption: primaryKey: "64-char-hex" deterministicKey: "64-char-hex" keyDerivationSalt: "64-char-hex" # --- OR use an existing Secret (takes precedence) --- # existingSecret: "mastodon-app-secrets" # Secret must contain keys: # SECRET_KEY_BASE, OTP_SECRET, VAPID_PRIVATE_KEY, VAPID_PUBLIC_KEY, # ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, # ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY, # ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT ``` -------------------------------- ### Reset Admin Password using Tootctl Source: https://github.com/mastodon/chart/blob/main/README.md Command to reset the admin user's password within the Mastodon web deployment using `tootctl`. This requires `kubectl` access to the Kubernetes cluster. ```bash kubectl -n mastodon exec -it deployment/mastodon-web -- bash tootctl accounts modify admin --reset-password ``` ```bash kubectl -n mastodon exec -it deployment/mastodon-web -- tootctl accounts modify admin --reset-password ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.