Docker Compose Setup

The easiest way to deploy Postiz is using Docker Compose. This guide will walk you through setting up a complete Postiz instance with all required services.

Prerequisites

Install Docker

Install Docker Engine and Docker Compose on your system:

Verify Installation

docker --version
docker compose version

Quick Start

Create Project Directory

mkdir postiz
cd postiz

Download Docker Compose File

curl -O https://raw.githubusercontent.com/gitroomhq/postiz-app/main/docker-compose.yaml

Create Dynamic Config Directory

mkdir -p dynamicconfig

This directory is required for Temporal configuration.

Start Services

docker compose up -d

Access Postiz

Open your browser and navigate to:

http://localhost:4007

The first startup may take a few minutes as Docker downloads all the required images and initializes the databases.

Docker Compose Configuration

The docker-compose.yaml file configures all services needed to run Postiz:

Services Overview

services:
  # Main Postiz application
  postiz:
    image: ghcr.io/gitroomhq/postiz-app:latest
    container_name: postiz
    restart: always
    ports:
      - "4007:5000"
    depends_on:
      postiz-postgres:
        condition: service_healthy
      postiz-redis:
        condition: service_healthy

  # PostgreSQL database
  postiz-postgres:
    image: postgres:17-alpine
    container_name: postiz-postgres
    restart: always

  # Redis cache
  postiz-redis:
    image: redis:7.2
    container_name: postiz-redis
    restart: always

  # Temporal workflow engine
  temporal:
    image: temporalio/auto-setup:1.28.1
    container_name: temporal
    ports:
      - '7233:7233'

  # Temporal UI (optional)
  temporal-ui:
    image: temporalio/ui:2.34.0
    container_name: temporal-ui
    ports:
      - '8080:8080'

Service Descriptions

postiz

service

Main application container running the Postiz frontend and backend

Image: ghcr.io/gitroomhq/postiz-app:latest
Port: 4007:5000 (host:container)
Volumes:
- /config/ - Application configuration
- /uploads/ - Media uploads (if using local storage)

postiz-postgres

service

PostgreSQL 17 database for persistent data storage

Image: postgres:17-alpine
Healthcheck: Ensures database is ready before starting Postiz
Volume: postgres-volume:/var/lib/postgresql/data

postiz-redis

service

Redis cache for sessions and temporary data

Image: redis:7.2
Healthcheck: Ensures Redis is responding before starting Postiz
Volume: postiz-redis-data:/data

temporal

service

Temporal workflow orchestration engine for background jobs

Image: temporalio/auto-setup:1.28.1
Port: 7233:7233
Dependencies: temporal-postgresql, temporal-elasticsearch

Environment Variables

The Docker Compose file includes essential environment variables. Here are the key ones:

Required Settings

MAIN_URL: 'http://localhost:4007'
FRONTEND_URL: 'http://localhost:4007'
NEXT_PUBLIC_BACKEND_URL: 'http://localhost:4007/api'
JWT_SECRET: 'random string that is unique to every install'
DATABASE_URL: 'postgresql://postiz-user:postiz-password@postiz-postgres:5432/postiz-db-local'
REDIS_URL: 'redis://postiz-redis:6379'

Security: Change the JWT_SECRET to a random string! This is critical for security. Generate a strong random string with:

openssl rand -base64 32

Database Credentials

DATABASE_URL: 'postgresql://postiz-user:postiz-password@postiz-postgres:5432/postiz-db-local'

For production, change the default PostgreSQL credentials:

postiz-postgres:
  environment:
    POSTGRES_PASSWORD: your-strong-password
    POSTGRES_USER: your-username
    POSTGRES_DB: postiz-db

Update the DATABASE_URL accordingly.

Persistent Storage

Postiz uses Docker volumes to persist data:

volumes:
  postgres-volume:      # PostgreSQL database files
  postiz-redis-data:    # Redis persistence
  postiz-config:        # Application configuration
  postiz-uploads:       # Media uploads (local storage)

Backup Volumes

To backup your data:

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

# Backup uploads directory
docker run --rm -v postiz_postiz-uploads:/uploads -v $(pwd):/backup alpine tar czf /backup/uploads-backup.tar.gz -C /uploads .

Port Configuration

By default, Postiz exposes these ports:

Service	Host Port	Container Port	Description
Postiz	4007	5000	Main application
Temporal	7233	7233	Temporal gRPC
Temporal UI	8080	8080	Temporal web UI

