Installation Guide

Overview

This guide covers self-hosting Postiz using Docker Compose. The self-hosted version has no feature limitations compared to the cloud version—you get the complete platform with full control over your data.

Prefer cloud hosting? Sign up at platform.postiz.com for instant access with zero setup.

Prerequisites

Before you begin, ensure you have:

Docker & Docker Compose

Docker Engine 20.10+ and Docker Compose v2.0+Install Docker

System Requirements

Minimum:

2 CPU cores
4GB RAM
20GB disk space

Recommended:

4 CPU cores
8GB RAM
50GB SSD storage

Domain & DNS

A domain name with DNS configured (for production)Optional for local testing

Platform Credentials

OAuth credentials for platforms you want to connectSee platform setup section

Quick Installation

Get Postiz running in 3 commands:

Clone the Repository

git clone https://github.com/gitroomhq/postiz-app.git
cd postiz-app

Configure Environment

Copy the example environment file and update required settings:

cp .env.example .env

Edit .env with your preferred editor:

nano .env

Minimum Required Configuration:

.env

# Database (auto-configured by Docker)
DATABASE_URL="postgresql://postiz-user:postiz-password@postiz-postgres:5432/postiz-db-local"
REDIS_URL="redis://postiz-redis:6379"

# JWT Secret - CHANGE THIS to a random string!
JWT_SECRET="your-super-secret-random-string-min-32-chars"

# URLs - Update these for your domain
MAIN_URL="http://localhost:4007"
FRONTEND_URL="http://localhost:4007"
NEXT_PUBLIC_BACKEND_URL="http://localhost:4007/api"
BACKEND_INTERNAL_URL="http://localhost:3000"

# Temporal (auto-configured)
TEMPORAL_ADDRESS="temporal:7233"

# Required flags
IS_GENERAL="true"
DISABLE_REGISTRATION="false"

# Storage - local or cloudflare
STORAGE_PROVIDER="local"
UPLOAD_DIRECTORY="/uploads"
NEXT_PUBLIC_UPLOAD_DIRECTORY="/uploads"

Security: Change JWT_SECRET to a unique random string. Use at least 32 characters for production deployments.

Launch Postiz

Start all services with Docker Compose:

docker compose up -d

This will start:

postiz - Main application (port 4007)
postiz-postgres - PostgreSQL database
postiz-redis - Redis cache
temporal - Workflow orchestrator
temporal-postgresql - Temporal database
temporal-elasticsearch - Temporal search
temporal-ui - Temporal dashboard (port 8080)

First launch takes 3-5 minutes to download images and initialize databases.

Check service status:

docker compose ps

All services should show running status.

Access Postiz

Once all services are running:

Main Application

URL: http://localhost:4007Your Postiz dashboard and UI

Temporal UI

URL: http://localhost:8080Monitor background jobs and workflows

Open Postiz

Navigate to http://localhost:4007 in your browser

Create Admin Account

On first visit, you’ll see the registration page:

Enter your name
Email address
Password (min 8 characters)
Click Create Account

If RESEND_API_KEY is not configured, your account is immediately active. Otherwise, check your email for verification.

To connect social platforms, you need OAuth credentials from each platform’s developer portal. Add these to your .env file:

X (Twitter)

Developer Portal: https://developer.twitter.com/en/portal/dashboardRequired Permissions:

Read and write tweets
Read user profile

Callback URL:

http://localhost:4007/integrations/social/x

Environment Variables:

X_API_KEY="your_consumer_key"
X_API_SECRET="your_consumer_secret"

LinkedIn (Personal)

Developer Portal: https://www.linkedin.com/developers/Required Products:

Share on LinkedIn
Sign In with LinkedIn

Callback URL:

http://localhost:4007/integrations/social/linkedin

Environment Variables:

LINKEDIN_CLIENT_ID="your_client_id"
LINKEDIN_CLIENT_SECRET="your_client_secret"

Facebook & Instagram

