Retrospected: a self-hostable real-time retrospective board built on React, Socket.IO and Postgres

What Retrospected is, and the team it is aimed at

Retrospected describes itself as a free AI-powered real-time Agile Retrospective Board for engineering teams. The repository is both the source of the hosted product at retrospected.com and, in the author's own words, a technology demo built on current JavaScript and TypeScript libraries. That dual purpose explains a lot of the codebase: the stack moves quickly, and version 5.5.0 replaced ESLint and Prettier with Biome in a single migration.

The audience is narrower than "anyone running a retro". The README points at two paths: use the public instance, or host it on your premises. The second path is the interesting one for a company that cannot put sprint notes on someone else's server. The self-hosting documentation lives at docs.retrospected.com, and the quick-start guide is the entry point the README recommends. The project also carries a self-hosting licence product, so the intended self-hosted user is a paying customer, not a hobbyist looking for a weekend project.

If you only need a board for a five-person team and have no data residency constraint, the public app is the shorter route. The self-hosted path exists for the cases where the board has to sit behind your own network boundary.

How the real-time board actually works

The architecture is a split frontend and backend. The frontend is React 18 with React Router 6, Recoil for global state, MUI 5 for components and Emotion for styling, bundled by Vite. The backend runs on Node 24 LTS, talks to Postgres, and uses Socket.IO for the live session. Passport handles OAuth against Google, Twitter, GitHub, Slack, Microsoft and Okta. Persistence is Postgres, and the docker-compose file pins the database image to postgres:16.

Live collaboration is the part that shapes deployment. Because the backend holds Socket.IO connections, the compose file declares the backend as depending on redis, and .env.example exposes REDIS_ENABLED and REDIS_FOR_SOCKETIO_ENABLED, both false by default. Redis is therefore optional in the default single-instance setup and becomes relevant when you scale out. The README lists Kubernetes for scaling, with a parenthetical joke about 10M+ users, so the project does not pretend to have solved that.

State changes propagate over the socket connection rather than through polling, which is why the frontend cannot start before the backend is healthy. Version 5.5.2 added a health check specifically so that the frontend waits for the backend during integration tests. The same ordering matters in production: bring up Postgres, then the backend, then the frontend.

Cards can be reordered and grouped by drag and drop using React Beautiful DND. Version 5.3.0 added options to restrict title editing and to restrict ordering and grouping to the moderator, which is a direct response to the failure mode where one person rearranges the whole board while everyone else is still writing.

Installing Retrospected with Docker Compose

The README states that you can start an instance in five minutes by following the quick-start guide in the docs. The repository ships a docker-compose.yml with four services: postgres, backend, pgadmin and frontend. The backend image is retrospected/backend:latest, and the compose file expects a licence key and an admin email.

The compose file warns that the Postgres password must be set before the first run, because the database cannot change it afterwards, and that it must match DB_PASSWORD in the backend section. The relevant environment block looks like this:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: some-password
      POSTGRES_USER: postgres
      POSTGRES_DB: retroboard
  backend:
    image: retrospected/backend:latest
    environment:
      LICENCE_KEY:
      SELF_HOSTED_ADMIN: 'your@email.com'
      DB_PASSWORD: some-password
      SESSION_SECRET: im-a-secret

SELF_HOSTED_ADMIN is the user who becomes admin on the instance. SESSION_SECRET can be any string according to the comment in the file, but you should still replace it rather than ship the example value.

For development outside Docker, the repository root package.json defines scripts that delegate into the subprojects. The .env.example file at the root lists the variables the backend reads, including DB_HOST, DB_PORT, BACKEND_PORT and BASE_URL.

yarn
cd backend && yarn migrate

The mig script at the root is defined as cd backend && yarn migrate, so either form reaches the same migration command. Run it before the first start, otherwise the backend will connect to an empty schema. The frontend and backend scripts in the root package.json start each side separately, which is the normal development loop.

For a production-style local build, the Makefile has a local target that builds retrospected/backend:local and retrospected/frontend:local from the backend and frontend Dockerfiles. The build target uses buildx with TARGET_ARCHS defaulting to linux/amd64, linux/arm64 and linux/arm/v7, which is how the project publishes multi-architecture images.

The AI agile coach and what it costs you in configuration

The AI features are backed by OpenAI. .env.example carries OPEN_AI_API_KEY, OPEN_AI_FREE_LIMIT set to 5 and OPEN_AI_PAID_LIMIT set to 1000. Version 5.3.0 notes that the Agile Coach moved to ChatGPT 4. The two limit variables mean the coach is metered: free accounts get a small number of calls, paid accounts a larger one.

