Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/morelitea/initiative

A self-hosted, multi-tenant project management platform built for teams that need workspace isolation, granular permissions, and rich collaboration features.
https://github.com/morelitea/initiative

fastapi project-management python react typescript

Last synced: about 2 months ago
JSON representation

A self-hosted, multi-tenant project management platform built for teams that need workspace isolation, granular permissions, and rich collaboration features.

Awesome Lists containing this project

README 

          
# 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.



initiative screenshot



---



## 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:**

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:**

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](SECURITY.md).



**Initiative role permissions:**

Initiative role permissions



**Project/Document access control:**

Project DAC permissions



### 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):**

Project Kanban view



**Task details:**

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:**

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](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)



```bash

# 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](#key-environment-variables) for full configuration options.



### Docker Hub Images



```bash

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



| Variable | Description | Default |

|---|---|---|

| `DATABASE_URL` | Superuser PostgreSQL connection (migrations, role creation) | Required |

| `DATABASE_URL_APP` | RLS-enforced connection (`app_user` role) | Required |

| `DATABASE_URL_ADMIN` | Admin connection for background jobs (`app_admin` role) | Required |

| `SECRET_KEY` | JWT signing and encryption key | Required |

| `APP_URL` | Public base URL (required for OIDC callbacks) | - |

| `DISABLE_GUILD_CREATION` | Restrict guild creation to super admin | `false` |

| `ENABLE_PUBLIC_REGISTRATION` | Allow registration without invite link | `true` |

| `CAPTCHA_PROVIDER` | Captcha vendor for registration: `hcaptcha`, `turnstile`, or `recaptcha` (v2 only). Unset / unrecognised disables the gate | - |

| `CAPTCHA_SITE_KEY` | Public key sent to the SPA to render the widget | - |

| `CAPTCHA_SECRET_KEY` | Server-side key for the provider's siteverify endpoint | - |

| `BEHIND_PROXY` | Trust `X-Forwarded-For` headers | `false` |

| `FORWARDED_ALLOW_IPS` | Trusted proxy IPs (when `BEHIND_PROXY=true`) | `*` |

| `FIRST_SUPERUSER_EMAIL` | Bootstrap admin email | - |

| `FIRST_SUPERUSER_PASSWORD` | Bootstrap admin password | - |

| `SMTP_HOST` / `SMTP_PORT` / `SMTP_USERNAME` / `SMTP_PASSWORD` | SMTP server configuration | - |

| `SMTP_FROM_ADDRESS` | Email sender address | - |

| `FCM_ENABLED` | Enable Firebase Cloud Messaging | `false` |

| `PUID` | UID the container runs as (for rootless/NAS setups) | `1000` |

| `PGID` | GID the container runs as (for rootless/NAS setups) | `1000` |



For FCM setup, see [docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md). For a complete list of options, see `backend/.env.example`.



---



## 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



| Layer | Technologies |

|---|---|

| **Backend** | FastAPI, SQLModel + SQLAlchemy, PostgreSQL 17, Alembic, asyncpg |

| **Frontend** | React 19, TypeScript, Vite, React Query, Tailwind CSS, shadcn/ui, dnd-kit |

| **Mobile** | Capacitor (iOS and Android), Firebase push notifications |

| **Infrastructure** | Docker, GitHub Actions (multi-arch builds), Dependabot |



---



## Development



See [CONTRIBUTING.md](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](CONTRIBUTING.md)** — Development setup, testing, code style, submitting PRs

- **[SECURITY.md](SECURITY.md)** — Security philosophy and vulnerability reporting

- **[CHANGELOG.md](CHANGELOG.md)** — Release history

- **[Docker Hub](https://hub.docker.com/r/morelitea/initiative)** — Published images

- **API docs** — Available at `/api/v1/docs` when running (Swagger UI)



---



## Contributing



See [CONTRIBUTING.md](CONTRIBUTING.md) for details. PRs must target the `dev` branch.



By contributing, you agree to the terms of the [Contributor License Agreement](./CLA.md).



## Security



See [SECURITY.md](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](LICENSE) (AGPL-3.0). Copyright is retained by the project maintainers, who reserve all commercial rights.