Development environment

This runs PostQueen from its source, with the frontend and the backend reloading as you edit. It is the setup for changing the code or adding a network. To run PostQueen without changing it, Docker Compose is shorter. The source is at GkhanKINAY/postqueen-app. The contributing guide there covers pull requests.

On your machine
In a dev container

What you need

Tool	Version
Node.js	22.13 or newer, below 23. The repository refuses other versions.
pnpm	10.6.1, through Corepack: `corepack enable`
Docker	Any recent version, for PostgreSQL, Redis and Temporal

macOS and Linux are tested. Windows and WSL are not.

Set it up

Clone the repository

git clone https://github.com/GkhanKINAY/postqueen-app.git
cd postqueen-app

Start the databases and Temporal

pnpm run dev:docker

This starts docker-compose.dev.yaml:

Service	Address
PostgreSQL	`localhost:5432`, user `postqueen-local`, password `postqueen-local-pwd`, database `postqueen-db-local`
Redis	`localhost:6379`
Temporal	`localhost:7233`, with its web UI at http://localhost:8080
pgAdmin	http://localhost:8085, `admin@admin.com` / `admin`
RedisInsight	http://localhost:5540

Create .env

cp .env.example .env

One .env at the repository root serves every app. The database, Redis and Temporal addresses already match the containers. Change these before the first run:

# Sign-in over plain HTTP
NOT_SECURED=true
# Local storage needs a folder: an absolute path to the repository's uploads folder
UPLOAD_DIRECTORY=/absolute/path/to/postqueen-app/uploads
NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY=uploads
# Starts the recurring workflows
RUN_CRON=true

And delete the line POSTQUEEN_GENERIC_OAUTH="false". Any value turns single sign-on on, which replaces the Google button with an unconfigured one.Add a network’s keys only when you work on that network: Channel developer apps.

Install

pnpm install
pnpm run prisma-db-push

pnpm install also generates the Prisma client. prisma-db-push creates the schema in the local database.

Run it

pnpm run dev

Open http://localhost:4200 and sign up.

The repository describes a dev container with Node 22, pnpm, PostgreSQL 17, Redis 7 and Temporal. You need only Docker and an editor that supports dev containers. Nothing is published to your host except the app’s ports, so it runs next to an existing Compose install.Give Docker enough memory: the watch builds and Temporal’s Elasticsearch together need several gigabytes.

Open the repository in the container

In VS Code with the Dev Containers extension, clone the repository, open it and choose Reopen in Container. From a terminal, use the Dev Container CLI:

git clone https://github.com/GkhanKINAY/postqueen-app.git
devcontainer up --workspace-folder postqueen-app

The first start installs the dependencies and creates the schema. When there is no .env, it writes one from .env.example with the database, Redis and Temporal addresses pointed at the container’s services and NOT_SECURED=true added. An existing .env is left alone, and the container’s own settings take priority over it.

Fix the two .env traps

Add UPLOAD_DIRECTORY=/workspaces/postqueen-app/uploads and delete POSTQUEEN_GENERIC_OAUTH="false", as on your own machine.

Run it

pnpm run dev

From the CLI: devcontainer exec --workspace-folder postqueen-app pnpm run dev. Open http://localhost:4200; the editor forwards the port.The container’s first-start message suggests pnpm run dev-backend. That starts no orchestrator, so nothing publishes: use pnpm run dev.

What runs

Part	Port	Started alone with
Frontend (Next.js)	4200	`pnpm run dev:frontend`
Backend (NestJS)	3000	`pnpm run dev:backend`
Orchestrator (Temporal worker)	3002, health only	`pnpm run dev:orchestrator`
Browser extension	8081, hot reload	part of `pnpm run dev`

pnpm run dev starts all four. pnpm run dev-backend starts only the frontend and the backend: enough for interface work, but nothing publishes and no mail is sent without the orchestrator. From source the frontend and backend are separate servers, so NEXT_PUBLIC_BACKEND_URL is http://localhost:3000 here, while the image puts both behind one port and uses /api. To work on the frontend against a backend that already runs in the Compose stack, set DEV_BACKEND_PROXY=http://localhost:4007 and NEXT_PUBLIC_BACKEND_URL=/api, and run pnpm run dev:frontend.

Commands

Command	What it does
`pnpm run dev`	Everything, with hot reload
`pnpm run dev-backend`	Frontend and backend only
`pnpm run dev:docker`	The local PostgreSQL, Redis and Temporal
`pnpm run build`	Production build of the frontend, backend and orchestrator
`pnpm run prisma-generate`	Regenerate the Prisma client after editing the schema
`pnpm run prisma-db-push`	Apply the schema to the local database
`pnpm test`	The tests: every `*.spec.ts` under `apps/` and `libraries/`, with Node’s test runner through `tsx`
`pnpm run lint`	ESLint, from the repository root only

The repository

It is a pnpm workspace: apps/* and libraries/*.

Folder	What it holds
`apps/frontend`	The web app, Next.js with Tailwind
`apps/backend`	The API, NestJS: controllers that call services from `libraries`
`apps/orchestrator`	Temporal workflows and activities: publishing, token refresh, analytics sync, email, video conversion
`apps/extension`	The browser extension that connects Skool
`apps/commands`	Command-line maintenance tasks
`apps/sdk`	The `@postqueen/node` SDK
`libraries/nestjs-libraries`	Shared server code: the Prisma schema, the network integrations, services and repositories
`libraries/react-shared-libraries`	Shared React code and the translations
`libraries/helpers`	Small utilities used on both sides

The Prisma schema is libraries/nestjs-libraries/src/database/prisma/schema.prisma. Imports use the @gitroom/* alias from tsconfig.base.json: it is the real workspace alias, kept from the project PostQueen started from.

Behind an HTTPS tunnel

Some networks accept only an https redirect address. On plain http, PostQueen sends Slack, TikTok, TikTok Business, Threads, Instagram (Standalone) and VK through redirectmeto.com, and the rest refuse. To test those networks locally, put the frontend behind a tunnel such as ngrok or Cloudflare Tunnel and set FRONTEND_URL to the tunnel’s https address. The redirect URI you register with the network is then the tunnel address plus /integrations/social/<network>.

If something goes wrong

The backend stops at start with UPLOAD_DIRECTORY is not set

Set UPLOAD_DIRECTORY to an absolute, writable folder, as in the .env step.

Password authentication failed

DATABASE_URL does not match the dev container: user postqueen-local, password postqueen-local-pwd, database postqueen-db-local.

Posts never publish

The orchestrator is not running, or Temporal is not. Use pnpm run dev, and check the Temporal UI at http://localhost:8080.

The dev servers or the build run out of memory

Give Node more room in the same shell: export NODE_OPTIONS="--max-old-space-size=4096", then run pnpm run dev or pnpm run build again. The dev container already sets a higher limit.

Start here

Install

Domain and HTTPS

Configure

Channel developer apps

Operate

Develop

What you need

Set it up

What runs

Commands

The repository

Behind an HTTPS tunnel

If something goes wrong

Next steps

Add a network

Configuration reference

​What you need

​Set it up

​What runs

​Commands

​The repository

​Behind an HTTPS tunnel

​If something goes wrong

​Next steps

Add a network

Configuration reference

What you need

Set it up

What runs

Commands

The repository

Behind an HTTPS tunnel

If something goes wrong

Next steps