Mastodon + PostgreSQL + Elasticsearch
Web & Communication
rootless
6 containers
postgres
docker.io/postgres:14-alpine
redis
docker.io/redis:7-alpine
elasticsearch
docker.elastic.co/elasticsearch/elasticsearch:7.17.29
mastodon-web
ghcr.io/mastodon/mastodon:v4.5.9
· 3000:3000
mastodon-streaming
ghcr.io/mastodon/mastodon-streaming:v4.5.9
· 4000:4000
mastodon-sidekiq
ghcr.io/mastodon/mastodon:v4.5.9
Deployment rootless
1. Prepare the host
Operating System:
!
Prerequisites once as root
Install Podman (needs podman 4.3 or newer; Ubuntu 22.04 ships 3.4 and is too old, use 24.04)
apt update && apt install -y podman
Create user (if not existing)
useradd -m -s /bin/bash mastodon passwd mastodon
Enable linger (services keep running after logout and start after reboot)
loginctl enable-linger mastodon
↪
Switch to deployment user
su - mastodon
Use su - with the dash — this creates a proper login shell as mastodon. Without the dash, root environment variables carry over and rootless Podman will not work correctly.
!
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
2. Choose a format and deploy
The same pod in four forms. Pick one and follow only its steps.
Each tab says which podman it needs. Check yours with podman --version:
Debian 12 ships 4.3, Ubuntu 24.04 4.9, Debian 13 5.4, Fedora 5.8, Arch 6.x.
Kubernetes YAML for podman kube play, started by systemd through a Quadlet .kube unit (podman 4.4+; older podman like Debian 12 uses podman-kube@, see the version check below).
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: x85-KcwsPrHVrKtugwWmaw
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: x85-KcwsPrHVrKtugwWmaw
- 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: kY0SVkt9OlgFmOTsCuapmQ
- name: OTP_SECRET
value: kY0SVkt9OlgFmOTsCuapmQ
- name: VAPID_PRIVATE_KEY
value: UNgiY0aMn3myLf2h7-7AkQ
- name: VAPID_PUBLIC_KEY
value: UNgiY0aMn3myLf2h7-7AkQ
- name: ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
value: XittbTUlSVqWzVscey3EaA
- name: ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT
value: XittbTUlSVqWzVscey3EaA
- name: ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
value: XittbTUlSVqWzVscey3EaA
- 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: x85-KcwsPrHVrKtugwWmaw
- name: REDIS_HOST
value: 127.0.0.1
- name: REDIS_PORT
value: '6379'
- name: SECRET_KEY_BASE
value: kY0SVkt9OlgFmOTsCuapmQ
- 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: x85-KcwsPrHVrKtugwWmaw
- 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: kY0SVkt9OlgFmOTsCuapmQ
- name: OTP_SECRET
value: kY0SVkt9OlgFmOTsCuapmQ
- name: VAPID_PRIVATE_KEY
value: UNgiY0aMn3myLf2h7-7AkQ
- name: VAPID_PUBLIC_KEY
value: UNgiY0aMn3myLf2h7-7AkQ
- name: ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
value: XittbTUlSVqWzVscey3EaA
- name: ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT
value: XittbTUlSVqWzVscey3EaA
- name: ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
value: XittbTUlSVqWzVscey3EaA
- 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
1
Save the YAML file
mkdir -p ~/.config/containers/ nano ~/.config/containers/mastodon.yaml
2
Test the pod (without autostart)
podman kube play ~/.config/containers/mastodon.yaml # Check status: podman pod ps && podman ps # Stop: podman kube down ~/.config/containers/mastodon.yaml
Check your podman version
podman --version
4.4 or newer: continue with step 3 below.
Older, e.g. 4.3 on Debian 12? There is no Quadlet yet: use podman's own podman-kube@ service instead of steps 3–5
systemctl --user enable --now podman-kube@$(systemd-escape ~/.config/containers/mastodon.yaml).service # Status & logs: systemctl --user status podman-kube@$(systemd-escape ~/.config/containers/mastodon.yaml).service journalctl --user -u podman-kube@$(systemd-escape ~/.config/containers/mastodon.yaml).service -f
The day-to-day commands below have a block for this service.
3
Create Quadlet .kube file
mastodon.kube
[Unit] Description=mastodon pod After=network-online.target Wants=network-online.target [Kube] Yaml=%h/.config/containers/mastodon.yaml [Service] Restart=always [Install] WantedBy=default.target
%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
4
Start systemd service
systemctl --user daemon-reload systemctl --user start mastodon.service
5
Status & Logs
systemctl --user status mastodon.service journalctl --user -u mastodon.service -f podman pod ps podman ps
6
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
Day-to-day logs, restart, update, remove (click to open)
Logs & shell into a container
podman logs -f mastodon-postgres podman logs -f mastodon-redis podman logs -f mastodon-elasticsearch podman logs -f mastodon-mastodon-web podman logs -f mastodon-mastodon-streaming podman logs -f mastodon-mastodon-sidekiq podman exec -it mastodon-postgres /bin/sh
Restart
systemctl --user restart mastodon.service
Update an image by hand
Pull the new version, the restart recreates the containers from it:
podman pull <image>:<tag> systemctl --user restart mastodon.service
Stop & remove
Stop through systemd, otherwise Restart=always brings the pod back. To remove it for good, delete the unit files and reload:
systemctl --user stop mastodon.service rm ~/.config/containers/systemd/mastodon.kube systemctl --user daemon-reload
podman older than 4.4 (podman-kube@ from step 3)
systemctl --user restart podman-kube@$(systemd-escape ~/.config/containers/mastodon.yaml).service # Update an image: pull, then restart as above podman pull <image>:<tag> # Stop and remove from autostart: systemctl --user disable --now podman-kube@$(systemd-escape ~/.config/containers/mastodon.yaml).service
Delete the data — permanent, only after stop & remove
podman volume rm mastodon-db podman volume rm mastodon-redis podman volume rm mastodon-es podman volume rm mastodon-system
Native systemd units without the Kubernetes YAML: one .pod plus one .container per container.
Each container becomes its own systemd service (restart, logs and ordering per container).
Needs podman 5.0 or newer — Debian 12 ships 4.3, use the Kube YAML tab there.
1
Save the unit files
mastodon.pod
[Unit] Description=mastodon pod [Pod] PodName=mastodon PublishPort=3000:3000 PublishPort=4000:4000
mastodon-postgres.container
[Unit] Description=mastodon-postgres container [Container] Image=docker.io/postgres:14-alpine Pod=mastodon.pod ContainerName=mastodon-postgres Environment=POSTGRES_DB=mastodon Environment=POSTGRES_USER=mastodon Environment=POSTGRES_PASSWORD=x85-KcwsPrHVrKtugwWmaw Volume=mastodon-db:/var/lib/postgresql/data:Z [Service] Restart=always [Install] WantedBy=default.target
mastodon-redis.container
[Unit] Description=mastodon-redis container [Container] Image=docker.io/redis:7-alpine Pod=mastodon.pod ContainerName=mastodon-redis Volume=mastodon-redis:/data:Z Exec=redis-server --appendonly yes [Service] Restart=always [Install] WantedBy=default.target
mastodon-elasticsearch.container
[Unit] Description=mastodon-elasticsearch container [Container] Image=docker.elastic.co/elasticsearch/elasticsearch:7.17.29 Pod=mastodon.pod ContainerName=mastodon-elasticsearch Environment=discovery.type=single-node Environment=xpack.security.enabled=false Environment="ES_JAVA_OPTS=-Xms512m -Xmx512m" Environment=cluster.name=mastodon-es Volume=mastodon-es:/usr/share/elasticsearch/data:Z [Service] Restart=always [Install] WantedBy=default.target
mastodon-mastodon-web.container
[Unit] Description=mastodon-mastodon-web container [Container] Image=ghcr.io/mastodon/mastodon:v4.5.9 Pod=mastodon.pod ContainerName=mastodon-mastodon-web Environment=RAILS_ENV=production Environment=LOCAL_DOMAIN=mastodon.example.com Environment=SINGLE_USER_MODE=false Environment=DB_HOST=127.0.0.1 Environment=DB_PORT=5432 Environment=DB_NAME=mastodon Environment=DB_USER=mastodon Environment=DB_PASS=x85-KcwsPrHVrKtugwWmaw Environment=REDIS_HOST=127.0.0.1 Environment=REDIS_PORT=6379 Environment=ES_ENABLED=true Environment=ES_HOST=127.0.0.1 Environment=ES_PORT=9200 Environment=SECRET_KEY_BASE=kY0SVkt9OlgFmOTsCuapmQ Environment=OTP_SECRET=kY0SVkt9OlgFmOTsCuapmQ Environment=VAPID_PRIVATE_KEY=UNgiY0aMn3myLf2h7-7AkQ Environment=VAPID_PUBLIC_KEY=UNgiY0aMn3myLf2h7-7AkQ Environment=ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=XittbTUlSVqWzVscey3EaA Environment=ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=XittbTUlSVqWzVscey3EaA Environment=ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=XittbTUlSVqWzVscey3EaA Environment=SMTP_SERVER=smtp.example.com Environment=SMTP_PORT=587 Environment=SMTP_LOGIN= Environment=SMTP_PASSWORD= Environment=SMTP_FROM_ADDRESS=mastodon@example.com Environment=IP_RETENTION_PERIOD=31536000 Environment=SESSION_RETENTION_PERIOD=31536000 Volume=mastodon-system:/mastodon/public/system:Z Exec=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" [Service] Restart=always [Install] WantedBy=default.target
mastodon-mastodon-streaming.container
[Unit] Description=mastodon-mastodon-streaming container [Container] Image=ghcr.io/mastodon/mastodon-streaming:v4.5.9 Pod=mastodon.pod ContainerName=mastodon-mastodon-streaming Environment=NODE_ENV=production Environment=LOCAL_DOMAIN=mastodon.example.com Environment=DB_HOST=127.0.0.1 Environment=DB_PORT=5432 Environment=DB_NAME=mastodon Environment=DB_USER=mastodon Environment=DB_PASS=x85-KcwsPrHVrKtugwWmaw Environment=REDIS_HOST=127.0.0.1 Environment=REDIS_PORT=6379 Environment=SECRET_KEY_BASE=kY0SVkt9OlgFmOTsCuapmQ Environment=PORT=4000 Environment=STREAMING_CLUSTER_NUM=1 [Service] Restart=always [Install] WantedBy=default.target
mastodon-mastodon-sidekiq.container
[Unit] Description=mastodon-mastodon-sidekiq container [Container] Image=ghcr.io/mastodon/mastodon:v4.5.9 Pod=mastodon.pod ContainerName=mastodon-mastodon-sidekiq Environment=RAILS_ENV=production Environment=LOCAL_DOMAIN=mastodon.example.com Environment=DB_HOST=127.0.0.1 Environment=DB_PORT=5432 Environment=DB_NAME=mastodon Environment=DB_USER=mastodon Environment=DB_PASS=x85-KcwsPrHVrKtugwWmaw Environment=REDIS_HOST=127.0.0.1 Environment=REDIS_PORT=6379 Environment=ES_ENABLED=true Environment=ES_HOST=127.0.0.1 Environment=ES_PORT=9200 Environment=SECRET_KEY_BASE=kY0SVkt9OlgFmOTsCuapmQ Environment=OTP_SECRET=kY0SVkt9OlgFmOTsCuapmQ Environment=VAPID_PRIVATE_KEY=UNgiY0aMn3myLf2h7-7AkQ Environment=VAPID_PUBLIC_KEY=UNgiY0aMn3myLf2h7-7AkQ Environment=ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=XittbTUlSVqWzVscey3EaA Environment=ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=XittbTUlSVqWzVscey3EaA Environment=ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=XittbTUlSVqWzVscey3EaA Environment=SMTP_SERVER=smtp.example.com Environment=SMTP_PORT=587 Environment=SMTP_LOGIN= Environment=SMTP_PASSWORD= Environment=SMTP_FROM_ADDRESS=mastodon@example.com Volume=mastodon-system:/mastodon/public/system:Z Exec=bash -c "until (echo > /dev/tcp/127.0.0.1/3000) 2>/dev/null; do sleep 3; done && exec bundle exec sidekiq" [Service] Restart=always [Install] WantedBy=default.target
Save all of them to ~/.config/containers/systemd/:
mkdir -p ~/.config/containers/systemd/ nano ~/.config/containers/systemd/mastodon.pod nano ~/.config/containers/systemd/mastodon-postgres.container nano ~/.config/containers/systemd/mastodon-redis.container nano ~/.config/containers/systemd/mastodon-elasticsearch.container nano ~/.config/containers/systemd/mastodon-mastodon-web.container nano ~/.config/containers/systemd/mastodon-mastodon-streaming.container nano ~/.config/containers/systemd/mastodon-mastodon-sidekiq.container
2
Start the pod
The pod service pulls in every container service. Autostart at boot comes from the [Install] section of the units, no enable needed.
systemctl --user daemon-reload systemctl --user start mastodon-pod.service
3
Status & Logs
systemctl --user status mastodon-pod.service journalctl --user -u mastodon-postgres.service -f journalctl --user -u mastodon-redis.service -f journalctl --user -u mastodon-elasticsearch.service -f journalctl --user -u mastodon-mastodon-web.service -f journalctl --user -u mastodon-mastodon-streaming.service -f journalctl --user -u mastodon-mastodon-sidekiq.service -f podman pod ps && podman ps
Day-to-day logs, restart, update, remove (click to open)
Logs & shell into a container
podman logs -f mastodon-postgres podman logs -f mastodon-redis podman logs -f mastodon-elasticsearch podman logs -f mastodon-mastodon-web podman logs -f mastodon-mastodon-streaming podman logs -f mastodon-mastodon-sidekiq podman exec -it mastodon-postgres /bin/sh
Restart
systemctl --user restart mastodon-pod.service
Update an image by hand
Pull the new version, the restart recreates the containers from it:
podman pull <image>:<tag> systemctl --user restart mastodon-pod.service
Stop & remove
Stop through systemd, otherwise Restart=always brings the pod back. To remove it for good, delete the unit files and reload:
systemctl --user stop mastodon-pod.service rm ~/.config/containers/systemd/mastodon.pod rm ~/.config/containers/systemd/mastodon-postgres.container rm ~/.config/containers/systemd/mastodon-redis.container rm ~/.config/containers/systemd/mastodon-elasticsearch.container rm ~/.config/containers/systemd/mastodon-mastodon-web.container rm ~/.config/containers/systemd/mastodon-mastodon-streaming.container rm ~/.config/containers/systemd/mastodon-mastodon-sidekiq.container systemctl --user daemon-reload
Delete the data — permanent, only after stop & remove
podman volume rm mastodon-db podman volume rm mastodon-redis podman volume rm mastodon-es podman volume rm mastodon-system
A docker-compose.yml for podman-compose. Handy if you already work with Compose; there are no per-container systemd services.
1
Install podman-compose as root
Run this as root, e.g. together with the prerequisites before su - mastodon.
apt install -y podman-compose
2
Save the compose file
docker-compose.yml
services:
postgres:
image: docker.io/postgres:14-alpine
restart: always
environment:
- POSTGRES_DB=mastodon
- POSTGRES_USER=mastodon
- POSTGRES_PASSWORD=x85-KcwsPrHVrKtugwWmaw
volumes:
- mastodon-db:/var/lib/postgresql/data:Z
ports:
- 3000:3000
- 4000:4000
redis:
image: docker.io/redis:7-alpine
restart: always
command:
- redis-server
- --appendonly
- 'yes'
volumes:
- mastodon-redis:/data:Z
network_mode: service:postgres
depends_on:
postgres:
condition: service_started
elasticsearch:
image: docker.elastic.co/elasticsearch/elasticsearch:7.17.29
restart: always
environment:
- discovery.type=single-node
- xpack.security.enabled=false
- ES_JAVA_OPTS=-Xms512m -Xmx512m
- cluster.name=mastodon-es
depends_on:
postgres:
condition: service_started
redis:
condition: service_started
volumes:
- mastodon-es:/usr/share/elasticsearch/data:Z
network_mode: service:postgres
mastodon-web:
image: ghcr.io/mastodon/mastodon:v4.5.9
restart: always
environment:
- RAILS_ENV=production
- LOCAL_DOMAIN=mastodon.example.com
- SINGLE_USER_MODE=false
- DB_HOST=127.0.0.1
- DB_PORT=5432
- DB_NAME=mastodon
- DB_USER=mastodon
- DB_PASS=x85-KcwsPrHVrKtugwWmaw
- REDIS_HOST=127.0.0.1
- REDIS_PORT=6379
- ES_ENABLED=true
- ES_HOST=127.0.0.1
- ES_PORT=9200
- SECRET_KEY_BASE=kY0SVkt9OlgFmOTsCuapmQ
- OTP_SECRET=kY0SVkt9OlgFmOTsCuapmQ
- VAPID_PRIVATE_KEY=UNgiY0aMn3myLf2h7-7AkQ
- VAPID_PUBLIC_KEY=UNgiY0aMn3myLf2h7-7AkQ
- ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=XittbTUlSVqWzVscey3EaA
- ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=XittbTUlSVqWzVscey3EaA
- ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=XittbTUlSVqWzVscey3EaA
- SMTP_SERVER=smtp.example.com
- SMTP_PORT=587
- SMTP_LOGIN=
- SMTP_PASSWORD=
- SMTP_FROM_ADDRESS=mastodon@example.com
- IP_RETENTION_PERIOD=31536000
- SESSION_RETENTION_PERIOD=31536000
command:
- 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
depends_on:
postgres:
condition: service_started
redis:
condition: service_started
volumes:
- mastodon-system:/mastodon/public/system:Z
network_mode: service:postgres
mastodon-streaming:
image: ghcr.io/mastodon/mastodon-streaming:v4.5.9
restart: always
environment:
- NODE_ENV=production
- LOCAL_DOMAIN=mastodon.example.com
- DB_HOST=127.0.0.1
- DB_PORT=5432
- DB_NAME=mastodon
- DB_USER=mastodon
- DB_PASS=x85-KcwsPrHVrKtugwWmaw
- REDIS_HOST=127.0.0.1
- REDIS_PORT=6379
- SECRET_KEY_BASE=kY0SVkt9OlgFmOTsCuapmQ
- PORT=4000
- STREAMING_CLUSTER_NUM=1
depends_on:
postgres:
condition: service_started
redis:
condition: service_started
network_mode: service:postgres
mastodon-sidekiq:
image: ghcr.io/mastodon/mastodon:v4.5.9
restart: always
environment:
- RAILS_ENV=production
- LOCAL_DOMAIN=mastodon.example.com
- DB_HOST=127.0.0.1
- DB_PORT=5432
- DB_NAME=mastodon
- DB_USER=mastodon
- DB_PASS=x85-KcwsPrHVrKtugwWmaw
- REDIS_HOST=127.0.0.1
- REDIS_PORT=6379
- ES_ENABLED=true
- ES_HOST=127.0.0.1
- ES_PORT=9200
- SECRET_KEY_BASE=kY0SVkt9OlgFmOTsCuapmQ
- OTP_SECRET=kY0SVkt9OlgFmOTsCuapmQ
- VAPID_PRIVATE_KEY=UNgiY0aMn3myLf2h7-7AkQ
- VAPID_PUBLIC_KEY=UNgiY0aMn3myLf2h7-7AkQ
- ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=XittbTUlSVqWzVscey3EaA
- ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=XittbTUlSVqWzVscey3EaA
- ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=XittbTUlSVqWzVscey3EaA
- SMTP_SERVER=smtp.example.com
- SMTP_PORT=587
- SMTP_LOGIN=
- SMTP_PASSWORD=
- SMTP_FROM_ADDRESS=mastodon@example.com
command:
- bash
- -c
- until (echo > /dev/tcp/127.0.0.1/3000) 2>/dev/null; do sleep 3; done && exec
bundle exec sidekiq
depends_on:
postgres:
condition: service_started
redis:
condition: service_started
volumes:
- mastodon-system:/mastodon/public/system:Z
network_mode: service:postgres
volumes:
mastodon-db: null
mastodon-redis: null
mastodon-es: null
mastodon-system: null
mkdir -p ~/mastodon nano ~/mastodon/docker-compose.yml
3
Start, status & logs
cd ~/mastodon podman-compose up -d podman-compose ps podman-compose logs -f # Stop: podman-compose down
4
Start after reboot
podman-restart.service starts every container with restart: always at boot:
systemctl --user enable podman-restart.service
5
Update images
cd ~/mastodon podman-compose pull podman-compose up -d
Day-to-day logs, restart, update, remove (click to open)
Logs & shell into a container
podman logs -f mastodon_postgres_1 podman logs -f mastodon_redis_1 podman logs -f mastodon_elasticsearch_1 podman logs -f mastodon_mastodon-web_1 podman logs -f mastodon_mastodon-streaming_1 podman logs -f mastodon_mastodon-sidekiq_1 podman exec -it mastodon_postgres_1 /bin/sh
Restart
cd ~/mastodon podman-compose restart
Stop & remove
cd ~/mastodon podman-compose down
Delete the data — permanent, only after stop & remove
podman volume rm mastodon_mastodon-db podman volume rm mastodon_mastodon-redis podman volume rm mastodon_mastodon-es podman volume rm mastodon_mastodon-system
Plain podman pod create / podman create commands. Good for a quick test or to see what happens under the hood.
1
Save the script
mastodon.sh
#!/bin/bash set -e # ── Create named volumes ─────────────────────────────────────────── # Named volumes are created automatically — no UID/GID permission adjustment needed. podman volume exists mastodon-db || podman volume create mastodon-db podman volume exists mastodon-redis || podman volume create mastodon-redis podman volume exists mastodon-es || podman volume create mastodon-es podman volume exists mastodon-system || podman volume create mastodon-system # ── Create pod ───────────────────────────────────────────────────── podman pod create \ --name mastodon \ -p 3000:3000 \ -p 4000:4000 # ── Container: mastodon-postgres ───────────────────────────────────────────── podman create \ --pod mastodon \ --name mastodon-postgres \ --restart always \ -e POSTGRES_DB='mastodon' \ -e POSTGRES_USER='mastodon' \ -e POSTGRES_PASSWORD='x85-KcwsPrHVrKtugwWmaw' \ -v mastodon-db:/var/lib/postgresql/data:Z \ docker.io/postgres:14-alpine # ── Container: mastodon-redis ───────────────────────────────────────────── podman create \ --pod mastodon \ --name mastodon-redis \ --restart always \ -v mastodon-redis:/data:Z \ docker.io/redis:7-alpine \ redis-server --appendonly yes # ── Container: mastodon-elasticsearch ───────────────────────────────────────────── podman create \ --pod mastodon \ --name mastodon-elasticsearch \ --restart always \ -e discovery.type='single-node' \ -e xpack.security.enabled='false' \ -e ES_JAVA_OPTS='-Xms512m -Xmx512m' \ -e cluster.name='mastodon-es' \ -v mastodon-es:/usr/share/elasticsearch/data:Z \ docker.elastic.co/elasticsearch/elasticsearch:7.17.29 # ── Container: mastodon-mastodon-web ───────────────────────────────────────────── podman create \ --pod mastodon \ --name mastodon-mastodon-web \ --restart always \ -e RAILS_ENV='production' \ -e LOCAL_DOMAIN='mastodon.example.com' \ -e SINGLE_USER_MODE='false' \ -e DB_HOST='127.0.0.1' \ -e DB_PORT='5432' \ -e DB_NAME='mastodon' \ -e DB_USER='mastodon' \ -e DB_PASS='x85-KcwsPrHVrKtugwWmaw' \ -e REDIS_HOST='127.0.0.1' \ -e REDIS_PORT='6379' \ -e ES_ENABLED='true' \ -e ES_HOST='127.0.0.1' \ -e ES_PORT='9200' \ -e SECRET_KEY_BASE='kY0SVkt9OlgFmOTsCuapmQ' \ -e OTP_SECRET='kY0SVkt9OlgFmOTsCuapmQ' \ -e VAPID_PRIVATE_KEY='UNgiY0aMn3myLf2h7-7AkQ' \ -e VAPID_PUBLIC_KEY='UNgiY0aMn3myLf2h7-7AkQ' \ -e ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY='XittbTUlSVqWzVscey3EaA' \ -e ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT='XittbTUlSVqWzVscey3EaA' \ -e ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY='XittbTUlSVqWzVscey3EaA' \ -e SMTP_SERVER='smtp.example.com' \ -e SMTP_PORT='587' \ -e SMTP_LOGIN='' \ -e SMTP_PASSWORD='' \ -e SMTP_FROM_ADDRESS='mastodon@example.com' \ -e IP_RETENTION_PERIOD='31536000' \ -e SESSION_RETENTION_PERIOD='31536000' \ -v mastodon-system:/mastodon/public/system:Z \ ghcr.io/mastodon/mastodon:v4.5.9 \ 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' # ── Container: mastodon-mastodon-streaming ───────────────────────────────────────────── podman create \ --pod mastodon \ --name mastodon-mastodon-streaming \ --restart always \ -e NODE_ENV='production' \ -e LOCAL_DOMAIN='mastodon.example.com' \ -e DB_HOST='127.0.0.1' \ -e DB_PORT='5432' \ -e DB_NAME='mastodon' \ -e DB_USER='mastodon' \ -e DB_PASS='x85-KcwsPrHVrKtugwWmaw' \ -e REDIS_HOST='127.0.0.1' \ -e REDIS_PORT='6379' \ -e SECRET_KEY_BASE='kY0SVkt9OlgFmOTsCuapmQ' \ -e PORT='4000' \ -e STREAMING_CLUSTER_NUM='1' \ ghcr.io/mastodon/mastodon-streaming:v4.5.9 # ── Container: mastodon-mastodon-sidekiq ───────────────────────────────────────────── podman create \ --pod mastodon \ --name mastodon-mastodon-sidekiq \ --restart always \ -e RAILS_ENV='production' \ -e LOCAL_DOMAIN='mastodon.example.com' \ -e DB_HOST='127.0.0.1' \ -e DB_PORT='5432' \ -e DB_NAME='mastodon' \ -e DB_USER='mastodon' \ -e DB_PASS='x85-KcwsPrHVrKtugwWmaw' \ -e REDIS_HOST='127.0.0.1' \ -e REDIS_PORT='6379' \ -e ES_ENABLED='true' \ -e ES_HOST='127.0.0.1' \ -e ES_PORT='9200' \ -e SECRET_KEY_BASE='kY0SVkt9OlgFmOTsCuapmQ' \ -e OTP_SECRET='kY0SVkt9OlgFmOTsCuapmQ' \ -e VAPID_PRIVATE_KEY='UNgiY0aMn3myLf2h7-7AkQ' \ -e VAPID_PUBLIC_KEY='UNgiY0aMn3myLf2h7-7AkQ' \ -e ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY='XittbTUlSVqWzVscey3EaA' \ -e ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT='XittbTUlSVqWzVscey3EaA' \ -e ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY='XittbTUlSVqWzVscey3EaA' \ -e SMTP_SERVER='smtp.example.com' \ -e SMTP_PORT='587' \ -e SMTP_LOGIN='' \ -e SMTP_PASSWORD='' \ -e SMTP_FROM_ADDRESS='mastodon@example.com' \ -v mastodon-system:/mastodon/public/system:Z \ ghcr.io/mastodon/mastodon:v4.5.9 \ bash -c 'until (echo > /dev/tcp/127.0.0.1/3000) 2>/dev/null; do sleep 3; done && exec bundle exec sidekiq' # ── Start pod ────────────────────────────────────────────────────── podman pod start mastodon # ── Stop & clean up ─────────────────────────────────────────────── # podman pod stop mastodon # podman pod rm mastodon
nano mastodon.sh
2
Run it, status & logs
bash mastodon.sh podman pod ps && podman ps podman logs -f <container-name>
3
Start after reboot
podman-restart.service starts every container with --restart always at boot:
systemctl --user enable podman-restart.service
4
Remove or rebuild
The script creates the pod once. To apply changes or new images, remove the pod and run the script again (named volumes stay):
podman pod rm -f mastodon bash mastodon.sh
Day-to-day logs, restart, update, remove (click to open)
Logs & shell into a container
podman logs -f mastodon-postgres podman logs -f mastodon-redis podman logs -f mastodon-elasticsearch podman logs -f mastodon-mastodon-web podman logs -f mastodon-mastodon-streaming podman logs -f mastodon-mastodon-sidekiq podman exec -it mastodon-postgres /bin/sh
Restart
podman pod stop mastodon podman pod start mastodon
Stop & remove
podman pod rm -f mastodon
Delete the data — permanent, only after stop & remove
podman volume rm mastodon-db podman volume rm mastodon-redis podman volume rm mastodon-es podman volume rm mastodon-system
Useful Tips
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 are the running containers publishing? See the PORTS column:
podman ps
Custom DNS for the pod
Set a custom DNS server (e.g. local Pi-hole) in the generator under DNS server. Every format picks it up.
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
Check for outdated images
List local images; auto-update only covers units with AutoUpdate= (Kube and Quadlet tabs):
podman images podman auto-update --dry-run
All containers, including stopped ones
podman pod ps podman ps -a
Resource usage
podman stats --no-stream
Customize this stack
Change ports, volumes, environment variables and more in the generator.
