Mastodon + PostgreSQL + Elasticsearch
Kubernetes YAML
apiVersion: v1
kind: Pod
metadata:
name: mastodon
labels:
app: mastodon
spec:
restartPolicy: Always
containers:
- name: postgres
image: docker.io/postgres:14-alpine
env:
- name: POSTGRES_DB
value: mastodon
- name: POSTGRES_USER
value: mastodon
- name: POSTGRES_PASSWORD
value: 4DB9NuJB-vccWHbWXyzIEQ
volumeMounts:
- name: vol-0
mountPath: /var/lib/postgresql/data
- name: redis
image: docker.io/redis:7-alpine
volumeMounts:
- name: vol-1
mountPath: /data
args:
- redis-server
- --appendonly
- 'yes'
- name: elasticsearch
image: docker.elastic.co/elasticsearch/elasticsearch:7.17.29
env:
- name: discovery.type
value: single-node
- name: xpack.security.enabled
value: 'false'
- name: ES_JAVA_OPTS
value: -Xms512m -Xmx512m
- name: cluster.name
value: mastodon-es
volumeMounts:
- name: vol-2
mountPath: /usr/share/elasticsearch/data
- name: mastodon-web
image: ghcr.io/mastodon/mastodon:v4.5.9
ports:
- containerPort: 3000
hostPort: 3000
env:
- name: RAILS_ENV
value: production
- name: LOCAL_DOMAIN
value: mastodon.example.com
- name: SINGLE_USER_MODE
value: 'false'
- name: DB_HOST
value: 127.0.0.1
- name: DB_PORT
value: '5432'
- name: DB_NAME
value: mastodon
- name: DB_USER
value: mastodon
- name: DB_PASS
value: 4DB9NuJB-vccWHbWXyzIEQ
- name: REDIS_HOST
value: 127.0.0.1
- name: REDIS_PORT
value: '6379'
- name: ES_ENABLED
value: 'true'
- name: ES_HOST
value: 127.0.0.1
- name: ES_PORT
value: '9200'
- name: SECRET_KEY_BASE
value: MvYa9qGg0aTwK20dfQ4ptQ
- name: OTP_SECRET
value: MvYa9qGg0aTwK20dfQ4ptQ
- name: VAPID_PRIVATE_KEY
value: OeAq8fDIKBBD6QTwaEIpyw
- name: VAPID_PUBLIC_KEY
value: OeAq8fDIKBBD6QTwaEIpyw
- name: ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
value: 3T6U2C3zzdhr0Hw1KCe0QQ
- name: ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT
value: 3T6U2C3zzdhr0Hw1KCe0QQ
- name: ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
value: 3T6U2C3zzdhr0Hw1KCe0QQ
- name: SMTP_SERVER
value: smtp.example.com
- name: SMTP_PORT
value: '587'
- name: SMTP_LOGIN
value: ''
- name: SMTP_PASSWORD
value: ''
- name: SMTP_FROM_ADDRESS
value: mastodon@example.com
- name: IP_RETENTION_PERIOD
value: '31536000'
- name: SESSION_RETENTION_PERIOD
value: '31536000'
volumeMounts:
- name: vol-3
mountPath: /mastodon/public/system
args:
- bash
- -c
- until (echo > /dev/tcp/127.0.0.1/5432) 2>/dev/null; do sleep 3; done && bundle
exec rails db:prepare && exec bundle exec puma -C config/puma.rb
- name: mastodon-streaming
image: ghcr.io/mastodon/mastodon-streaming:v4.5.9
ports:
- containerPort: 4000
hostPort: 4000
env:
- name: NODE_ENV
value: production
- name: LOCAL_DOMAIN
value: mastodon.example.com
- name: DB_HOST
value: 127.0.0.1
- name: DB_PORT
value: '5432'
- name: DB_NAME
value: mastodon
- name: DB_USER
value: mastodon
- name: DB_PASS
value: 4DB9NuJB-vccWHbWXyzIEQ
- name: REDIS_HOST
value: 127.0.0.1
- name: REDIS_PORT
value: '6379'
- name: SECRET_KEY_BASE
value: MvYa9qGg0aTwK20dfQ4ptQ
- name: PORT
value: '4000'
- name: STREAMING_CLUSTER_NUM
value: '1'
- name: mastodon-sidekiq
image: ghcr.io/mastodon/mastodon:v4.5.9
env:
- name: RAILS_ENV
value: production
- name: LOCAL_DOMAIN
value: mastodon.example.com
- name: DB_HOST
value: 127.0.0.1
- name: DB_PORT
value: '5432'
- name: DB_NAME
value: mastodon
- name: DB_USER
value: mastodon
- name: DB_PASS
value: 4DB9NuJB-vccWHbWXyzIEQ
- name: REDIS_HOST
value: 127.0.0.1
- name: REDIS_PORT
value: '6379'
- name: ES_ENABLED
value: 'true'
- name: ES_HOST
value: 127.0.0.1
- name: ES_PORT
value: '9200'
- name: SECRET_KEY_BASE
value: MvYa9qGg0aTwK20dfQ4ptQ
- name: OTP_SECRET
value: MvYa9qGg0aTwK20dfQ4ptQ
- name: VAPID_PRIVATE_KEY
value: OeAq8fDIKBBD6QTwaEIpyw
- name: VAPID_PUBLIC_KEY
value: OeAq8fDIKBBD6QTwaEIpyw
- name: ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
value: 3T6U2C3zzdhr0Hw1KCe0QQ
- name: ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT
value: 3T6U2C3zzdhr0Hw1KCe0QQ
- name: ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
value: 3T6U2C3zzdhr0Hw1KCe0QQ
- name: SMTP_SERVER
value: smtp.example.com
- name: SMTP_PORT
value: '587'
- name: SMTP_LOGIN
value: ''
- name: SMTP_PASSWORD
value: ''
- name: SMTP_FROM_ADDRESS
value: mastodon@example.com
volumeMounts:
- name: vol-3
mountPath: /mastodon/public/system
args:
- bash
- -c
- until (echo > /dev/tcp/127.0.0.1/3000) 2>/dev/null; do sleep 3; done && exec
bundle exec sidekiq
volumes:
- name: vol-0
persistentVolumeClaim:
claimName: mastodon-db
- name: vol-1
persistentVolumeClaim:
claimName: mastodon-redis
- name: vol-2
persistentVolumeClaim:
claimName: mastodon-es
- name: vol-3
persistentVolumeClaim:
claimName: mastodon-system
Deployment Guide rootless
Prerequisites once as root
0. Install Podman
apt update && apt install -y podman
1. Create user (if not existing)
useradd -m -s /bin/bash passwd
2. Enable linger (service runs after reboot without login)
loginctl enable-linger
Switch to deployment user
su -
Use su - with the dash — this creates a proper login shell as . Without the dash, root environment variables carry over and rootless Podman will not work correctly.
As deployment user
Fix environment for rootless systemd (new users only — skip if already set)
Required once so systemctl --user works in non-login sessions.
cat << 'EOF' >> ~/.bashrc # Fix for systemd user services (rootless Podman/systemctl) export XDG_RUNTIME_DIR=/run/user/$(id -u) export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus EOF source ~/.bashrc
Save the YAML file
mkdir -p ~/.config/containers/ nano ~/.config/containers/mastodon.yaml
Test the pod (without autostart)
podman play kube ~/.config/containers/mastodon.yaml # Check status: podman pod ps && podman ps # Stop: podman play kube --down ~/.config/containers/mastodon.yaml
Create Quadlet .kube file
%h is a systemd home-directory specifier — do not replace it with ~/.
Save to ~/.config/containers/systemd/:
mkdir -p ~/.config/containers/systemd/ nano ~/.config/containers/systemd/mastodon.kube
Start systemd service
systemctl --user daemon-reload systemctl --user start mastodon.service
Status & Logs
systemctl --user status mastodon.service journalctl --user -u mastodon.service -f podman pod ps podman ps
Enable automatic image updates optional
Requires AutoUpdate=registry in the .kube file. Podman then checks for new images and restarts the pod automatically:
systemctl --user enable --now podman.socket systemctl --user daemon-reload systemctl --user enable --now podman-auto-update.timer # Check status: systemctl --user status podman-auto-update.timer # Trigger manually: podman auto-update
Ports < 1024 (e.g. 80, 443)
Rootless cannot open privileged ports. Solution:
sysctl net.ipv4.ip_unprivileged_port_start=80
Make persistent in /etc/sysctl.d/99-podman.conf.
Containers communicate via localhost
All containers in the pod share the same network namespace. Always use localhost, not container names.
# Correct (e.g. app → db): localhost:5432 # Wrong (doesn't work in a pod): db-container:5432
List open ports
Which ports is the running pod listening on?
podman port mastodon-pod
Custom DNS for the pod
Set a custom DNS server (e.g. local Pi-hole):
# In YAML under spec.dnsConfig:
spec:
dnsConfig:
nameservers:
- 192.168.1.x
Set volume ownership
Fix permission errors by adjusting UID/GID in the user namespace:
podman unshare chown 1000:1000 /path/to/volume
SELinux volume labels
On SELinux systems (RHEL, Fedora) set the volume suffix:
/host/path:/container/path:Z # private /host/path:/container/path:z # shared
List all volumes
podman volume ls podman volume inspect <volume-name>
Volume backup
Back up data from a named volume:
podman run --rm \ -v <volume-name>:/data:ro \ -v $(pwd):/backup \ busybox tar czf /backup/backup.tar.gz /data
Cleanup
Remove unused images, containers and volumes:
podman system prune -f # containers + images podman image prune -f # untagged images only podman volume prune -f # unused volumes
Manual update
Pull a new image version and restart the pod:
podman pull <image>:<tag> podman play kube --replace \ ~/.config/containers/mastodon.yaml
Check for outdated images
List local images and test auto-update without applying:
podman images podman auto-update --dry-run
Shell into a running container
podman exec -it mastodon-<container> /bin/sh # or bash: podman exec -it mastodon-<container> /bin/bash
Follow live logs
# All containers in the pod: podman pod logs -f mastodon-pod # Single container: podman logs -f mastodon-<container>
Pod info & resource usage
podman pod inspect mastodon-pod podman stats mastodon-pod
Restart pod without data loss
podman pod restart mastodon-pod # or via systemd: systemctl --user restart mastodon.service
Stop & remove pod
podman pod stop mastodon-pod podman pod rm mastodon-pod
All in one
podman pod stop mastodon-pod && podman pod rm mastodon-pod
