Skrum

Skrum is an open-source, self-hostable place for a team's rituals. It is multi-tenant (workspaces contain teams, teams run sessions), lets guests join a session through a link, and is available in English, French, Spanish and German. It is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later, see LICENSE).

Run with Docker · Configuration · Connect an AI assistant · Local development · Contributing

Features

• Retrospectives: realtime boards from templates, anonymous cards, votes, a return-on-time-invested poll, and action items with an owner, a due date and reminders.
• Planning poker: custom decks, anonymous rounds, tasks imported from an issue tracker.
• Whiteboards: a shared canvas for the whole team.
• Surveys: health check, team pulse, eNPS and quick questions.
• Games: nine icebreakers for standalone game rooms or retrospectives: Draw & Guess, Sprint in one GIF, Hangman, Decoded, Two truths and a lie, Mood weather, Guess who?, Quick question and Undercover. Undercover supports 3–12 players, private words, spoken clues and elimination votes controlled by the host.
• Integrations: Slack, Telegram, Microsoft Teams, Mattermost, Jira (Cloud and Data Center), Linear, GitHub and outgoing webhooks.
• Sign-in: password, passkeys, two-factor authentication, and single sign-on with Google, GitHub, Microsoft Entra or any OpenID Connect provider.
• AI assistants: a Model Context Protocol server, so an assistant reads and updates what you allow.
• Self-hosting: one container for the web server, websockets, queue and scheduler, on PostgreSQL, MariaDB, MySQL or SQLite.

Documentation: https://arnaud-ritti.github.io/skrum/docs/

Run with Docker

The image is published to GitHub Container Registry.

curl -O https://raw.githubusercontent.com/arnaud-ritti/skrum/main/compose.production.yaml
curl -o .env https://raw.githubusercontent.com/arnaud-ritti/skrum/main/.env.production.example
docker run --rm --entrypoint php ghcr.io/arnaud-ritti/skrum:latest artisan key:generate --show

The last command prints the value for APP_KEY. Fill the three values at the top of .env:

• APP_URL: the public address of the instance, as typed in the browser;
• APP_KEY: the value just printed;
• DB_PASSWORD: a strong password for the database.

Everything else has a working default. The same file lists, commented, what an install most often changes: the address Caddy serves, the host ports, the image version (SKRUM_IMAGE), the instance name and time zone, and outgoing mail, which goes to the log until the MAIL_* variables are set.

Compose reads .env from the project directory twice: to fill the ${...} values in compose.production.yaml (image, ports, database name, user and password) and as the app container's environment. To use a file with another name, pass --env-file <file> to every docker compose command; it feeds the ${...} values, so also point the env_file: entry of the app service at that file.

Start it:

docker compose -f compose.production.yaml up -d

Skrum answers on http://<host>: plain HTTP on port 80, meant for a TLS-terminating reverse proxy in front, whose forwarded headers are trusted by default (TRUSTED_PROXIES). To let the built-in Caddy obtain certificates itself, set SERVER_NAME to your domain: see SERVER_NAME.

[!WARNING] The first account to sign up becomes the instance admin. Create it right after starting, and consider SKRUM_SIGNUP_MODE to control who can sign up afterwards.

If a container keeps restarting, docker compose -f compose.production.yaml logs app shows why (for example a missing variable, or APP_DEBUG left enabled).

Upgrading

Back up the database first (the pgsql-data volume with the default Compose file) and the app-storage volume, then pull the new image and recreate the containers:

docker compose -f compose.production.yaml pull && docker compose -f compose.production.yaml up -d

Migrations run automatically when the container starts. Prefer pinning SKRUM_IMAGE to a version tag over latest, so upgrades happen when you choose.

To show a maintenance page while you work, run php artisan down --retry=<seconds> in the application container (docker compose -f compose.production.yaml exec app php artisan down --retry=1800) and php artisan up when done. The page shows the time of return taken from --retry; it reloads by itself every 30 seconds and links to the status page.

The admin footer shows the running version (SKRUM_VERSION, set by the published images). The check for a newer release is on by default (SKRUM_UPDATE_CHECK_ENABLED=true). Set it to false to disable the environment default; a saved Administration › General choice takes precedence. When enabled, the instance asks SKRUM_UPDATE_FEED once a day and sends nothing about itself.

Upgrading to the release that adds the app-storage volume: until then, profile photos and brand assets lived in the container itself, and the new volume starts empty. Once, copy them out of the running container before up -d, then back into the volume and give them to uid 82 (www-data). With compose.production.mariadb.yaml or compose.production.sqlite.yaml, use that file in each command:

docker compose -f compose.production.yaml cp app:/app/storage/app ./storage-app-backup
docker compose -f compose.production.yaml pull && docker compose -f compose.production.yaml up -d
docker compose -f compose.production.yaml cp ./storage-app-backup/. app:/app/storage/app
docker compose -f compose.production.yaml exec -u root app chown -R 82:82 /app/storage/app

This is the beginning of the README. Read the rest at the original. Read the full README ↗