RetroGemini

Private-by-design, real-time Scrum retrospectives and team health checks for organizations that need to keep their data on their own infrastructure.

RetroGemini was created at the State of Geneva and is already used by around 30 internal teams. Because candid retrospective feedback can be sensitive, our public administration cannot send it to external cloud services. RetroGemini keeps the complete application and its data under the organization's control.

This makes it a strong fit for public-sector, healthcare, finance, regulated, privacy-conscious, and air-gapped environments — or simply for teams that prefer to own their tools and data.

No external service is required at runtime. SMTP and OpenAI-compatible AI features are optional and disabled unless you configure them.

If RetroGemini solves a problem for your organization, please star the repository so more self-hosting and Agile teams can find it.

Demo board with fictional data.

Try it in 60 seconds

You only need Docker:

docker run --pull=always -d \
  --name retrogemini \
  -p 8080:8080 \
  -v retro-data:/data \
  jpfroud/retrogemini:latest

Open http://localhost:8080, create a team, and start a retrospective.

The named Docker volume keeps your test data across container restarts. For a production deployment, also set a stable SESSION_TOKEN_SECRET, use HTTPS through your reverse proxy, and review the configuration below.

One-click temporary demo

The Deploy to Render button above creates a free personal evaluation instance from the latest published Docker image.

Render's free web services sleep after 15 minutes without traffic and use an ephemeral filesystem. The demo's SQLite data is therefore cleared whenever the service sleeps, restarts, or redeploys. Use this path to explore the product, not for a real team deployment.

What teams get

Why RetroGemini

• Your retrospective data stays with you. The core application makes no external service calls and can run on an isolated network.
• It is designed for real facilitation. Sessions follow a clear workflow rather than presenting an unstructured sticky-note board.
• It supports the work after the retro. Actions, decisions, health checks, reports, and follow-up remain visible over time.
• It starts small and scales. Use one Docker container with SQLite, or PostgreSQL plus Redis/PostgreSQL adapters for multiple pods.
• It has real organizational usage. The product is shaped by feedback from approximately 30 teams at the State of Geneva.
• It is open source with a permissive public-domain license. Use, adapt, and redistribute it without vendor lock-in.

Docker Compose

git clone https://github.com/republique-et-canton-de-geneve/RetroGemini.git
cd RetroGemini
docker compose up -d app

The application is available at http://localhost:8080, with data persisted in the retro-data volume.

Production example

Generate and keep a stable secret in your secret manager, then run:

docker run --pull=always -d \
  --name retrogemini \
  --restart unless-stopped \
  -p 8080:8080 \
  -v /path/to/retrogemini-data:/data \
  -e SESSION_TOKEN_SECRET='replace-with-a-long-random-secret' \
  -e SUPER_ADMIN_PASSWORD='replace-with-a-strong-admin-password' \
  jpfroud/retrogemini:latest

Put RetroGemini behind an HTTPS reverse proxy before exposing it outside a trusted network.

Deployment options

Docker

Build the image yourself if you do not want to pull the published image:

docker build -t retrogemini .
docker run -d \
  --name retrogemini \
  -p 8080:8080 \
  -v /path/to/data:/data \
  retrogemini

Kubernetes / OpenShift

See the Kubernetes and OpenShift guide. The container runs as a non-root user and exposes /health and /ready probes.

Railway

1. Fork this repository.
2. Create a Railway project from your fork.
3. Add a persistent volume mounted at /data.
4. Deploy using the included Dockerfile and railway.toml.

Without a persistent volume, SQLite data is ephemeral and will be lost during redeployments.

Configuration

All configuration is provided through environment variables. See .env.example for the complete list.

Data persistence

RetroGemini supports two database backends:

• SQLite for a simple single-container or single-pod deployment.
• PostgreSQL for production and multi-pod deployments.

For SQLite, the server tries these locations in order:

1. DATA_STORE_PATH
2. /data/data.sqlite
3. /tmp/data.sqlite — ephemeral
4. ./data.sqlite

A warning is logged when ephemeral storage is used.

For multiple pods, Socket.IO uses Redis when REDIS_URL or REDIS_HOST is configured. Otherwise it uses the PostgreSQL adapter when PostgreSQL is the data store.

Corporate proxy and custom CA

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt

The same variables can be configured in Docker Compose, Kubernetes, or OpenShift.

Architecture

• Frontend: React 19, TypeScript, Vite, Tailwind CSS
• Backend: Express 5, Socket.IO 4
• Storage: SQLite with WAL mode or PostgreSQL
• Scale-out: Redis or PostgreSQL Socket.IO adapter
• Container: Node 26 Alpine, non-root user

The application is designed to survive rolling updates: session state is persisted, WebSocket clients reconnect automatically, and participants rejoin their active session.

Quality and security

Every pull request runs linting, TypeScript checks, unit and integration tests, a production build, dependency review, CodeQL analysis, and container vulnerability scanning.

Useful local checks:

npm run lint
npm run type-check
npm test
npm run build
npm run test:e2e

See MAINTENANCE.md, HARDENING_STATUS.md, SECURITY.md, and ACCESSIBILITY.md for details.

Accessibility is gated on every pull request — an axe-core run over six screens and eslint-plugin-jsx-a11y inside the lint budget. Both are ratchets: the number they allow may fall, never rise. ACCESSIBILITY.md states what is tested, what was fixed, and what is still missing.

Development

Requirements: Node.js 22+ and npm.

npm install
npm run start

In another terminal:

npm run dev

The backend runs on port 3000 and the Vite development server on port 5173.

Built with AI assistance, not dependent on AI

RetroGemini was developed with extensive assistance from Gemini, Claude, and Codex. That describes the development process, not a runtime dependency: the application works without an internet connection or an AI service.

Administrators can optionally connect an OpenAI-compatible model for grouping suggestions and summaries. Those features remain off until explicitly configured.

Contributing

Bug reports, feature requests, documentation improvements, translations, and code contributions are welcome. Read CONTRIBUTING.md before opening a pull request.

If you deploy RetroGemini, consider opening a discussion or issue to share your environment and feedback. Real-world deployment notes help other organizations adopt it.

License

RetroGemini is released into the public domain under The Unlicense. You may use, copy, modify, and distribute it for any purpose without conditions.