Developer Portal: https://developers.facebook.com/Required Products:

Facebook Login
Instagram Basic Display
Instagram Graph API (for business accounts)

Callback URL:

http://localhost:4007/integrations/social/facebook

Environment Variables:

FACEBOOK_APP_ID="your_app_id"
FACEBOOK_APP_SECRET="your_app_secret"

Instagram posting requires a Facebook Business Page connected to your Instagram account.

YouTube

Developer Portal: https://console.cloud.google.com/Required APIs:

YouTube Data API v3

Callback URL:

http://localhost:4007/integrations/social/youtube

Environment Variables:

YOUTUBE_CLIENT_ID="your_google_client_id"
YOUTUBE_CLIENT_SECRET="your_google_client_secret"

TikTok

Developer Portal: https://developers.tiktok.com/Required Permissions:

Video upload
User info

Callback URL:

http://localhost:4007/integrations/social/tiktok

Environment Variables:

TIKTOK_CLIENT_ID="your_client_key"
TIKTOK_CLIENT_SECRET="your_client_secret"

Developer Portal: https://www.reddit.com/prefs/appsApp Type: Web AppCallback URL:

http://localhost:4007/integrations/social/reddit

Environment Variables:

REDDIT_CLIENT_ID="your_client_id"
REDDIT_CLIENT_SECRET="your_client_secret"

Discord

Developer Portal: https://discord.com/developers/applicationsRequired Scopes:

bot
applications.commands
Send Messages

Callback URL:

http://localhost:4007/integrations/social/discord

Environment Variables:

DISCORD_CLIENT_ID="your_application_id"
DISCORD_CLIENT_SECRET="your_client_secret"
DISCORD_BOT_TOKEN_ID="your_bot_token"

Slack

Developer Portal: https://api.slack.com/appsRequired Scopes:

channels:read
chat:write
users:read
groups:read
channels:join

Callback URL:

http://localhost:4007/integrations/social/slack

Environment Variables:

SLACK_ID="your_client_id"
SLACK_SECRET="your_client_secret"
SLACK_SIGNING_SECRET="your_signing_secret"

Threads

Developer Portal: https://developers.facebook.com/Note: Threads uses Meta’s developer platformCallback URL:

http://localhost:4007/integrations/social/threads

Environment Variables:

THREADS_APP_ID="your_app_id"
THREADS_APP_SECRET="your_app_secret"

Developer Portal: https://developers.pinterest.com/Required Scopes:

boards:read
pins:read
pins:write

Callback URL:

http://localhost:4007/integrations/social/pinterest

Environment Variables:

PINTEREST_CLIENT_ID="your_app_id"
PINTEREST_CLIENT_SECRET="your_app_secret"

Mastodon

Setup: No developer account needed - instance-level OAuthDefault Instance: https://mastodon.social (configurable)Environment Variables:

MASTODON_URL="https://mastodon.social"
MASTODON_CLIENT_ID="auto_generated_on_connect"
MASTODON_CLIENT_SECRET="auto_generated_on_connect"

Mastodon credentials are generated when you first connect. You can connect to any Mastodon instance.

All Supported Platforms: Below is the complete list from integration.manager.ts:40-74:

X (Twitter)
LinkedIn (Personal & Pages)
Reddit
Instagram (Business & Standalone)
Facebook
Threads
YouTube
Google My Business
TikTok
Pinterest
Dribbble
Discord
Slack
Kick
Twitch
Mastodon
Bluesky
Lemmy
Farcaster
Telegram
Nostr
VK
Medium
Dev.to
Hashnode
WordPress
Listmonk
Moltbook
Whop
Skool

You don’t need credentials for all platforms—only configure the ones you plan to use.

Optional Configuration

AI Content Generation

Enable AI-powered content creation with OpenAI:

.env

OPENAI_API_KEY="sk-your-openai-api-key"

AI Features:

Generate engaging posts from prompts
Create thread content automatically
Optimize post length for platforms
Convert text to natural voice

