Milestone

Documentation | User Guide | Admin Guide | Changelog

An open-source R&D project management platform for multi-site organizations.

Features

• Gantt chart visualization — Interactive timeline with drag & drop, resize phases, dependencies and critical path
• Kanban board — Phases and subphases as cards with status, assignees and comment threads, kept in sync with the Gantt
• Tags and tag groups — Colour-coded project labels per site; group, filter and colour the Gantt by them
• Resource management — Staff allocation with percentage-based assignments and a workload heatmap
• Absences and site calendars — Vacation types, bank holidays and company events, with .ics import
• Equipment scheduling — Book equipment across projects with conflict detection and maintenance blocks
• Multi-tenant architecture — Separate databases per organization
• Organization-level SSO — Microsoft Entra ID with group-based access control
• Cross-site visibility — View resources across locations while maintaining confidentiality
• What-If planning — Scenario planning without affecting production data
• Real-time collaboration — WebSocket-powered live updates
• Notifications — In-app inbox for assignments, comments, mentions and status changes
• Import/Export — Microsoft Project (CSV, XML, MPP) support and a full site export to Excel
• Mobile responsive — Touch-optimized for tablets

Tech Stack

• Backend: Python 3.11+ / FastAPI / SQLAlchemy 2.0 (async) / PostgreSQL 15+
• Frontend: React 18 / TypeScript / Zustand / Vite / TanStack Query
• Deployment: Docker / Docker Compose
• Documentation: MkDocs Material / Cloudflare Pages

Quick Start

Option 1: GitHub Codespaces (Recommended for Demo)

Click the badge above to launch a fully configured environment with PostgreSQL, Python, Node.js, and a pre-seeded demo tenant.

The backend starts automatically on port 8485 serving the pre-built frontend — the demo is usable as soon as the Codespace is ready. For frontend development with hot reload, optionally run:

cd frontend && npm run dev -- --host 0.0.0.0 --port 3333

The Codespace automatically creates a demo tenant with sample data:

Access	URL	Email	Password
Admin Portal	/admin/	admin@demo.local	demo1234
Demo Tenant	/t/demo/	admin@demo.local	demo1234

The demo tenant includes 2 sites (Winterthur, Frankfurt), 5 projects (one archived) with phases, nested subphases, dependencies, staff and equipment bookings, 9 people (incl. a part-time member, a project manager and an inactive account) with skills, 8 equipment items, tag groups, custom columns, bank holidays, a site closure, absences of every type, Kanban comments and notifications. All staff accounts use password demo1234.

Option 2: Docker Fresh Install

git clone https://github.com/vincentmakes/milestone-planner.git
cd milestone-planner
cp .env.example .env
docker compose -f docker-compose.fresh.yml up -d

This starts PostgreSQL + the app with auto-initialization. Check docker logs milestone-fresh for the admin password. Access at http://localhost:8486/.

Option 3: Production with External DB

cp .env.example .env
# Edit .env with your database credentials and secrets

# Start against a managed/external PostgreSQL (auto-creates DBs with PG_ADMIN_* creds)
docker compose -f docker-compose.external-db.yml up -d

Access at http://localhost:8485/. (The plain docker-compose.yml targets a specific Unraid deployment — external network + hardcoded host path — adapt it before using it elsewhere. See the installation guide.)

Documentation

Full documentation is published at docs-milestone.verdet.me.

Resource	Description
User Guide	Day-to-day usage: Gantt charts, staff, equipment, vacations
Admin Guide	Installation, multi-tenant management, SSO configuration
Developer Guide	Architecture, local development, API reference
API Documentation	Swagger UI (when running)
Changelog	Release history (SemVer)

File Structure

milestone-planner/
├── app/                    # FastAPI backend
│   ├── main.py            # Application entry point
│   ├── config.py          # Pydantic settings
│   ├── database.py        # Tenant DB engine/session
│   ├── routers/           # API endpoints (22 modules + admin/ package)
│   ├── models/            # SQLAlchemy models (18 modules)
│   ├── schemas/           # Pydantic schemas
│   ├── scripts/           # init_db (auto-init), seed_demo
│   ├── services/          # Business logic (encryption, SSO, tenant management)
│   ├── middleware/        # Auth, tenant resolution, broadcast middleware
│   └── websocket/         # Real-time collaboration (presence, change events)
├── frontend/              # React frontend source
│   └── src/               # Components, stores, API clients, types
├── docs/                  # MkDocs documentation source
│   ├── user-guide/        # End-user documentation
│   ├── admin-guide/       # Admin & multi-tenant docs
│   └── developer-guide/   # Architecture & API reference
├── .devcontainer/         # GitHub Codespaces configuration
├── .github/workflows/     # CI (audits, lint, test, build, version gate; docs deploy via Cloudflare Pages)
├── migrations/            # Raw SQL migration files
├── scripts/               # Utility scripts
├── public/                # Served frontend (built from frontend/dist/)
├── docker-compose.yml     # Production deployment
├── docker-compose.fresh.yml  # Self-contained fresh install
├── docker-compose.dev.yml # Development with hot reload
├── Dockerfile             # Multi-stage container build
├── mkdocs.yml             # Documentation site config
├── setup_databases.sql    # Complete database schema
└── .env.example           # Environment template

Multi-Tenant Mode

For SaaS deployment with multiple organizations:

1. Set MULTI_TENANT=true in .env
2. Configure master DB settings (MASTER_DB_HOST, MASTER_DB_NAME, etc.)
3. Set TENANT_ENCRYPTION_KEY (64-char hex, required)
4. Set PG_ADMIN_USER / PG_ADMIN_PASSWORD for auto-provisioning
5. Access admin panel at /admin/

Each tenant gets an isolated PostgreSQL database. Credentials are encrypted with AES-256-GCM. See the Multi-Tenant Management Guide for details.

Access URLs

URL	Description
/	Main application
/t/{slug}/	Tenant-specific access
/admin/	Multi-tenant admin panel
/api/docs	API documentation (Swagger)
/health	Health check endpoint

Environment Variables

Key variables (see .env.example for full list):

Variable	Description
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD	PostgreSQL connection
SESSION_SECRET	Secret for session signing
MULTI_TENANT	Enable multi-tenant mode (true/false)
MASTER_DB_HOST, MASTER_DB_NAME, etc.	Master DB (multi-tenant only)
TENANT_ENCRYPTION_KEY	64-char hex for credential encryption
PG_ADMIN_USER, PG_ADMIN_PASSWORD	For auto-provisioning tenant DBs

License

Milestone Planner is licensed under the Functional Source License 1.1 with MIT Future License (FSL-1.1-MIT).

What this means in practice:

• ✅ Use it freely. Self-host Milestone Planner in your company, for any internal purpose, commercial or not. No fees, no seat limits, no strings.
• ✅ Modify it. Fork it, adapt it, build on it for your own use.
• ✅ Consult with it. Professional services helping organizations adopt and run Milestone Planner are explicitly permitted.
• ✅ It becomes MIT. Each release automatically converts to the MIT license two years after publication. The code always returns to fully permissive open source.
• ❌ Don't resell it. You may not offer Milestone Planner (or a derivative) to third parties as a competing commercial product, or as a hosted/managed service.

Versions up to and including 1.6.0 remain under the MIT license.