Initiative

A self-hosted project management platform designed for friend groups, gaming communities, and small teams who want an intuitive way to organize projects, share documents, and track tasks — without the complexity of enterprise tools.

Pre-release software — this project hasn't reached v1.0.0 yet. The API may change between minor releases.

What is Initiative?

Initiative is project management for people who don't want to think about project management. It's built for groups that need to coordinate work, share information, and stay on the same page — whether you're running a tabletop campaign, organizing a community event, or managing a small team.

• Guilds keep each group's data completely separate — run multiple communities from one instance
• Initiatives organize related projects and documents so nothing gets lost
• Drag-and-drop boards make task tracking visual and immediate
• Collaborative documents let your team write and edit together in real time
• Simple sharing — control who sees what without needing a degree in access management
• Self-hosted with Docker — your data stays on your hardware

Key Features

Guilds

Each guild is a completely separate workspace — your D&D group and your work team never see each other's data, even on the same server.

• True data isolation: PostgreSQL Row Level Security enforces guild boundaries at the database layer
• Switch between guilds instantly: Join multiple guilds and move between them with one click
• Invite links: Share links with optional expiry dates and usage limits
• Controlled creation: Optionally restrict guild creation for hosted deployments

Guild settings:

Initiatives & Projects

Initiatives group related projects and documents together — think of them as folders for an entire effort (a campaign, an event, a product).

• Everything in one place: Bundle projects, documents, and team members under a single initiative
• Automatic scoping: Members only see initiatives they belong to
• Custom project boards: Drag-and-drop Kanban boards with customizable task statuses
• Color-coded organization: Visual distinction with initiative-specific colors

Initiatives page:

Simple Sharing & Permissions

Sharing is straightforward: add people to a guild, add them to an initiative, then choose who can see or edit each project and document. No complicated admin panels required.

• Initiative roles: Create roles like "player" or "DM" with different feature access
• Project & document sharing: Set owner, write, or read access per user or per role
• Role-based grants: Share with an entire role at once instead of adding people one by one

For details on how access control is enforced under the hood, see SECURITY.md.

Initiative role permissions:

Project/Document access control:

Rich Task Management

• Multiple views: Table, Kanban, Calendar, and Gantt with row virtualization for large datasets
• Priority levels: Low, medium, high, and urgent with visual indicators
• Flexible scheduling: Start dates, due dates, and recurring tasks
• Subtasks: Break down complex work with completion tracking
• Multiple assignees: Assign tasks to multiple team members
• Server-side pagination & sorting: Multi-column sort with advanced filtering
• My Tasks dashboard: Personal cross-guild view with date grouping and timezone support

Project Kanban view (Table, Kanban, Calendar, and Gantt views supported):

Task details:

Collaborative Documents

• Rich text editing: Full-featured editor with JSONB storage
• Live collaboration: Real-time multi-user editing via WebSocket
• File documents: Upload and manage PDFs, DOCX, and other file types with permission-gated downloads
• Document templates: Create reusable templates for common workflows
• Threaded comments: Discuss documents with nested comment threads

Document editor:

Command Center

Press Cmd+K / Ctrl+K to instantly navigate to projects, tasks, documents, and pages with fuzzy search. Available via sidebar shortcut or 3-finger tap on mobile.

Authentication

• Email & password or OpenID Connect (OIDC) SSO — connect your existing identity provider
• OIDC claim-to-role mapping: Automatically assign guild and initiative memberships from identity provider claims
• Encryption at rest for sensitive data — see SECURITY.md for the full security architecture

Notifications

• Real-time updates: WebSocket-based live updates for collaborative work
• Per-channel preferences: Independent email and mobile push toggles per notification category
• Overdue task digests: Configurable email digests for overdue tasks
• Mobile push: Firebase Cloud Messaging support for iOS and Android

AI Integration

• Bring Your Own Key (BYOK): Configure API keys for OpenAI, Anthropic, Ollama, or OpenAI-compatible APIs
• Hierarchical settings: Platform, guild, and user-level AI configuration with override controls
• AI-powered tasks: Generate task descriptions, subtasks, and document summaries

Internationalization

• Full i18n support with 16 translation namespaces
• English and Spanish locales included (community translations welcome)
• Locale-aware AI content generation

Quick Start

Docker Compose (Recommended)

# 1. Download the example compose file
curl -O https://raw.githubusercontent.com/Morelitea/initiative/main/docker-compose.example.yml
cp docker-compose.example.yml docker-compose.yml

# 2. Edit configuration — set a secure SECRET_KEY at minimum
nano docker-compose.yml

# 3. Start the application
docker-compose up -d

# 4. Access Initiative at http://localhost:8173

What's included:

• PostgreSQL 17 with persistent storage and Row Level Security
• Automatic database role creation and migrations
• React frontend served via FastAPI
• Health checks and automatic restarts

First-time setup:

1. The first user to register becomes the platform admin
2. Configure SMTP in the admin panel to enable email notifications
3. Create your first guild and start inviting team members

See Key Environment Variables for full configuration options.

Docker Hub Images

docker pull morelitea/initiative:latest    # latest release
docker pull morelitea/initiative:0.32      # specific minor

Images support linux/amd64 and linux/arm64 architectures.

Configuration

Key Environment Variables

For FCM setup, see docs/en/admin/push-notifications.md. For a complete list of options, see backend/.env.example.

Database connections

Initiative needs three PostgreSQL connection strings, and the container will not start without all of them (DATABASE_URL_APP and DATABASE_URL_ADMIN have no defaults — a missing one aborts startup with a config validation error). They work as a set:

• DATABASE_URL — the provisioning role (app_provisioner): runs migrations and creates/removes guild schemas, and auto-creates the two roles below. It is deliberately not a superuser — the example compose file creates app_provisioner automatically when the database volume is first initialized, and the app warns at boot if this URL connects as a superuser (existing installs: run backend/scripts/create-provisioner.sql once to switch).
• DATABASE_URL_APP — connects as app_user. The password in this URL is the password the app_user role is created/updated with.
• DATABASE_URL_ADMIN — connects as app_admin, the system role for background jobs and startup seeding. Likewise, its password seeds that role.

In other words, the provisioning URL bootstraps the roles, while the APP/ADMIN URLs both define those roles' passwords and are what the running app actually uses. The example compose file wires all three together with matching credentials, so the default docker-compose up path works as-is. If you write your own compose file or use docker run, set all three.

Running as a non-root user (PUID/PGID)

The container starts as root so its entrypoint can create the runtime user, fix ownership on the uploads volume, and then drop privileges with gosu. The main uvicorn process runs unprivileged — by default UID/GID 1000:1000 with no Linux capabilities.

To run as a different UID/GID (for example, to match the NAS user that owns the uploads volume), set the PUID/PGID environment variables. Do not add a Docker user: (Compose) or --user (run) override — that starts the entrypoint as non-root, so it can't create the user and fails with fatal: Only root may add a user or group to the system. PUID/PGID is the supported knob; 0 (root) is rejected.

MCP Server

Initiative ships an optional, in-app MCP server so MCP-compatible AI assistants (such as Claude Code) can work with your data on your behalf. It is route-backed: every tool call runs through the real API with your authentication and the same Row-Level-Security access rules as the app, so a tool can only ever reach data you can reach — scoped per guild and initiative. It is off by default.

Enable it

Set ENABLE_MCP=true (in .env or your container environment) and restart — the endpoint is mounted at startup:

ENABLE_MCP=true

The server is then served at /api/v1/mcp/ (note the trailing slash) on your deployment's public host — i.e. <APP_URL>/api/v1/mcp/, using the same APP_URL you set in .env. (For local testing that's http://localhost:8173/api/v1/mcp/; localhost is for testing only, not your launched URL.) Because it is in-app, it ships in the Docker image — flipping the env var is all a deployer needs. Leave it off where you don't want the surface; it is gated at the infra level, not by a UI toggle.

Connect a client (Claude Code example)

1. Mint a personal API key in Settings → Security. Tick Read-only for read access only (recommended for most uses); pin it to a single guild to limit its blast radius. A full-access key is required only if you want the write tools.

2. Register the server:

   claude mcp add --transport http initiative \
     https://your-host/api/v1/mcp/ \
     --header "Authorization: Bearer ppk_your_key_here"

3. Use it — ask your assistant things like "list my projects in Initiative" or "add a task to the Auth project." Write actions are confirmed by the client before they run.

What it can access

The surface is curated and default-deny — only the following are exposed. Everything else (documents, queues, counters, calendar, tags, members, admin, auth, settings, deletes, bulk operations, and AI generation) is not.

Reads (any API key):

Writes (full-access key only — a read-only key is rejected with 403; each is confirmed in the client):

Security notes

• Least privilege: prefer a read-only, single-guild API key. A read-only key cannot invoke the write tools.
• No ambient access: the tools carry no standing privilege — each call authenticates as the key's user and is scoped by RLS, exactly like a normal request.
• Revocable: delete the key in Settings → Security at any time; a password reset also revokes it.

Roadmap

Current Status

• Most core features are implemented and functional:
  • AGPL container: frontend + storage
  • Rich task management (Kanban, Calendar, Table, Gantt)
  • Collaborative documents with real-time editing
  • Notifications and AI integrations
  • Additional tooling menu for initaitive based features such as calender and queues
  • Self-hosted via Docker, multi-guild support

Focus for Upcoming Iterations

• Iterate and polish existing features:

  • Debugging, UX refinements, accessibility
  • Standardize testing accross the board for stability between releases
  • CI/CD improvements

• New minor features / improvements:

  • Whiteboard document type for collaborative visual planning
  • Additional templates for documents and workflows
  • Improved API endpoints for integrations

Long-Term / Philosophy

• Maintain the AGPL container as fully open-source
• Automation visuals, storage, and frontend exist in the container; the execution logic runs in a private, paid cloud instance
• Initiative is designed for small teams, communities, and personal learning projects

Technology Stack

Development

See CONTRIBUTING.md for full development setup, testing, code style, and how to submit pull requests.

Quick start: Open the project in VS Code and run Tasks: Run Task > dev:setup from the Command Palette. This starts Postgres, runs migrations, seeds test data, and launches both servers. Login with admin@example.com / changeme.

Documentation

• CONTRIBUTING.md — Development setup, testing, code style, submitting PRs
• SECURITY.md — Security philosophy and vulnerability reporting
• CHANGELOG.md — Release history
• Docker Hub — Published images
• API docs — Available at /api/v1/docs when running (Swagger UI)

Contributing

See CONTRIBUTING.md for details. PRs must target the dev branch.

By contributing, you agree to the terms of the Contributor License Agreement.

Security

See SECURITY.md for our security philosophy and how to report vulnerabilities.

License

This project is source-available under the GNU Affero General Public License v3.0 (AGPL-3.0). Copyright is retained by the project maintainers, who reserve all commercial rights.