Email Notifications

Configure Resend for user email verification and notifications:

.env

RESEND_API_KEY="re_your-resend-api-key"
EMAIL_FROM_ADDRESS="[email protected]"
EMAIL_FROM_NAME="Postiz"

If RESEND_API_KEY is not set, users are auto-activated without email verification.

Cloudflare R2 Storage

For production, use Cloudflare R2 instead of local storage:

.env

STORAGE_PROVIDER="cloudflare"
CLOUDFLARE_ACCOUNT_ID="your-account-id"
CLOUDFLARE_ACCESS_KEY="your-access-key"
CLOUDFLARE_SECRET_ACCESS_KEY="your-secret-access-key"
CLOUDFLARE_BUCKETNAME="postiz-uploads"
CLOUDFLARE_BUCKET_URL="https://your-bucket.r2.cloudflarestorage.com/"
CLOUDFLARE_REGION="auto"

Stripe Payments (Optional)

If you want to offer paid plans:

.env

STRIPE_PUBLISHABLE_KEY="pk_your_publishable_key"
STRIPE_SECRET_KEY="sk_your_secret_key"
STRIPE_SIGNING_KEY="whsec_your_webhook_secret"
FEE_AMOUNT=0.05

Disable Registration

For private instances, disable new user signups:

.env

DISABLE_REGISTRATION="true"

API Rate Limiting

Configure public API rate limits (requests per hour):

.env

API_LIMIT=30

Production Deployment

For production environments, follow these additional steps:

Use a Reverse Proxy

Set up Nginx or Caddy to handle SSL/TLS:Nginx Example:

server {
    listen 443 ssl http2;
    server_name postiz.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:4007;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Update your .env:

MAIN_URL="https://postiz.yourdomain.com"
FRONTEND_URL="https://postiz.yourdomain.com"
NEXT_PUBLIC_BACKEND_URL="https://postiz.yourdomain.com/api"

Update OAuth Callbacks

Update all platform OAuth redirect URIs from http://localhost:4007 to your production domain:

https://postiz.yourdomain.com/integrations/social/{platform}

This must be done in each platform’s developer console.

Configure Cloudflare R2

Switch from local storage to Cloudflare R2 for scalability:

STORAGE_PROVIDER="cloudflare"
# Add Cloudflare credentials as shown above

Set Up Backups

Backup PostgreSQL database regularly:

# Manual backup
docker compose exec postiz-postgres pg_dump -U postiz-user postiz-db-local > backup.sql

# Restore
docker compose exec -T postiz-postgres psql -U postiz-user postiz-db-local < backup.sql

Consider automated backups with cron or cloud backup services.

Monitor Services

Access Temporal UI to monitor workflow execution:

https://postiz.yourdomain.com:8080

Set up log aggregation with:

docker compose logs -f

Updating Postiz

To update to the latest version:

# Pull latest changes
git pull origin main

# Pull latest Docker images
docker compose pull

# Restart services
docker compose up -d

# Check everything is running
docker compose ps

Always backup your database before updating!

Troubleshooting

Services won't start

Check Docker status:

docker compose ps
docker compose logs

Common fixes:

Ensure ports 4007, 8080, 7233 are not in use
Check Docker has enough memory (4GB minimum)
Verify .env file exists and is properly formatted

Database connection errors

Error: Error: connect ECONNREFUSEDSolution: Wait for PostgreSQL to initialize:

docker compose logs postiz-postgres

Look for “database system is ready to accept connections”Restart Postiz service:

docker compose restart postiz

OAuth redirect errors

Error: Redirect URI mismatchSolution: Ensure callback URLs match exactly:

Check your .env FRONTEND_URL
Verify platform developer console callback URLs
Format: {FRONTEND_URL}/integrations/social/{platform}
No trailing slashes

Posts not publishing

Problem: Scheduled posts remain in queueSolution: Check Temporal services:

docker compose logs temporal
docker compose logs orchestrator

Ensure Temporal UI shows workflows executing:

http://localhost:8080

Restart orchestrator if needed:

docker compose restart postiz

High memory usage

Problem: Docker consuming too much RAMSolution: Limit container resources in docker-compose.yaml:

services:
  postiz:
    deploy:
      resources:
        limits:
          memory: 2G

Or disable Elasticsearch for Temporal (uses less memory):

# Comment out temporal-elasticsearch service

File upload failures

Problem: Cannot upload media filesSolution: Check storage configuration:Local storage:

# Verify volume permissions
docker compose exec postiz ls -la /uploads

Cloudflare R2:

Verify credentials are correct
Check bucket permissions
Test connectivity to R2 endpoint

Development Setup

For local development without Docker:

Install Dependencies

Requirements:

Node.js 22.12.0+
pnpm 10.6.1+
PostgreSQL 17
Redis 7.2

# Install pnpm
npm install -g [email protected]

# Install dependencies
pnpm install

Start Infrastructure

Use Docker for databases only:

docker compose -f docker-compose.dev.yaml up -d

This starts PostgreSQL, Redis, and Temporal.

Run Database Migrations

pnpm prisma-db-push

Start Development Servers

# Start all apps (frontend, backend, orchestrator)
pnpm dev

# Or start individually:
pnpm dev:frontend   # http://localhost:4200
pnpm dev:backend    # http://localhost:3000
pnpm dev:orchestrator

Project Structure:

postiz-app/
├── apps/
│   ├── frontend/        # Next.js 14 app (port 4200)
│   ├── backend/         # NestJS API (port 3000)
│   ├── orchestrator/    # Temporal workflows
│   └── cli/             # Postiz CLI tool
├── libraries/
│   ├── nestjs-libraries/  # Shared backend code
│   │   └── integrations/  # Platform providers
│   └── helpers/          # Utility functions
├── docker-compose.yaml   # Production setup
├── docker-compose.dev.yaml  # Dev infrastructure
└── .env                  # Configuration

Next Steps

Quick Start

Learn how to create your first scheduled post

Configuration Reference

Explore all configuration options

Public API

Integrate Postiz with external tools

GitHub

Contribute to the project

Need help? Join our Discord community or open an issue on GitHub.

Get Started

Core Features

Social Platforms

Self-Hosting

Configuration

Installation Guide

Overview

Prerequisites

Docker & Docker Compose

System Requirements

Domain & DNS

Platform Credentials

Quick Installation

Access Postiz

Main Application

Temporal UI

Optional Configuration

AI Content Generation

Email Notifications

Cloudflare R2 Storage

Stripe Payments (Optional)

Disable Registration

API Rate Limiting

Production Deployment

Updating Postiz

Troubleshooting

Development Setup

Next Steps

Quick Start

Configuration Reference

Public API

GitHub

Build docs developers (and LLMs) love

Get Started

Core Features

Social Platforms

Self-Hosting

Configuration

​Overview

​Prerequisites

Docker & Docker Compose

System Requirements

Domain & DNS

Platform Credentials

​Quick Installation

​Access Postiz

Main Application

Temporal UI

​Configure Social Platform Credentials

​Optional Configuration

​AI Content Generation

​Email Notifications

​Cloudflare R2 Storage

​Stripe Payments (Optional)

​Disable Registration

​API Rate Limiting

​Production Deployment

​Updating Postiz

​Troubleshooting

​Development Setup

​Next Steps

Quick Start

Configuration Reference

Public API

GitHub

Build docs developers (and LLMs) love

Overview

Prerequisites

Quick Installation

Access Postiz

Configure Social Platform Credentials

Optional Configuration

AI Content Generation

Email Notifications

Cloudflare R2 Storage

Stripe Payments (Optional)

Disable Registration

API Rate Limiting

Production Deployment

Updating Postiz

Troubleshooting

Development Setup

Next Steps