Changing the Default Port

To run Postiz on a different port (e.g., 8080):

postiz:
  ports:
    - "8080:5000"  # Changed from 4007:5000
  environment:
    MAIN_URL: 'http://localhost:8080'
    FRONTEND_URL: 'http://localhost:8080'
    NEXT_PUBLIC_BACKEND_URL: 'http://localhost:8080/api'

Production Deployment

For production deployments, consider these additional configurations:

1. Use Environment File

Create a .env file instead of inline environment variables:

postiz:
  env_file:
    - .env

See the Environment Variables page for a complete list.

2. Configure Reverse Proxy

Use Nginx or Traefik as a reverse proxy:

server {
    listen 80;
    server_name postiz.yourdomain.com;

    location / {
        proxy_pass http://localhost:4007;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. Enable SSL/TLS

Update URLs to use HTTPS:

MAIN_URL: 'https://postiz.yourdomain.com'
FRONTEND_URL: 'https://postiz.yourdomain.com'
NEXT_PUBLIC_BACKEND_URL: 'https://postiz.yourdomain.com/api'

4. Set Resource Limits

postiz:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 4G
      reservations:
        cpus: '1'
        memory: 2G

Managing Services

Start Services

docker compose up -d

Stop Services

docker compose down

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f postiz

Restart Service

docker compose restart postiz

Update to Latest Version

docker compose pull
docker compose up -d

Always backup your database before updating!

Troubleshooting

Container Won’t Start

Check the logs:

docker compose logs postiz

Database Connection Issues

Verify PostgreSQL is healthy:

docker compose ps postiz-postgres
docker compose exec postiz-postgres pg_isready -U postiz-user

Port Already in Use

Change the host port in docker-compose.yaml:

ports:
  - "8080:5000"  # Use 8080 instead of 4007

Reset Everything

This will delete all data!

docker compose down -v
docker compose up -d

Monitoring

Health Checks

Postiz includes health checks for critical services:

postiz-postgres:
  healthcheck:
    test: pg_isready -U postiz-user -d postiz-db-local
    interval: 10s
    timeout: 3s
    retries: 3

postiz-redis:
  healthcheck:
    test: redis-cli ping
    interval: 10s
    timeout: 3s
    retries: 3

Temporal UI

Access the Temporal UI to monitor workflows:

http://localhost:8080

Sentry Integration (Optional)

Enable Sentry for error tracking:

NEXT_PUBLIC_SENTRY_DSN: 'http://spotlight:8969/stream'
SENTRY_SPOTLIGHT: '1'

The Spotlight service will be available at http://localhost:8969.

Next Steps

Configure Storage

Set up storage configuration for media uploads

Add Social Media OAuth

Configure authentication for social media platforms

Review All Variables

Check the complete environment variables reference

Get Started

Core Features

Social Platforms

Self-Hosting

Configuration

​Docker Compose Setup

​Prerequisites

​Quick Start

​Docker Compose Configuration

​Services Overview

​Service Descriptions

​Environment Variables

​Required Settings

​Database Credentials

​Persistent Storage

​Backup Volumes

​Port Configuration

​Changing the Default Port

​Production Deployment

​1. Use Environment File

​2. Configure Reverse Proxy

​3. Enable SSL/TLS

​4. Set Resource Limits

​Managing Services

​Start Services

​Stop Services

​View Logs

​Restart Service

​Update to Latest Version

​Troubleshooting

​Container Won’t Start

​Database Connection Issues

​Port Already in Use

​Reset Everything

​Monitoring

​Health Checks

​Temporal UI

​Sentry Integration (Optional)

​Next Steps

Build docs developers (and LLMs) love

Docker Compose Setup

Prerequisites

Quick Start

Docker Compose Configuration

Services Overview

Service Descriptions

Environment Variables

Required Settings

Database Credentials

Persistent Storage

Backup Volumes

Port Configuration

Changing the Default Port

Production Deployment

1. Use Environment File

2. Configure Reverse Proxy

3. Enable SSL/TLS

4. Set Resource Limits

Managing Services

Start Services

Stop Services

View Logs

Restart Service

Update to Latest Version

Troubleshooting

Container Won’t Start

Database Connection Issues

Port Already in Use

Reset Everything

Monitoring

Health Checks

Temporal UI

Sentry Integration (Optional)

Next Steps