Skip to main content
This sets up PostQueen from source on your own machine, with the frontend and backend reloading as you edit. It is the right setup for writing code, adding a provider or fixing a bug. If you only want to run her, not change her, Docker Compose is much shorter and it is the supported path.
Prefer to let your editor do the setup? Dev Container runs this same environment inside a container, with Node, pnpm and the databases already in place.

​
Tested configurations

macOS and Linux. Windows and WSL are not officially supported and are not well tested, so help with problems specific to them may be limited.

​
What you need

Node 22 specifically. The repository declares >=22.12.0 <23.0.0, and installs fail on older versions. If you use a version manager, switch to 22 in this directory before you start.
You do not need to install pnpm by hand. Node ships with Corepack, which fetches the exact version this repository expects:

​
Set it up

1

Clone the repository

2

Start the databases and the scheduler

That runs docker-compose.dev.yaml, which brings up PostgreSQL, Redis, Temporal and two optional inspection tools. Temporal is included, so there is no second repository to clone for it.
3

Create your .env

One shared .env at the repository root serves every app in the monorepo. The defaults match the containers you just started, so for a plain local setup there is nothing to change. The values that matter:
NOT_SECURED=true is what lets sign-in work over plain HTTP. It belongs in local development and nowhere else.
Add provider keys only for the networks you actually want to test against. Each one is covered under Providers.
4

Install dependencies

This also generates the Prisma client for you, so there is no separate generate step.
If this dies with a JavaScript heap error, give Node more room:
5

Create the database schema

6

Run it

Open http://localhost:4200.
pnpm run dev also starts the browser extension build, which wants port 8081, and pgAdmin from the previous step is already using it. If that clashes, run the two you actually need:
That starts only the backend and the frontend.

​
What runs where

Note that these are not the ports the container image uses. From source the frontend and backend are separate servers on separate ports, while the published image puts a small proxy in front of both on a single port. That is why NEXT_PUBLIC_BACKEND_URL is http://localhost:3000 here and carries an /api suffix in a Compose install.

​
Useful commands

​
The layout

It is a pnpm workspace, not an Nx-driven build, so tasks run through pnpm --filter.
Imports use the @gitroom/* prefix. That is intentional and correct, it is the real workspace alias in tsconfig.base.json.

​
If something goes wrong

The containers are probably not up. docker ps should list postqueen-postgres and postqueen-redis. If not, pnpm run dev:docker again and watch for errors.
DATABASE_URL does not match the container. The dev stack creates the user postqueen-local with password postqueen-local-pwd and the database postqueen-db-local. Copy the line from the step above exactly.
pgAdmin and the extension’s hot reload both want it. Use pnpm run dev-backend, or stop pgAdmin with docker stop postqueen-pg-admin.
Temporal is not reachable. It is what actually fires posts. Check TEMPORAL_ADDRESS is localhost:7233 and that the dashboard answers at http://localhost:8080.
Set NOT_SECURED=true in .env. Without it the login cookie requires HTTPS, which you do not have locally.
Still stuck? The support page has where to ask.

​
Next Steps

Add a provider

What a new social network needs on the backend and the frontend

Developer guide

How the codebase is organised and how to contribute

Architecture

The services behind a post, and what each one does

Configuration reference

Every environment variable she reads