Postiz — self-hosted social media scheduling

Context

Postiz is Aspire's self-hosted social-media scheduling platform (open-source Buffer/Hootsuite alternative). Powers the Content Studio publish-routing pipeline AND is the infrastructure behind the Aspire Social Media Management service offering. LIVE on Aspire infra since 2026-05-09.

Architecture

Detail

Deployment

• Self-hosted via Coolify, postgres service fx782ru9k48gczub7xzkcq3x
• Image: ghcr.io/gitroomhq/postiz-app:*
• LIVE 2026-05-09

⚠️ Critical operational gotchas (hard-won, multiple outages)

1. Volume-prefix doubling → empty-DB outage (per MEMORY.md feedback_coolify_volume_prefix_doubling)

• Every Coolify update/restart on the Postiz service DOUBLES the volume name prefix
• → postgres mounts a fresh-empty volume → "cannot log in" outage
• Data is SAFE on the original fx782..._postgres-volume
• Caused an 8-hour outage 2026-05-13→16
• DO NOT run Coolify ops on Postiz until the permanent fix (06-permanent-volume-fix.md) is applied
• Manual postgres recreate needs --network-alias postiz-postgres

2. EMAIL_PROVIDER must be set (per MEMORY.md feedback_postiz_email_provider_required)

• Setting EMAIL_HOST/PORT/USER/PASS alone is NOT enough
• EmailService defaults to EmptyProvider that silently no-ops
• Must set EMAIL_PROVIDER=nodemailer (or =resend)
• Affects BOTH backend (queues) AND orchestrator (sends) PM2 processes
• Forgot-password / invites silently fail otherwise; SendGrid Activity shows nothing

3. Temporal compose bug (per MEMORY.md feedback_postiz_temporal_dynamic_config_bug)

• Postiz one-click compose has stale DYNAMIC_CONFIG_FILE_PATH that crashes Temporal on auto-setup:1.28.1
• Remove the env var

4. No curl/wget in image (per MEMORY.md feedback_postiz_no_curl_in_image)

• Image ships only /usr/local/bin/node
• curl/wget HEALTHCHECK fails → unhealthy → Traefik 503
• Use node -e "require('http').get(...)" pattern
• start_period 180s minimum for prisma db push

postiz-mcp (built 2026-05-23)

• Local MCP at ~/mcp-servers/postiz-mcp/
• 5 tools: list_channels, upload_media, schedule_post, get_post_status, cancel_post
• Registration pending API token paste (see REGISTER.md)

Two consumers

1. Content Studio publish-routing skill (AI marketing engine at marketing/content-studio/) — see content-studio
2. Aspire Social Media Management service — done-for-you SMM offering (pre-launch; do NOT deploy more infra until client #1 signs)

Aspire LLM Gateway integration

Postiz was the FIRST gateway consumer — virtual key sk-woK9Fvz_lu6yLU8CyU5vSQ provisioned 2026-05-09 (per aspire-llm-gateway-fallback-chain).

Related

• content-studio — primary consumer
• edm-sproutsend — email counterpart (Postiz = social, EDM = email)
• aspire-llm-gateway-fallback-chain — first virtual key
• coolify-multi-server-topology — deploy gotchas

🔗 Relationships