Skip to content
Klutch.sh Docs

Deploying a Postiz App

Introduction

Postiz is an open-source social media scheduler with queues, calendars, and multi-account publishing. Deploying Postiz with a Dockerfile on Klutch.sh delivers reproducible builds, managed secrets, and optional persistent storage—all configured from klutch.sh/app. This guide covers installation, repo prep, a production-ready Dockerfile, environment configuration, storage, Nixpacks overrides, and sample API calls.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Postiz Dockerfile (GitHub is the only supported git source)
  • External PostgreSQL database and optional Redis cache
  • OAuth credentials for social networks you plan to connect

For onboarding, see the Quick Start.

Architecture and ports

  • Postiz serves HTTP on internal port 3000. Choose HTTP traffic in Klutch.sh and set the internal port to 3000.
  • Persistent storage is optional (e.g., image uploads/cache). Primary data lives in Postgres (and Redis if enabled).

Repository layout

postiz/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Test locally before pushing to GitHub:

Terminal window
docker build -t postiz-local .
docker run -p 3000:3000 \
  -e DATABASE_URL=postgres://user:pass@localhost:5432/postiz \
  -e NEXTAUTH_SECRET=$(openssl rand -hex 32) \
  -e NEXTAUTH_URL=http://localhost:3000 \
  -e REDIS_URL=redis://localhost:6379 \
  postiz-local

Ensure Postgres (and Redis if used) are reachable.

Dockerfile for Postiz (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it.

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build


FROM node:18-alpine AS runner
WORKDIR /app
ENV PORT=3000
ENV NODE_ENV=production
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package*.json ./
RUN npm ci --omit=dev
EXPOSE 3000
CMD ["npm", "run", "start"]

Notes:

  • Pin Node to the version Postiz supports (adjust if upstream changes).
  • Keep the Dockerfile at the repo root; users cannot select Docker manually in the dashboard.

Environment variables (Klutch.sh)

Set these before deploying:

  • PORT=3000
  • DATABASE_URL=postgres://<user>:<password>@<host>:5432/<db>
  • NEXTAUTH_URL=https://example-app.klutch.sh
  • NEXTAUTH_SECRET=<secure-random-hex>
  • REDIS_URL=redis://<host>:6379 (optional)
  • OAuth keys for providers you enable (e.g., TWITTER_CLIENT_ID, TWITTER_CLIENT_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, etc.)

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_NODE_VERSION=18
  • NIXPACKS_START_CMD=npm run start

Attach persistent volumes

If you store local assets, add storage in Klutch.sh with mount path and size (no names needed):

  • /app/storage — optional uploads/cache.

Ensure the path matches your Postiz configuration.

Deploy Postiz on Klutch.sh (Dockerfile workflow)

  1. Push your repo—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 3000.
  4. Add the environment variables above (database, NextAuth, OAuth keys, and optional Redis).
  5. Attach a volume at /app/storage if you want local asset persistence, sized for your needs.
  6. Deploy. Your app will be reachable at https://example-app.klutch.sh; add a custom domain if desired.

Sample API usage

Check health:

Terminal window
curl -I https://example-app.klutch.sh/api/health

Create a test request (example placeholder endpoint):

Terminal window
curl -X POST https://example-app.klutch.sh/api/webhooks/test \
  -H "Content-Type: application/json" \
  -d '{"source":"klutch-guide","status":"ok"}'

Health checks and production tips

  • Add an HTTP readiness probe to /api/health (or the equivalent status endpoint).
  • Keep NEXTAUTH_SECRET and OAuth credentials in Klutch.sh secrets; rotate them periodically.
  • Use external Postgres (and Redis) for durability; back up databases regularly.
  • Pin Docker base versions and test upgrades in staging before production.
  • Monitor storage usage on /app/storage if enabled; resize volumes proactively.

Postiz on Klutch.sh gives you reproducible Docker builds, managed secrets, and optional persistent storage—without extra YAML or CI steps. Configure ports, env vars, and storage, then ship your social scheduling workspace.