This is the part of the project most likely to surprise a self-hoster. Enabling the coach means putting an OpenAI key in your environment and accepting that retrospective content, or some representation of it, leaves your infrastructure. If the reason you are self-hosting is data control, the AI coach is in tension with that goal. No local model option is documented in the repository.

The same applies to the other integrations. Stripe variables are present in .env.example because the hosted product sells subscriptions, and SendGrid or SMTP variables exist for mail. A self-hosted instance that only needs boards can leave most of these blank, but the defaults still reference the commercial plumbing.

Where Retrospected is the wrong tool

The licence situation is the first limitation. The repository is GPL-3.0, but the README says the quick-start deployment runs a demo version that you turn into a fully licensed version by purchasing a Self Hosted licence. Version 5.5.1 even hardcodes a licence for the French Ministère de l'intérieur. So the open source code and the usable self-hosted instance are not the same thing, and anyone expecting to clone, build and run without a key should read the self-hosting docs before assuming otherwise. The README does not document what an unlicensed instance restricts, and that silence is itself a reason to check.

Operationally, the stack is heavier than a retrospective board sounds. You need Postgres 16, a Node backend, a frontend container, and optionally Redis and pgAdmin. The compose file also exposes pgAdmin on port 1801 by default, with a default email and password of admin@admin.com and admin. Leaving that reachable is a straightforward way to lose a database. The file tells you to change the password before the first run, but the port mapping is the part people forget.

There is also a maintenance cost that comes from the project's own framing as a demo of current libraries. Version 5.5.0 swapped the entire linting and formatting toolchain to Biome, and the dependency list changes often enough that the README keeps a struck-through list of libraries previous versions used. Upgrades are not just security patches. If you fork the frontend, expect to rebase against that churn.

Finally, the AI coach is not a substitute for facilitation. It generates suggestions from board content. A team that expects the tool to run the retro for them will get generic output, and the free limit of 5 calls will run out quickly.

Retrospected compared with a plain shared document

The obvious alternative is not another retro product but a shared document or whiteboard that the team already has. The difference in approach is real. A document is a passive artifact: everyone edits the same page and the facilitator resolves conflicts by hand. Retrospected keeps a session model with participants, a moderator role, per-card authorship, and optional timers. Version 5.4.0 separated the moderator from the person who created the retro and allowed finer-grained timers, which matters when you want a silent writing phase followed by a discussion phase without watching a clock yourself.

Socket.IO is what makes that model work. When someone adds a card, the other participants see it without refreshing, and the "I'm ready" state is tracked per session. Version 5.3.0 fixed a bug where that button became hidden with too many connected users, which tells you the design assumes a room of people acting at the same time.

A document also has no notion of hiding authors. Retrospected supports disabling "Show Author" globally, and .env.example includes DISABLE_REVEAL_NAMES. If your team's retros depend on anonymous input, that is a feature a shared doc cannot replicate without process discipline.

The trade-off runs the other way too. A document needs no Postgres, no containers, no licence key and no migration command. If your retro is six people and a list of three questions, the document wins on operational cost, and Retrospected's extra machinery buys you nothing.

Maintenance, licensing and upgrade reality

The last push to the repository was on 2026-07-12, and the repository is not archived. The version in package.json is 5.5.2, and the versions history in the README shows a steady stream of small releases: dependency upgrades, a Biome migration, a Postgres 16 upgrade, hotfixes for grouping and for the ready button. That cadence is healthy, but it also means the self-hosted images move. The compose file references retrospected/backend:latest, which will pull whatever was published most recently. Pinning a specific tag is the safer choice for a production instance, and the Makefile shows the project does tag images with PACKAGE_VERSION.

On licensing, the code is GPL-3.0 while the self-hosted product is sold as a licence. Those two facts sit together awkwardly, and the repository does not resolve the tension. If you plan to modify and redistribute Retrospected, or to run it as part of a commercial offering, get a proper reading of the GPL-3.0 terms alongside the self-hosting licence rather than assuming the open source licence alone covers your use. This is not legal advice, and the README does not discuss the boundary.

The practical upgrade path is Docker images plus the migration command. Because the backend owns the schema, a version bump can require a migration run before the new backend starts. The compose file does not show a migration step in the backend service, so a self-hoster upgrading across versions should plan for running yarn migrate against the new backend image rather than assuming the container does it.

Editorial conclusion

Retrospected fits teams that want a retrospective board they can run on their own infrastructure and are willing to deal with a licence key, a Postgres volume and the environment variables in .env.example. It is a poor fit for anyone who needs a plain GPL binary with no commercial strings attached, because the self-hosting path is written around a purchased licence. Before committing, verify what an unlicensed instance actually restricts, and confirm that the licence key you buy covers the number of people who will connect to your board.

Frequently asked questions

Official sources

1. antoinejaussoin/retro-board on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README