diff --git a/PROJECT_OVERVIEW.md b/PROJECT_OVERVIEW.md new file mode 100644 index 00000000000..84d76b9cb38 --- /dev/null +++ b/PROJECT_OVERVIEW.md @@ -0,0 +1,569 @@ +# πŸ“Š Plane - Project Overview & Analysis + +Complete analysis of the Plane project for rebranding and customization. + +--- + +## 🎯 Executive Summary + +**Plane** is a comprehensive, open-source project management platform comparable to Jira, Linear, or Asana. It's built with modern technologies and offers enterprise-grade features while remaining highly customizable. + +### Key Strengths + +βœ… **Modern Tech Stack** - React 18, Django 4.2, PostgreSQL, real-time collaboration +βœ… **Feature-Rich** - Issues, sprints, analytics, real-time editing +βœ… **Well-Architected** - Monorepo, microservices-ready, scalable +βœ… **Production-Ready** - Docker support, comprehensive documentation +βœ… **Active Development** - Regular updates, strong community + +### Key Considerations + +⚠️ **Resource-Intensive** - Requires 12+ GB RAM for development +⚠️ **Complex Architecture** - Multiple services and technologies +⚠️ **AGPL License** - Open-source requirements for modifications +⚠️ **Learning Curve** - Large codebase with many features + +--- + +## πŸ—οΈ Architecture Overview + +### Application Structure + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PLANE PLATFORM β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Web App β”‚ β”‚ Admin Panel β”‚ β”‚ Space β”‚ β”‚ +β”‚ β”‚ (React) β”‚ β”‚ (React) β”‚ β”‚ (React) β”‚ β”‚ +β”‚ β”‚ :3000 β”‚ β”‚ :3001 β”‚ β”‚ :3002 β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Live Server β”‚ β”‚ Django API β”‚ β”‚ +β”‚ β”‚ (Node.js) β”‚ β”‚ (REST Framework) β”‚ β”‚ +β”‚ β”‚ :3100 β”‚ β”‚ :8000 β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Postgresβ”‚ β”‚ Redis β”‚ β”‚ RabbitMQ β”‚ β”‚ MinIO β”‚ β”‚ +β”‚ β”‚ :5432 β”‚ β”‚ :6379 β”‚ β”‚ :5672 β”‚ β”‚ :9000 β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Technology Stack + +| Layer | Technology | Version | Purpose | +|-------|-----------|---------|---------| +| **Frontend** | React | 18.3.1 | UI framework | +| | React Router | 7.9.5 | Routing & SSR | +| | Vite | 7.1.11 | Build tool | +| | MobX | 6.12.0 | State management | +| | Tailwind CSS | Latest | Styling | +| | TipTap | 2.22.3 | Rich text editor | +| **Backend** | Django | 4.2.26 | Web framework | +| | DRF | 3.15.2 | REST API | +| | Celery | 5.4.0 | Async tasks | +| | Uvicorn | 0.29.0 | ASGI server | +| **Database** | PostgreSQL | 15.7 | Primary database | +| | Redis | 7.2.11 | Cache/sessions | +| **Queue** | RabbitMQ | 3.13.6 | Message broker | +| **Storage** | MinIO | Latest | S3-compatible storage | +| **Real-time** | Hocuspocus | 2.15.2 | Collaboration server | +| | Yjs | 13.6.20 | CRDT for sync | +| **DevOps** | Docker | Latest | Containerization | +| | Turbo | 2.6.1 | Monorepo builds | +| | pnpm | 10.21.0 | Package manager | + +--- + +## πŸ“‚ Project Structure + +### Directory Overview + +``` +plane/ +β”‚ +β”œβ”€β”€ apps/ # Main applications +β”‚ β”œβ”€β”€ web/ # Main dashboard (React Router + Vite) +β”‚ β”‚ β”œβ”€β”€ app/ # React Router app directory +β”‚ β”‚ β”‚ β”œβ”€β”€ routes/ # Page routes +β”‚ β”‚ β”‚ β”œβ”€β”€ components/ # React components +β”‚ β”‚ β”‚ └── root.tsx # App root +β”‚ β”‚ β”œβ”€β”€ core/ # Business logic +β”‚ β”‚ β”œβ”€β”€ ce/ # Community Edition features +β”‚ β”‚ β”œβ”€β”€ ee/ # Enterprise Edition features +β”‚ β”‚ β”œβ”€β”€ public/ # Static assets +β”‚ β”‚ β”œβ”€β”€ styles/ # Global styles +β”‚ β”‚ β”œβ”€β”€ vite.config.ts # Vite configuration +β”‚ β”‚ └── package.json # Dependencies +β”‚ β”‚ +β”‚ β”œβ”€β”€ admin/ # Admin panel (React Router + Vite) +β”‚ β”‚ β”œβ”€β”€ app/ # Admin routes (God mode) +β”‚ β”‚ └── package.json +β”‚ β”‚ +β”‚ β”œβ”€β”€ space/ # Public sharing app +β”‚ β”‚ β”œβ”€β”€ app/ # Space routes +β”‚ β”‚ └── package.json +β”‚ β”‚ +β”‚ β”œβ”€β”€ api/ # Django backend +β”‚ β”‚ β”œβ”€β”€ plane/ # Main Django project +β”‚ β”‚ β”‚ β”œβ”€β”€ app/ # Core application +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ views/ # API endpoints +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ serializers/ # Data serializers +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ urls/ # URL routing +β”‚ β”‚ β”‚ β”‚ └── permissions/ # Access control +β”‚ β”‚ β”‚ β”œβ”€β”€ db/ # Database models +β”‚ β”‚ β”‚ β”‚ └── models/ # Django models +β”‚ β”‚ β”‚ β”œβ”€β”€ settings/ # Django configuration +β”‚ β”‚ β”‚ β”œβ”€β”€ bgtasks/ # Celery tasks +β”‚ β”‚ β”‚ └── utils/ # Utilities +β”‚ β”‚ β”œβ”€β”€ requirements/ # Python dependencies +β”‚ β”‚ └── manage.py # Django CLI +β”‚ β”‚ +β”‚ β”œβ”€β”€ live/ # Real-time collaboration server +β”‚ β”‚ β”œβ”€β”€ src/ # TypeScript source +β”‚ β”‚ β”‚ β”œβ”€β”€ index.ts # Server entry +β”‚ β”‚ β”‚ └── extensions/ # Hocuspocus extensions +β”‚ β”‚ └── package.json +β”‚ β”‚ +β”‚ └── proxy/ # Caddy reverse proxy +β”‚ └── Caddyfile.ce # Proxy configuration +β”‚ +β”œβ”€β”€ packages/ # Shared libraries +β”‚ β”œβ”€β”€ ui/ # UI component library +β”‚ β”‚ β”œβ”€β”€ src/components/ # Reusable components +β”‚ β”‚ └── storybook/ # Component docs +β”‚ β”‚ +β”‚ β”œβ”€β”€ types/ # TypeScript type definitions +β”‚ β”œβ”€β”€ services/ # API client services +β”‚ β”œβ”€β”€ hooks/ # React hooks +β”‚ β”œβ”€β”€ constants/ # Shared constants +β”‚ β”œβ”€β”€ utils/ # Utility functions +β”‚ β”œβ”€β”€ editor/ # Rich text editor package +β”‚ β”œβ”€β”€ i18n/ # Internationalization +β”‚ β”‚ └── src/locales/ # Translation files +β”‚ β”‚ β”œβ”€β”€ en/ # English +β”‚ β”‚ └── fr/ # French +β”‚ β”‚ +β”‚ β”œβ”€β”€ shared-state/ # Global state management +β”‚ β”œβ”€β”€ eslint-config/ # Shared ESLint config +β”‚ β”œβ”€β”€ tailwind-config/ # Shared Tailwind config +β”‚ └── typescript-config/ # Shared TypeScript config +β”‚ +β”œβ”€β”€ deployments/ # Deployment configurations +β”‚ β”œβ”€β”€ aio/ # All-in-one deployment +β”‚ β”œβ”€β”€ kubernetes/ # K8s manifests +β”‚ └── swarm/ # Docker Swarm +β”‚ +β”œβ”€β”€ docker-compose.yml # Production compose +β”œβ”€β”€ docker-compose-local.yml # Development compose +β”œβ”€β”€ turbo.json # Turbo configuration +β”œβ”€β”€ pnpm-workspace.yaml # pnpm workspaces +β”œβ”€β”€ package.json # Root package +β”œβ”€β”€ .env.example # Environment template +β”œβ”€β”€ setup.sh # Linux/Mac setup +β”œβ”€β”€ setup-windows.ps1 # Windows setup (PowerShell) +β”œβ”€β”€ setup-windows.bat # Windows setup (Batch) +β”œβ”€β”€ SETUP_GUIDE.md # Setup documentation +β”œβ”€β”€ REBRANDING_GUIDE.md # Customization guide +└── README.md # Project readme +``` + +--- + +## ✨ Feature Inventory + +### Core Features (Essential) + +| Feature | Description | Complexity | Priority | +|---------|-------------|------------|----------| +| **Issues** | Task/issue tracking with rich text | High | πŸ”΄ Critical | +| **Projects** | Project organization | Medium | πŸ”΄ Critical | +| **Workspaces** | Multi-tenant workspaces | Medium | πŸ”΄ Critical | +| **Cycles** | Sprint/iteration management | Medium | 🟑 High | +| **Views** | Customizable issue views | Medium | 🟑 High | +| **Analytics** | Dashboards and reports | Medium | 🟑 High | +| **States** | Issue status workflow | Low | πŸ”΄ Critical | +| **Labels** | Issue categorization | Low | 🟑 High | +| **Members** | Team collaboration | Medium | πŸ”΄ Critical | +| **Permissions** | Role-based access | Medium | πŸ”΄ Critical | + +### Advanced Features (Optional) + +| Feature | Description | Complexity | Removable? | +|---------|-------------|------------|------------| +| **Modules** | Project modules/epics | Medium | βœ… Yes | +| **Pages** | Rich text docs with AI | High | βœ… Yes | +| **Space** | Public issue sharing | Medium | βœ… Yes | +| **Real-time** | Live collaboration | Very High | ⚠️ With Pages | +| **Integrations** | Slack, OpenAI, etc. | Medium | βœ… Selective | +| **God Mode** | Instance admin panel | Medium | ⚠️ Keep | +| **Webhooks** | External integrations | Low | βœ… Yes | + +### UI Features + +| Feature | Description | Views Available | +|---------|-------------|----------------| +| **List View** | Traditional list | βœ… | +| **Kanban** | Board view | βœ… | +| **Calendar** | Calendar view | βœ… | +| **Spreadsheet** | Table view | βœ… | +| **Gantt** | Timeline view | ❌ Not implemented | +| **Filters** | Advanced filtering | βœ… | +| **Search** | Global search | βœ… | +| **Shortcuts** | Keyboard shortcuts | βœ… | + +--- + +## πŸ“Š Complexity Analysis + +### Lines of Code (Estimated) + +| Component | Lines | Language | Complexity | +|-----------|-------|----------|------------| +| Web App | ~50,000 | TypeScript/TSX | High | +| Admin App | ~5,000 | TypeScript/TSX | Low | +| Space App | ~10,000 | TypeScript/TSX | Medium | +| API Backend | ~40,000 | Python | High | +| Live Server | ~2,000 | TypeScript | Medium | +| Shared Packages | ~20,000 | TypeScript | Medium | +| **Total** | **~127,000** | Mixed | **High** | + +### Development Effort + +| Task | Estimated Time | Difficulty | +|------|----------------|------------| +| **Setup & Learning** | 1-2 weeks | Medium | +| **Basic Rebranding** | 1-2 weeks | Low | +| **Feature Removal** | 2-4 weeks | Medium | +| **Custom Features** | 4-12 weeks | High | +| **Production Deploy** | 1-2 weeks | Medium | + +--- + +## 🎨 Branding Elements + +### Current Brand Assets + +**Logo Locations:** +- `/apps/web/public/logo.svg` +- `/apps/web/public/favicon/` +- Email templates in `/apps/api/plane/templates/` + +**Color Scheme:** +- Defined in `/packages/tailwind-config/index.ts` +- Custom color variables throughout components + +**Typography:** +- Primary: Inter (sans-serif) +- Monospace: JetBrains Mono + +**Terminology:** +- Issues (not Tasks or Tickets) +- Cycles (not Sprints) +- Modules (not Epics) +- Workspace (not Organization) + +### Customization Targets + +🎨 **Easy to Change:** +- Logo and favicons +- Color scheme +- Typography +- Terminology (via i18n) +- Email templates + +πŸ”§ **Medium Difficulty:** +- UI component styles +- Layout and spacing +- Navigation structure +- Default workflows + +🚧 **Complex:** +- Core business logic +- Database schema +- API structure +- Real-time features + +--- + +## πŸ” Security Considerations + +### Current Security Features + +βœ… **Authentication:** +- Email/password +- Magic link (passwordless) +- Google OAuth +- JWT tokens + +βœ… **Authorization:** +- Role-based permissions (Admin, Member, Guest) +- Workspace-level isolation +- Project-level permissions + +βœ… **API Security:** +- CORS configuration +- Rate limiting +- CSRF protection +- Input sanitization + +βœ… **Data Protection:** +- PostgreSQL with proper permissions +- Encrypted passwords (Django default) +- Secure session handling + +### Recommendations for Production + +- [ ] Enable HTTPS (SSL/TLS) +- [ ] Configure firewall rules +- [ ] Set up regular backups +- [ ] Implement audit logging +- [ ] Enable 2FA (add custom) +- [ ] Regular security updates +- [ ] Penetration testing +- [ ] GDPR compliance (if EU users) + +--- + +## πŸ’° Cost Analysis + +### Development Costs (Estimated) + +| Resource | Cost | Notes | +|----------|------|-------| +| **Developer Time** | $50-150/hr | Varies by location | +| **Basic Rebrand** | $5,000-10,000 | 1-2 weeks | +| **Feature Custom** | $20,000-50,000 | 4-8 weeks | +| **Full Custom** | $50,000-150,000 | 3-6 months | + +### Infrastructure Costs (Monthly) + +**Small Scale (< 100 users):** +| Service | Provider | Cost | +|---------|----------|------| +| VPS (8 GB RAM) | DigitalOcean | $48/mo | +| Database | Managed PostgreSQL | $15/mo | +| Storage | S3/Spaces | $5-20/mo | +| CDN | Cloudflare | Free | +| **Total** | | **~$70-85/mo** | + +**Medium Scale (100-500 users):** +| Service | Provider | Cost | +|---------|----------|------| +| VPS (16 GB RAM) | DigitalOcean | $96/mo | +| Database | Managed PostgreSQL | $50/mo | +| Storage | S3/Spaces | $20-50/mo | +| Redis | Managed Redis | $30/mo | +| CDN | Cloudflare Pro | $20/mo | +| **Total** | | **~$220-250/mo** | + +**Large Scale (500+ users):** +- Kubernetes cluster: $500-2000/mo +- Managed databases: $200-500/mo +- CDN & storage: $100-300/mo +- Monitoring & logs: $50-200/mo +- **Total: $850-3000+/mo** + +--- + +## πŸ“ˆ Scalability + +### Current Capacity + +| Metric | Small VPS | Medium VPS | Cluster | +|--------|-----------|------------|---------| +| **Concurrent Users** | 10-50 | 50-200 | 500+ | +| **Projects** | 100s | 1,000s | 10,000+ | +| **Issues** | 10,000s | 100,000s | Millions | +| **Storage** | 50 GB | 500 GB | Unlimited | + +### Bottlenecks & Solutions + +**Database:** +- Bottleneck: Complex queries, large datasets +- Solution: Indexes, read replicas, connection pooling + +**Frontend:** +- Bottleneck: Bundle size, initial load +- Solution: Code splitting, lazy loading, CDN + +**Real-time:** +- Bottleneck: WebSocket connections +- Solution: Horizontal scaling of live server + +**File Storage:** +- Bottleneck: Upload/download speed +- Solution: CDN, S3 multipart uploads + +--- + +## πŸš€ Deployment Options + +### Option 1: Single VPS (Recommended for Start) + +**Pros:** +- βœ… Simple setup +- βœ… Low cost ($50-100/mo) +- βœ… Easy to manage + +**Cons:** +- ❌ Single point of failure +- ❌ Limited scaling +- ❌ Downtime for updates + +**Best For:** < 100 users, POC, internal tools + +### Option 2: Kubernetes Cluster + +**Pros:** +- βœ… Highly scalable +- βœ… Auto-healing +- βœ… Zero-downtime deploys + +**Cons:** +- ❌ Complex setup +- ❌ Higher cost ($500+/mo) +- ❌ Requires DevOps expertise + +**Best For:** > 500 users, SaaS, mission-critical + +### Option 3: Platform-as-a-Service + +**Pros:** +- βœ… Minimal DevOps +- βœ… Auto-scaling +- βœ… Managed services + +**Cons:** +- ❌ Higher cost +- ❌ Vendor lock-in +- ❌ Less control + +**Best For:** Fast launch, limited DevOps team + +--- + +## 🎯 Recommendations + +### For Rebranding + +**Priority 1 (Week 1-2):** +1. βœ… Change logo and favicons +2. βœ… Update color scheme +3. βœ… Modify terminology +4. βœ… Rebrand emails +5. βœ… Update meta tags + +**Priority 2 (Week 3-4):** +1. βœ… Customize UI components +2. βœ… Remove unused features +3. βœ… Adjust workflows +4. βœ… Test thoroughly + +**Priority 3 (Week 5+):** +1. βœ… Add custom features +2. βœ… Integrate external services +3. βœ… Deploy to production +4. βœ… Gather user feedback + +### Features to Keep + +βœ… **Must Keep:** +- Issues/Work Items +- Projects & Workspaces +- Views & Filters +- Analytics +- Members & Permissions +- God Mode (Admin) + +βœ… **Probably Keep:** +- Cycles (if using agile) +- Labels & States +- File uploads +- Search + +### Features to Consider Removing + +⚠️ **Evaluate:** +- **Pages** - If using external docs (Notion, etc.) +- **Modules** - If Cycles are sufficient +- **Space** - If no public sharing needed +- **Real-time** - If removing Pages + +**Savings from Removal:** +- Reduced complexity +- Lower resource usage +- Simplified deployment +- Easier maintenance + +--- + +## πŸ“š Learning Path + +### Week 1: Orientation +- [ ] Run the app locally +- [ ] Explore all features +- [ ] Review codebase structure +- [ ] Read documentation + +### Week 2: Customization +- [ ] Change branding elements +- [ ] Modify color scheme +- [ ] Update terminology +- [ ] Test changes + +### Week 3-4: Development +- [ ] Remove unwanted features +- [ ] Customize workflows +- [ ] Add integrations +- [ ] Build custom features + +### Week 5-6: Deployment +- [ ] Set up staging environment +- [ ] Deploy to production +- [ ] Configure monitoring +- [ ] Create backups + +### Ongoing: Maintenance +- [ ] Monitor performance +- [ ] Fix bugs +- [ ] Add features +- [ ] Update dependencies + +--- + +## πŸŽ‰ Conclusion + +Plane is a robust, feature-rich project management platform with: + +**Strengths:** +- Modern, maintainable codebase +- Comprehensive features +- Strong architecture +- Active community + +**Challenges:** +- Large codebase requires learning +- Resource-intensive +- Complex deployment +- AGPL license considerations + +**Verdict:** Excellent foundation for custom project management solution with proper planning and resources. + +--- + +## πŸ“ž Support Resources + +- **Setup Guide:** [SETUP_GUIDE.md](./SETUP_GUIDE.md) +- **Rebranding Guide:** [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) +- **Quick Start:** [QUICK_START_WINDOWS.md](./QUICK_START_WINDOWS.md) +- **Official Docs:** https://developers.plane.so/ +- **Community:** https://discord.com/invite/A92xrEGCge +- **GitHub:** https://github.com/makeplane/plane + +--- + +*Last Updated: Based on Plane v1.1.0* diff --git a/QUICK_START_WINDOWS.md b/QUICK_START_WINDOWS.md new file mode 100644 index 00000000000..f10f7d95556 --- /dev/null +++ b/QUICK_START_WINDOWS.md @@ -0,0 +1,295 @@ +# πŸš€ Quick Start Guide - Windows + +Get Plane running on your Windows machine in under 30 minutes! + +--- + +## ⚑ Prerequisites + +Before starting, ensure you have: + +- βœ… **Windows 10 or 11** (64-bit) +- βœ… **16 GB RAM** (minimum 12 GB) +- βœ… **20 GB free disk space** +- βœ… **Admin rights** on your computer + +--- + +## πŸ“¦ Step 1: Install Prerequisites (First Time Only) + +### 1.1 Install Node.js + +1. Download Node.js **v22.18.0 or higher** from [nodejs.org](https://nodejs.org/) +2. Run the installer with default options +3. Restart your terminal/PowerShell +4. Verify installation: + ```powershell + node --version + ``` + Should show: `v22.18.0` or higher + +### 1.2 Install Docker Desktop + +1. Download from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) +2. Run installer +3. **Restart your computer** (required) +4. Start Docker Desktop (wait for it to fully start) +5. Verify Docker is running: + ```powershell + docker --version + ``` + +### 1.3 Install Git + +1. Download from [git-scm.com](https://git-scm.com/) +2. Install with default settings +3. Verify: + ```powershell + git --version + ``` + +--- + +## πŸ› οΈ Step 2: Set Up the Project + +### 2.1 Clone the Repository + +Open **PowerShell** or **Command Prompt**: + +```powershell +# Clone the repository +git clone https://github.com/makeplane/plane.git plane-project + +# Navigate into the directory +cd plane-project +``` + +### 2.2 Run the Setup Script + +**Option A: Using PowerShell (Recommended)** + +```powershell +# Run the setup script +.\setup-windows.ps1 +``` + +**Option B: Using Batch File** + +```cmd +# Double-click setup-windows.bat in File Explorer +# OR run in Command Prompt: +setup-windows.bat +``` + +This will: +- βœ… Check prerequisites +- βœ… Create environment files +- βœ… Generate security keys +- βœ… Install dependencies (takes 5-10 minutes) + +**⏰ Go grab a coffee while dependencies install!** + +--- + +## πŸš€ Step 3: Start the Application + +### 3.1 Start Docker Services + +In PowerShell/CMD: + +```powershell +docker compose -f docker-compose-local.yml up -d +``` + +This starts: +- PostgreSQL database +- Redis cache +- RabbitMQ message queue +- MinIO file storage + +**Wait ~30 seconds** for all services to start. + +Verify services are running: +```powershell +docker compose -f docker-compose-local.yml ps +``` + +You should see all services with status "Up". + +### 3.2 Start Development Servers + +In a **new PowerShell/CMD window**: + +```powershell +pnpm dev +``` + +This starts all frontend applications: +- **Web app** (main dashboard) - port 3000 +- **Admin panel** - port 3001 +- **Space** (public sharing) - port 3002 +- **Live server** (real-time) - port 3100 + +**Wait ~2-3 minutes** for the build to complete. + +You'll see output like: +``` +βœ“ Built in XXXXms +Local: http://localhost:3000/ +``` + +--- + +## 🌐 Step 4: Access the Application + +### 4.1 Register as Instance Admin + +1. Open your browser to: **http://localhost:3001/god-mode/** +2. Fill in the registration form: + - Email + - Password + - Name +3. Click **"Submit"** + +This creates your admin account. + +### 4.2 Log In to Main App + +1. Open: **http://localhost:3000** +2. Log in with the same credentials from step 4.1 +3. Create your first workspace +4. Start creating projects and issues! + +--- + +## πŸŽ‰ You're Done! + +### Application URLs + +| Service | URL | Description | +|---------|-----|-------------| +| **Main App** | http://localhost:3000 | Your dashboard | +| **Admin Panel** | http://localhost:3001/god-mode/ | System settings | +| **API Docs** | http://localhost:8000/api/schema/swagger-ui/ | API documentation | +| **MinIO** | http://localhost:9090 | File storage (login: access-key/secret-key) | + +--- + +## πŸ”§ Common Issues & Solutions + +### Issue: "Port 3000 is already in use" + +**Solution:** +```powershell +# Find what's using the port +netstat -ano | findstr :3000 + +# Kill the process (replace with the number shown) +taskkill /PID /F +``` + +### Issue: Docker won't start + +**Solution:** +1. Open Docker Desktop +2. Wait for "Docker Desktop is running" message +3. Try the docker command again + +### Issue: "pnpm: command not found" + +**Solution:** +```powershell +# Enable pnpm +corepack enable +corepack prepare pnpm@10.21.0 --activate + +# Verify +pnpm --version +``` + +### Issue: Out of memory errors + +**Solution:** +1. Open Docker Desktop +2. Go to: Settings β†’ Resources β†’ Advanced +3. Increase Memory to **8 GB** (or more) +4. Click **"Apply & Restart"** + +### Issue: Slow performance + +**Solutions:** +- Close unnecessary applications +- Ensure you have at least 12 GB RAM +- Check if antivirus is scanning Docker folders (add to exclusions) + +--- + +## πŸ›‘ Stopping the Application + +When you're done for the day: + +### Stop Development Servers +Press `Ctrl + C` in the PowerShell window running `pnpm dev` + +### Stop Docker Services +```powershell +docker compose -f docker-compose-local.yml down +``` + +### To Restart Later +```powershell +# Start Docker services +docker compose -f docker-compose-local.yml up -d + +# Start dev servers (in a new window) +pnpm dev +``` + +--- + +## πŸ“š Next Steps + +Now that you have Plane running: + +1. **Explore the app** - Create projects, issues, cycles +2. **Read the guides**: + - [SETUP_GUIDE.md](./SETUP_GUIDE.md) - Detailed technical setup + - [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) - Customization guide +3. **Start customizing** - Change colors, logo, features +4. **Deploy to production** - When ready, follow deployment guide + +--- + +## πŸ†˜ Need Help? + +- **Detailed Setup:** See [SETUP_GUIDE.md](./SETUP_GUIDE.md) +- **Customization:** See [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) +- **Official Docs:** https://developers.plane.so/ +- **Discord:** https://discord.com/invite/A92xrEGCge + +--- + +## πŸ’‘ Pro Tips + +### Tip 1: Use VS Code +Install [Visual Studio Code](https://code.visualstudio.com/) for the best development experience. + +Recommended extensions: +- ESLint +- Prettier +- Tailwind CSS IntelliSense + +### Tip 2: Keep Docker Running +For faster startups, keep Docker Desktop running in the background. + +### Tip 3: Use Multiple Terminal Windows +- Window 1: Docker logs (`docker compose logs -f`) +- Window 2: Development servers (`pnpm dev`) +- Window 3: Commands and Git operations + +### Tip 4: Windows Terminal +Use [Windows Terminal](https://aka.ms/terminal) for a better command-line experience. + +--- + +Happy coding! πŸŽ‰ diff --git a/README_DOCUMENTATION.md b/README_DOCUMENTATION.md new file mode 100644 index 00000000000..37f0f74319f --- /dev/null +++ b/README_DOCUMENTATION.md @@ -0,0 +1,317 @@ +# πŸ“š Plane - Documentation Guide + +Welcome! This directory contains comprehensive documentation for setting up, understanding, and customizing the Plane project management platform. + +--- + +## πŸ“– Documentation Files + +### πŸš€ [QUICK_START_WINDOWS.md](./QUICK_START_WINDOWS.md) +**For:** Windows users who want to get started quickly +**Time:** 30 minutes + +Get Plane running on Windows in under 30 minutes. Includes: +- Prerequisites installation +- Quick setup steps +- Common troubleshooting +- Access instructions + +**Start here if you're new and using Windows!** + +--- + +### πŸ“‹ [SETUP_GUIDE.md](./SETUP_GUIDE.md) +**For:** Detailed technical setup on any platform +**Time:** 1-2 hours + +Comprehensive guide covering: +- Complete system requirements +- Step-by-step setup for Windows/macOS/Linux +- Architecture overview +- Development workflow +- Troubleshooting +- All access URLs + +**Use this for in-depth understanding and reference.** + +--- + +### 🎨 [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) +**For:** Customizing and rebranding Plane +**Time:** 2-6 weeks (depending on scope) + +Complete rebranding guide including: +- Visual identity changes (logo, colors, fonts) +- Feature assessment and recommendations +- Feature removal guides +- Custom feature ideas +- Technical considerations +- Deployment strategies +- Step-by-step checklist + +**Essential for customization and white-labeling.** + +--- + +### πŸ“Š [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md) +**For:** Understanding the project architecture +**Time:** 30 minutes reading + +Detailed project analysis: +- Architecture overview +- Technology stack details +- Feature inventory +- Complexity analysis +- Security considerations +- Cost estimates +- Scalability analysis +- Deployment options + +**Read this to understand what you're working with.** + +--- + +## πŸ› οΈ Setup Scripts + +### Windows Users: + +#### PowerShell Script +```powershell +.\setup-windows.ps1 +``` +Recommended method with full error checking and colored output. + +#### Batch File +```cmd +setup-windows.bat +``` +Alternative method that launches the PowerShell script. + +### Linux/macOS Users: + +```bash +chmod +x setup.sh +./setup.sh +``` + +--- + +## πŸ—ΊοΈ Quick Navigation + +### I want to... + +**...get started quickly on Windows** +β†’ [QUICK_START_WINDOWS.md](./QUICK_START_WINDOWS.md) + +**...set up on Linux/macOS** +β†’ [SETUP_GUIDE.md](./SETUP_GUIDE.md) + +**...understand the technology** +β†’ [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md) + +**...rebrand and customize** +β†’ [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) + +**...deploy to production** +β†’ [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md#deployment-strategy) (Deployment section) + +**...remove features I don't need** +β†’ [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md#feature-assessment) + +**...understand costs** +β†’ [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md#cost-analysis) + +--- + +## πŸ“ Recommended Reading Order + +### For Developers: + +1. **Start:** [QUICK_START_WINDOWS.md](./QUICK_START_WINDOWS.md) or [SETUP_GUIDE.md](./SETUP_GUIDE.md) + - Get the app running locally + +2. **Explore:** Use the application + - Create workspaces, projects, issues + - Test all features + +3. **Learn:** [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md) + - Understand architecture + - Review technology choices + +4. **Customize:** [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) + - Plan your changes + - Execute rebranding + +### For Project Managers: + +1. **Overview:** [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md) + - Understand what you have + - Assess features and costs + +2. **Planning:** [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) + - Feature assessment + - Customization options + - Timeline planning + +3. **Setup:** [SETUP_GUIDE.md](./SETUP_GUIDE.md) + - Share with development team + +--- + +## 🎯 Quick Reference + +### System Requirements + +| Component | Minimum | Recommended | +|-----------|---------|-------------| +| **RAM** | 12 GB | 16 GB | +| **CPU** | 4 cores | 8 cores | +| **Storage** | 20 GB | 50 GB | +| **Node.js** | 22.18.0+ | Latest LTS | + +### Application URLs (Local) + +| Service | URL | +|---------|-----| +| **Main App** | http://localhost:3000 | +| **Admin Panel** | http://localhost:3001/god-mode/ | +| **API Docs** | http://localhost:8000/api/schema/swagger-ui/ | +| **MinIO Console** | http://localhost:9090 | + +### Key Commands + +```bash +# Setup +./setup-windows.ps1 # Windows +./setup.sh # Linux/macOS + +# Start Docker services +docker compose -f docker-compose-local.yml up -d + +# Start development servers +pnpm dev + +# Stop everything +docker compose -f docker-compose-local.yml down + +# Clean build +pnpm clean +``` + +--- + +## πŸ†˜ Getting Help + +### Documentation Issues? + +If you find errors or have suggestions for these docs: +1. Create an issue on GitHub +2. Submit a pull request with corrections +3. Ask in Discord community + +### Technical Issues? + +1. Check the troubleshooting sections in guides +2. Review [Official Docs](https://developers.plane.so/) +3. Search [GitHub Issues](https://github.com/makeplane/plane/issues) +4. Ask in [Discord](https://discord.com/invite/A92xrEGCge) + +--- + +## πŸ“š Additional Resources + +### Official Plane Resources + +- **Product Documentation:** https://docs.plane.so/ +- **Developer Documentation:** https://developers.plane.so/ +- **GitHub Repository:** https://github.com/makeplane/plane +- **Discord Community:** https://discord.com/invite/A92xrEGCge +- **Twitter:** https://twitter.com/planepowers + +### Technology Documentation + +- **React Router:** https://reactrouter.com/ +- **Django:** https://docs.djangoproject.com/ +- **Django REST Framework:** https://www.django-rest-framework.org/ +- **Tailwind CSS:** https://tailwindcss.com/ +- **Docker:** https://docs.docker.com/ +- **PostgreSQL:** https://www.postgresql.org/docs/ + +--- + +## βœ… Checklist for Getting Started + +### Initial Setup + +- [ ] Read [QUICK_START_WINDOWS.md](./QUICK_START_WINDOWS.md) or [SETUP_GUIDE.md](./SETUP_GUIDE.md) +- [ ] Install prerequisites (Node.js, Docker, Git) +- [ ] Clone repository +- [ ] Run setup script +- [ ] Start Docker services +- [ ] Start development servers +- [ ] Register as instance admin +- [ ] Create first workspace + +### Learning Phase + +- [ ] Explore all features +- [ ] Read [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md) +- [ ] Review architecture +- [ ] Understand technology stack +- [ ] Identify features to keep/remove + +### Customization Phase + +- [ ] Read [REBRANDING_GUIDE.md](./REBRANDING_GUIDE.md) +- [ ] Plan branding changes +- [ ] Update logo and colors +- [ ] Modify terminology +- [ ] Remove unwanted features +- [ ] Test thoroughly + +### Deployment Phase + +- [ ] Set up production environment +- [ ] Configure domain and SSL +- [ ] Deploy application +- [ ] Set up monitoring +- [ ] Create backup strategy +- [ ] Test production deployment + +--- + +## πŸŽ‰ You're Ready! + +You now have all the documentation needed to: + +βœ… Set up Plane locally +βœ… Understand the architecture +βœ… Customize and rebrand +βœ… Deploy to production + +**Happy building! πŸš€** + +--- + +## πŸ“„ Document Version + +**Created:** 2025-01-22 +**Based on:** Plane v1.1.0 +**Last Updated:** 2025-01-22 + +--- + +## 🀝 Contributing + +Found a typo? Have a suggestion? Want to add content? + +These documentation files are part of your project and can be freely modified. Consider: + +1. Keeping them updated as you customize +2. Adding your own sections for custom features +3. Documenting your deployment process +4. Sharing improvements with the community + +--- + +*These guides were created to help you successfully set up, understand, and customize the Plane project management platform. Good luck with your project!* diff --git a/REBRANDING_GUIDE.md b/REBRANDING_GUIDE.md new file mode 100644 index 00000000000..5fb044fde96 --- /dev/null +++ b/REBRANDING_GUIDE.md @@ -0,0 +1,991 @@ +# 🎨 Plane - Rebranding & Feature Enhancement Guide + +A comprehensive guide for rebranding Plane and customizing features for your specific needs. + +--- + +## πŸ“‹ Table of Contents + +1. [Rebranding Overview](#rebranding-overview) +2. [Visual Identity Changes](#visual-identity-changes) +3. [Feature Assessment](#feature-assessment) +4. [Recommended Customizations](#recommended-customizations) +5. [Feature Enhancement Ideas](#feature-enhancement-ideas) +6. [Technical Considerations](#technical-considerations) +7. [Deployment Strategy](#deployment-strategy) + +--- + +## 🎯 Rebranding Overview + +### Current Brand Identity + +**Plane** is positioned as: +- Open-source project management platform +- Modern, minimalist design +- Developer-friendly interface +- Enterprise-grade features + +### Key Areas for Rebranding + +1. **Visual Identity** + - Logo and branding assets + - Color scheme + - Typography + - UI/UX design language + +2. **Naming & Messaging** + - Product name + - Taglines and messaging + - Feature names (Issues β†’ Work Items, Cycles β†’ Sprints, etc.) + - Documentation + +3. **Functionality** + - Feature set customization + - Workflow modifications + - Integration priorities + +--- + +## 🎨 Visual Identity Changes + +### 1. Logo & Brand Assets + +#### Files to Modify: + +``` +πŸ“ Logo Files: +apps/web/public/favicon/ # Favicon files +apps/admin/public/favicon/ # Admin favicon +apps/space/public/favicon/ # Space favicon + +πŸ“ Images & Graphics: +apps/web/public/ # Public assets +packages/ui/src/ # UI component assets + +πŸ“ README & Docs: +README.md # Main logo reference +``` + +#### Action Items: +- [ ] Replace favicon.ico files in all apps +- [ ] Update logo SVG/PNG in `public/` folders +- [ ] Update social media preview images +- [ ] Modify README.md header image +- [ ] Update email template logos (apps/api/plane/templates/) + +**Example Files:** +```bash +# Primary logo locations +apps/web/public/logo.svg +apps/web/public/favicon/favicon.ico +apps/admin/public/favicon/favicon.ico +apps/space/public/favicon/favicon.ico +``` + +### 2. Color Scheme + +#### Primary Configuration Files: + +```typescript +πŸ“ Tailwind Configuration: +packages/tailwind-config/index.ts # Global colors + +πŸ“ Theme Files: +apps/web/styles/ # Global styles +packages/ui/src/ # Component styles +``` + +#### Current Color Palette: + +The project uses Tailwind CSS with custom color definitions. Key colors to modify: + +```javascript +// packages/tailwind-config/index.ts +{ + colors: { + custom: { + primary: {...}, // Main brand color + background: {...}, // Background colors + text: {...}, // Text colors + border: {...}, // Border colors + sidebar: {...}, // Sidebar colors + } + } +} +``` + +#### Action Items: +- [ ] Define new brand color palette (primary, secondary, accent) +- [ ] Update Tailwind config with new colors +- [ ] Update CSS custom properties +- [ ] Test color contrast for accessibility (WCAG AA) +- [ ] Update dark mode colors + +**Recommended Tools:** +- [Coolors.co](https://coolors.co/) - Color palette generator +- [Contrast Checker](https://webaim.org/resources/contrastchecker/) - WCAG compliance + +### 3. Typography + +#### Font Configuration: + +```typescript +πŸ“ Font Files: +apps/web/app/styles/fonts.css # Font imports +packages/tailwind-config/index.ts # Font family config +``` + +Current fonts: +- **Sans-serif**: Inter (primary UI font) +- **Monospace**: JetBrains Mono (code) + +#### Action Items: +- [ ] Choose new brand fonts (Google Fonts, Adobe Fonts, custom) +- [ ] Add font files to project +- [ ] Update Tailwind font family configuration +- [ ] Update font imports in CSS +- [ ] Test font loading performance + +### 4. UI Component Library + +The project uses a custom UI library in `packages/ui/`. + +#### Key Components to Rebrand: + +``` +packages/ui/src/components/ +β”œβ”€β”€ button/ # Buttons +β”œβ”€β”€ badge/ # Badges and labels +β”œβ”€β”€ card/ # Cards +β”œβ”€β”€ dropdown/ # Dropdowns +β”œβ”€β”€ modal/ # Modals +β”œβ”€β”€ navigation/ # Navigation components +└── ... +``` + +#### Action Items: +- [ ] Review component designs +- [ ] Update button styles and variants +- [ ] Customize input field styles +- [ ] Modify modal and dialog designs +- [ ] Update navigation bar appearance +- [ ] Customize sidebar design + +### 5. Application Title & Meta Tags + +#### Files to Update: + +```typescript +πŸ“ HTML Meta Tags: +apps/web/app/root.tsx # Root component with meta +apps/admin/app/root.tsx # Admin meta +apps/space/app/root.tsx # Space meta + +πŸ“ Environment Variables: +apps/web/.env # App configuration +``` + +#### Action Items: +- [ ] Update `` tags +- [ ] Modify meta descriptions +- [ ] Change Open Graph titles and descriptions +- [ ] Update Twitter Card metadata +- [ ] Modify app manifest files + +**Example:** +```tsx +// apps/web/app/root.tsx +export const meta: MetaFunction = () => [ + { title: "Your Brand - Project Management" }, + { name: "description", content: "Your custom description" }, + { property: "og:title", content: "Your Brand" }, + // ... more meta tags +]; +``` + +--- + +## πŸ“Š Feature Assessment + +### Core Features Analysis + +| Feature | Keep? | Modify? | Remove? | Notes | +|---------|-------|---------|---------|-------| +| **Issues/Work Items** | βœ… | πŸ”§ | ❌ | Core feature - customize terminology | +| **Cycles (Sprints)** | βœ… | πŸ”§ | ❌ | Essential for agile teams | +| **Modules** | βœ… | πŸ”§ | ⚠️ | May overlap with other grouping | +| **Views** | βœ… | πŸ”§ | ❌ | Critical for customization | +| **Pages** | ⚠️ | πŸ”§ | ⚠️ | May be redundant if using external docs | +| **Analytics** | βœ… | πŸ”§ | ❌ | Valuable for insights | +| **Drive** (coming soon) | ⚠️ | πŸ”§ | ⚠️ | Not implemented yet | +| **Real-time Collaboration** | βœ… | πŸ”§ | ⚠️ | Complex but powerful | +| **Multi-workspace** | βœ… | πŸ”§ | ❌ | Essential for multi-tenancy | +| **God Mode (Admin)** | βœ… | πŸ”§ | ❌ | Necessary for instance management | +| **Public Sharing (Space)** | ⚠️ | πŸ”§ | ⚠️ | Use case dependent | + +**Legend:** +- βœ… Keep as-is or with minor changes +- πŸ”§ Modify significantly +- ⚠️ Evaluate based on use case +- ❌ Consider removing + +### Features to Potentially Remove + +#### 1. **Pages Feature** + +**Reasons to Remove:** +- You may already use external documentation tools (Notion, Confluence) +- Adds complexity to the UI +- Real-time collaboration infrastructure is resource-intensive + +**Impact:** +- Removes live server dependency +- Simplifies architecture +- Reduces resource usage + +**How to Remove:** +```bash +# Files to modify/remove: +apps/live/ # Can be removed entirely +apps/web/app/routes/pages/ # Remove pages routes +packages/editor/ # May still be used in issues + +# Database migrations to create (mark pages as deprecated) +# Update navigation to remove Pages link +# Remove Pages from API endpoints +``` + +**Estimated Effort:** Medium (1-2 weeks) + +#### 2. **Public Space (Public Issue Sharing)** + +**Reasons to Remove:** +- May not need public issue tracking +- Security concerns with public data +- Additional maintenance overhead + +**How to Remove:** +```bash +# Remove Space app: +apps/space/ # Remove entire app + +# Remove from build: +# Update turbo.json +# Update docker-compose files +# Remove space-related API endpoints +``` + +**Estimated Effort:** Low (2-3 days) + +#### 3. **Modules** + +**Reasons to Consider Removal:** +- May overlap with other organizational structures +- Cycles (Sprints) might be sufficient +- Simplifies project hierarchy + +**How to Remove:** +```bash +# API changes: +apps/api/plane/app/views/module/ # Remove module views + +# Frontend changes: +apps/web/app/routes/modules/ # Remove module routes + +# Database: +# Create migration to deprecate module tables +``` + +**Estimated Effort:** Medium (1-2 weeks) + +--- + +## πŸ”§ Recommended Customizations + +### 1. Terminology Changes + +Customize feature names to match your brand's language: + +#### Configuration File: + +```typescript +πŸ“ Internationalization: +packages/i18n/src/locales/en/translations.json +``` + +#### Common Terminology Changes: + +| Current | Alternative Options | +|---------|-------------------| +| Issues | Tasks, Items, Tickets, Work Items | +| Cycles | Sprints, Iterations, Milestones | +| Modules | Epics, Projects, Initiatives | +| Workspace | Organization, Team, Account | +| God Mode | Admin Panel, System Settings | + +#### How to Change: + +1. Edit translation files: +```json +// packages/i18n/src/locales/en/translations.json +{ + "issue": { + "label": "Task", // Changed from "Issue" + "title": "Task Title" + }, + "cycle": { + "label": "Sprint" // Changed from "Cycle" + } +} +``` + +2. Search and replace in codebase (be careful): +```bash +# Use with caution - review changes +grep -r "Issue" apps/web/app/ | wc -l +# Manually update key user-facing strings +``` + +### 2. Workflow Customizations + +#### Default Issue States + +Modify default issue states to match your workflow: + +```python +# apps/api/plane/db/models/state.py +# Customize default states + +# Example custom workflow: +- Backlog +- Ready +- In Progress +- In Review +- Testing +- Done +``` + +#### Custom Properties + +Add custom fields specific to your use case: + +```typescript +// Define custom properties for issues +- Estimated Hours +- Actual Hours +- Customer Impact (High/Medium/Low) +- Feature Flag +- Release Version +``` + +### 3. Integration Priorities + +Choose which integrations to keep/add: + +**Currently Supported:** +- βœ… Slack +- βœ… OpenAI (AI features) +- βœ… Webhooks + +**Consider Adding:** +- GitHub/GitLab integration +- Jira import/export +- Microsoft Teams +- Google Calendar +- Zapier/Make.com +- Custom SSO (SAML, OAuth) + +### 4. Email Template Customization + +Customize email notifications: + +``` +πŸ“ Email Templates: +apps/api/plane/templates/emails/ +``` + +**Templates to Customize:** +- Issue assignment notifications +- Mention notifications +- Cycle completion +- Workspace invitations + +### 5. Authentication Options + +Current support: +- Email/Password +- Magic Link (email-based) +- Google OAuth + +**Consider Adding:** +- Microsoft Azure AD +- SAML SSO +- LDAP integration +- Custom OAuth providers + +--- + +## πŸ’‘ Feature Enhancement Ideas + +### 1. Enhanced Time Tracking + +**Current State:** Basic time estimation +**Enhancement:** +- Built-in time tracker (start/stop timer) +- Automatic time logging +- Time reports and analytics +- Billable vs non-billable hours + +**Implementation Complexity:** Medium +**Estimated Time:** 2-3 weeks + +### 2. Advanced Reporting + +**Current State:** Basic analytics dashboard +**Enhancement:** +- Custom report builder +- Export to Excel/PDF +- Scheduled report emails +- Stakeholder-friendly reports + +**Implementation Complexity:** High +**Estimated Time:** 4-6 weeks + +### 3. Resource Management + +**New Feature:** +- Team capacity planning +- Resource allocation view +- Workload balancing +- Skill-based assignment + +**Implementation Complexity:** High +**Estimated Time:** 6-8 weeks + +### 4. Client Portal + +**New Feature:** +- Separate client-facing interface +- Limited issue visibility +- Client feedback collection +- Progress sharing + +**Implementation Complexity:** High +**Estimated Time:** 6-8 weeks + +### 5. Mobile Apps + +**Current State:** Web-only (responsive design) +**Enhancement:** +- React Native mobile apps +- Offline support +- Push notifications +- Mobile-optimized workflows + +**Implementation Complexity:** Very High +**Estimated Time:** 12-16 weeks + +### 6. Advanced Automation + +**Current State:** Basic workflow automation +**Enhancement:** +- No-code automation builder +- Trigger-action workflows +- Conditional logic +- Integration with external tools + +**Implementation Complexity:** High +**Estimated Time:** 8-10 weeks + +### 7. Gantt Chart View + +**Current State:** Calendar view available +**Enhancement:** +- Interactive Gantt chart +- Dependency visualization +- Timeline drag-and-drop +- Critical path analysis + +**Implementation Complexity:** Medium-High +**Estimated Time:** 4-6 weeks + +**Recommended Library:** [Frappe Gantt](https://github.com/frappe/gantt) or [DHTMLX Gantt](https://dhtmlx.com/docs/products/dhtmlxGantt/) + +### 8. AI-Powered Features + +**Current State:** Basic AI in Pages +**Enhancement:** +- AI issue description generation +- Smart task prioritization +- Predictive analytics (completion estimates) +- Automated task categorization +- Natural language queries + +**Implementation Complexity:** High +**Estimated Time:** 6-10 weeks + +### 9. White-Label Options + +**For SaaS/Multi-tenant:** +- Per-workspace branding +- Custom domains +- Workspace-level themes +- Branded emails + +**Implementation Complexity:** Medium +**Estimated Time:** 3-4 weeks + +--- + +## πŸ› οΈ Technical Considerations + +### 1. Monorepo Architecture + +**Current Structure:** +``` +Turborepo + pnpm workspaces +β”œβ”€β”€ apps/ # Applications +└── packages/ # Shared libraries +``` + +**Benefits:** +- βœ… Code sharing across apps +- βœ… Unified build system +- βœ… Consistent dependencies + +**Considerations:** +- Large codebase - may be slow on older machines +- All apps share Node.js version +- Build times can be long + +**Recommendation:** Keep monorepo structure unless you plan to drastically simplify + +### 2. Database Schema + +**Current Database:** PostgreSQL with comprehensive schema + +**Before Making Changes:** +1. βœ… Review existing migrations +2. βœ… Create backup before schema changes +3. βœ… Test migrations in development +4. βœ… Plan rollback strategy + +**Key Tables:** +- `workspaces` - Multi-tenancy +- `projects` - Projects within workspaces +- `issues` - Core work items +- `cycles` - Sprint/iteration management +- `states` - Issue states/statuses +- `labels` - Labels and tags +- `users` - User accounts + +### 3. API Design + +**Current API:** Django REST Framework + +**API Versioning:** +``` +/api/v1/workspaces/ +/api/v1/projects/ +/api/v1/issues/ +``` + +**When Adding Features:** +- Maintain backward compatibility +- Version breaking changes +- Update API documentation (Swagger) +- Test with existing clients + +### 4. Real-time Architecture + +**Current Setup:** Hocuspocus + Yjs (CRDT) + +**Resource Requirements:** +- Separate Node.js server (port 3100) +- WebSocket connections +- Memory-intensive for large documents + +**If Removing Pages:** +- Consider removing live server entirely +- Reduce infrastructure costs +- Simplify deployment + +### 5. Performance Optimization + +**Areas to Optimize:** + +1. **Frontend Bundle Size** + - Code splitting + - Lazy loading routes + - Tree shaking unused code + +2. **Database Queries** + - Add indexes for common queries + - Optimize N+1 queries + - Implement query caching + +3. **API Response Times** + - Redis caching + - Database connection pooling + - Async task processing + +4. **Asset Delivery** + - CDN for static assets + - Image optimization + - Gzip compression + +### 6. Security Hardening + +**Checklist:** + +- [ ] Enable HTTPS in production +- [ ] Configure CORS properly +- [ ] Set up rate limiting +- [ ] Enable CSRF protection +- [ ] Sanitize user inputs +- [ ] Regular dependency updates +- [ ] Security audit of custom code +- [ ] Implement CSP headers +- [ ] Add logging and monitoring + +--- + +## πŸš€ Deployment Strategy + +### 1. Development β†’ Staging β†’ Production + +**Recommended Workflow:** + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Development β”‚ ───> β”‚ Staging β”‚ ───> β”‚ Production β”‚ +β”‚ (Local) β”‚ β”‚ (VPS/AWS) β”‚ β”‚ (VPS/AWS) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 2. VPS Deployment Options + +#### Option A: Docker Compose (Recommended for Small-Medium Scale) + +**Requirements:** +- VPS with 8+ GB RAM (16 GB recommended) +- Ubuntu 20.04/22.04 or similar +- Docker and Docker Compose + +**Setup:** +```bash +# On VPS +git clone <your-repo> +cd plane +cp .env.example .env +# Edit .env with production values +docker compose up -d +``` + +**Pros:** +- βœ… Simple setup +- βœ… Easy to manage +- βœ… Good for single-server deployments + +**Cons:** +- ❌ Single point of failure +- ❌ Limited horizontal scaling + +#### Option B: Kubernetes (For Large Scale) + +**Requirements:** +- Kubernetes cluster (managed or self-hosted) +- kubectl configured +- Helm (optional but recommended) + +**Setup:** +```bash +# Use provided Kubernetes manifests +cd deployments/kubernetes +kubectl apply -f . +``` + +**Pros:** +- βœ… Highly scalable +- βœ… Auto-healing +- βœ… Load balancing + +**Cons:** +- ❌ Complex setup +- ❌ Higher resource requirements +- ❌ Steeper learning curve + +#### Option C: Platform-as-a-Service + +**Options:** +- Railway.app +- Render.com +- Fly.io +- DigitalOcean App Platform + +**Pros:** +- βœ… Minimal DevOps +- βœ… Automatic scaling +- βœ… Built-in SSL + +**Cons:** +- ❌ Higher cost +- ❌ Less control +- ❌ Vendor lock-in + +### 3. Environment Configuration + +**Production .env Checklist:** + +```env +# Security +SECRET_KEY=<generate-strong-random-key> +DEBUG=0 +ALLOWED_HOSTS=yourdomain.com + +# Database (use managed service recommended) +POSTGRES_HOST=your-db-host +POSTGRES_DB=plane_prod +POSTGRES_USER=plane_prod +POSTGRES_PASSWORD=<strong-password> + +# Redis (use managed service recommended) +REDIS_HOST=your-redis-host +REDIS_PASSWORD=<strong-password> + +# S3 Storage (use AWS S3 or DigitalOcean Spaces) +USE_MINIO=0 +AWS_REGION=us-east-1 +AWS_ACCESS_KEY_ID=<your-key> +AWS_SECRET_ACCESS_KEY=<your-secret> +AWS_S3_BUCKET_NAME=plane-uploads + +# SSL/HTTPS +CERT_EMAIL=admin@yourdomain.com +SITE_ADDRESS=yourdomain.com +``` + +### 4. Domain & SSL Setup + +**Steps:** + +1. **Point Domain to VPS:** + ``` + A Record: @ -> <VPS-IP> + A Record: www -> <VPS-IP> + ``` + +2. **SSL Certificate:** + - Caddy (included) handles automatic Let's Encrypt SSL + - Or use Cloudflare for SSL proxy + +3. **Update Environment:** + ```env + SITE_ADDRESS=yourdomain.com + CERT_EMAIL=admin@yourdomain.com + ``` + +### 5. Backup Strategy + +**Critical Data:** +- PostgreSQL database +- Uploaded files (S3/MinIO) +- Environment configurations + +**Backup Methods:** + +```bash +# Database backup +pg_dump -h localhost -U plane plane > backup.sql + +# Restore +psql -h localhost -U plane plane < backup.sql + +# S3 backup (if using MinIO) +mc mirror myminio/uploads /backup/uploads +``` + +**Automated Backups:** +- Daily PostgreSQL dumps +- S3 versioning enabled +- Retention policy (keep 30 days) + +### 6. Monitoring & Logging + +**Tools to Set Up:** + +1. **Application Monitoring:** + - Sentry (error tracking) - already integrated + - PostHog (analytics) - already integrated + +2. **Infrastructure Monitoring:** + - Prometheus + Grafana + - Datadog + - New Relic + +3. **Logging:** + - Centralized logging (ELK stack, Loki) + - Docker logs: `docker compose logs -f` + +4. **Uptime Monitoring:** + - UptimeRobot + - Pingdom + - StatusCake + +### 7. CI/CD Pipeline + +**Recommended Setup:** + +```yaml +# .github/workflows/deploy.yml +name: Deploy to VPS + +on: + push: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Deploy to VPS + run: | + ssh user@vps "cd /app && git pull && docker compose up -d --build" +``` + +--- + +## πŸ“ Step-by-Step Rebranding Checklist + +### Phase 1: Planning (Week 1) + +- [ ] Define new brand identity (name, colors, logo) +- [ ] Decide which features to keep/remove +- [ ] Plan UI/UX changes +- [ ] Create brand assets (logo, colors, fonts) +- [ ] Set up staging environment + +### Phase 2: Visual Rebranding (Week 2-3) + +- [ ] Replace logo files +- [ ] Update color scheme in Tailwind config +- [ ] Change typography +- [ ] Modify UI component styles +- [ ] Update favicons +- [ ] Rebrand email templates +- [ ] Update meta tags and titles + +### Phase 3: Feature Customization (Week 3-5) + +- [ ] Update terminology in i18n files +- [ ] Remove unwanted features (if any) +- [ ] Customize workflows and states +- [ ] Add custom properties +- [ ] Configure integrations + +### Phase 4: Testing (Week 5-6) + +- [ ] Visual regression testing +- [ ] Feature testing +- [ ] Cross-browser testing +- [ ] Mobile responsiveness +- [ ] Performance testing +- [ ] Security audit + +### Phase 5: Deployment (Week 6-7) + +- [ ] Set up production VPS +- [ ] Configure domain and SSL +- [ ] Set up backups +- [ ] Configure monitoring +- [ ] Deploy to production +- [ ] Smoke testing + +### Phase 6: Post-Launch (Ongoing) + +- [ ] Monitor performance +- [ ] Gather user feedback +- [ ] Iterate on features +- [ ] Plan enhancements + +--- + +## πŸŽ“ Learning Resources + +### Official Plane Resources + +- [Product Docs](https://docs.plane.so/) +- [Developer Docs](https://developers.plane.so/) +- [GitHub Repo](https://github.com/makeplane/plane) +- [Discord Community](https://discord.com/invite/A92xrEGCge) + +### Technology Stack Resources + +- **React Router**: https://reactrouter.com/ +- **Django REST Framework**: https://www.django-rest-framework.org/ +- **Tailwind CSS**: https://tailwindcss.com/ +- **MobX**: https://mobx.js.org/ +- **TipTap**: https://tiptap.dev/ +- **Docker**: https://docs.docker.com/ + +### Design Resources + +- **Figma**: Design prototypes +- **Tailwind UI**: Component examples +- **Hero Icons**: Icon library +- **Unsplash**: Free images + +--- + +## 🀝 Support & Contributions + +### Getting Help + +1. Review this guide and SETUP_GUIDE.md +2. Check official documentation +3. Search GitHub issues +4. Ask in Discord community + +### Contributing Back + +If you create useful features: +- Consider contributing back to Plane +- Share your modifications with community +- Help others with similar customizations + +--- + +## πŸ“„ License Considerations + +**Plane License:** AGPL-3.0 + +**Key Points:** +- βœ… Can modify and rebrand +- βœ… Can use commercially +- ⚠️ Must keep AGPL-3.0 license +- ⚠️ Must disclose source code if distributing +- ⚠️ Must share modifications under same license + +**For SaaS/Hosted Service:** +- AGPL requires sharing source code +- Consider commercial license from Plane team +- Or keep your modifications open-source + +**Consult Legal:** For commercial use, consult with legal advisor about AGPL compliance. + +--- + +## πŸŽ‰ Conclusion + +Rebranding Plane gives you a powerful, customizable project management platform tailored to your needs. Follow this guide systematically, test thoroughly, and don't hesitate to iterate based on user feedback. + +**Good luck with your rebranding! πŸš€** + +--- + +**Questions or Issues?** +- Refer to SETUP_GUIDE.md for technical setup +- Join Plane Discord for community support +- Review official documentation for advanced topics diff --git a/SETUP_GUIDE.md b/SETUP_GUIDE.md new file mode 100644 index 00000000000..844ae50c631 --- /dev/null +++ b/SETUP_GUIDE.md @@ -0,0 +1,690 @@ +# πŸš€ Plane - Local Development Setup Guide + +Complete guide to set up and run Plane on your local machine for development and testing. + +--- + +## πŸ“‹ Table of Contents + +1. [Project Overview](#project-overview) +2. [System Requirements](#system-requirements) +3. [Prerequisites Installation](#prerequisites-installation) +4. [Project Setup](#project-setup) +5. [Running the Application](#running-the-application) +6. [Accessing the Application](#accessing-the-application) +7. [Troubleshooting](#troubleshooting) +8. [Development Workflow](#development-workflow) +9. [Architecture Overview](#architecture-overview) +10. [Key Features](#key-features) + +--- + +## 🎯 Project Overview + +**Plane** is an open-source, modern project management platform built with: + +- **Frontend**: React 18 + React Router 7 + Vite +- **Backend**: Django 4.2 + Django REST Framework +- **Database**: PostgreSQL 15 +- **Cache**: Redis (Valkey) +- **Queue**: RabbitMQ + Celery +- **Real-time**: Node.js + Hocuspocus (Yjs) +- **Storage**: MinIO (S3-compatible) + +**Key Capabilities**: +- Issue tracking with rich text editor +- Sprint/Cycle management +- Modules and Views +- Real-time collaboration +- Analytics and insights +- Multi-workspace support + +--- + +## πŸ’» System Requirements + +### Minimum Requirements + +| Component | Requirement | +|-----------|-------------| +| **RAM** | 12 GB (minimum) - 16 GB recommended | +| **CPU** | 4 cores (8 recommended) | +| **Storage** | 20 GB free space | +| **OS** | Windows 10/11, macOS, Linux | + +> ⚠️ **Warning**: Systems with only 8 GB RAM may experience failures during Docker builds or runtime crashes. + +### Software Requirements + +| Software | Version | Purpose | +|----------|---------|---------| +| **Node.js** | β‰₯ 22.18.0 | Frontend and Live server | +| **pnpm** | 10.21.0 | Package manager | +| **Docker Desktop** | Latest | Container runtime | +| **Git** | Latest | Version control | +| **Python** | 3.8+ | Backend development (optional) | + +--- + +## πŸ“¦ Prerequisites Installation + +### Windows Setup + +#### 1. Install Node.js + +1. Download Node.js v22.18.0+ from [nodejs.org](https://nodejs.org/) +2. Run the installer +3. Verify installation: + ```powershell + node --version # Should be v22.18.0 or higher + npm --version + ``` + +#### 2. Install Docker Desktop + +1. Download from [docker.com](https://www.docker.com/products/docker-desktop/) +2. Install and restart your computer +3. Start Docker Desktop +4. Verify installation: + ```powershell + docker --version + docker compose version + ``` + +#### 3. Install Git + +1. Download from [git-scm.com](https://git-scm.com/) +2. Install with default settings +3. Verify: + ```powershell + git --version + ``` + +#### 4. Enable pnpm + +```powershell +corepack enable +corepack prepare pnpm@10.21.0 --activate +pnpm --version +``` + +### macOS Setup + +```bash +# Install Homebrew (if not installed) +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + +# Install Node.js +brew install node@22 + +# Install Docker Desktop (download from docker.com) +# Or use Colima: +brew install colima docker docker-compose +colima start + +# Enable pnpm +corepack enable +corepack prepare pnpm@10.21.0 --activate +``` + +### Linux (Ubuntu/Debian) Setup + +```bash +# Install Node.js 22 +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - +sudo apt-get install -y nodejs + +# Install Docker +sudo apt-get update +sudo apt-get install -y docker.io docker-compose +sudo systemctl start docker +sudo systemctl enable docker +sudo usermod -aG docker $USER + +# Enable pnpm +corepack enable +corepack prepare pnpm@10.21.0 --activate +``` + +--- + +## πŸ› οΈ Project Setup + +### Step 1: Clone the Repository + +```bash +# Clone the repository +git clone https://github.com/makeplane/plane.git plane-project +cd plane-project +``` + +### Step 2: Run Setup Script + +#### On Linux/macOS: + +```bash +chmod +x setup.sh +./setup.sh +``` + +#### On Windows (PowerShell): + +```powershell +# Use the Windows setup script +.\setup-windows.ps1 +``` + +This script will: +- βœ… Copy all `.env.example` files to `.env` +- βœ… Generate Django SECRET_KEY +- βœ… Install Node.js dependencies with pnpm +- βœ… Set up environment files for all services + +### Step 3: Verify Environment Files + +After running the setup script, you should have these `.env` files: + +``` +.env # Root environment (Docker services) +apps/web/.env # Web app environment +apps/api/.env # Django API environment +apps/space/.env # Space app environment +apps/admin/.env # Admin app environment +apps/live/.env # Live server environment +``` + +### Step 4: Configure Environment Variables (Optional) + +Review and customize `.env` files as needed: + +**Root `.env` (Docker services)**: +```env +# Database +POSTGRES_USER=plane +POSTGRES_PASSWORD=plane +POSTGRES_DB=plane + +# Redis +REDIS_HOST=plane-redis +REDIS_PORT=6379 + +# MinIO (S3) +AWS_ACCESS_KEY_ID=access-key +AWS_SECRET_ACCESS_KEY=secret-key +USE_MINIO=1 +``` + +**apps/web/.env**, **apps/admin/.env**, **apps/space/.env**: +```env +VITE_API_BASE_URL=http://localhost:8000 +VITE_WEB_BASE_URL=http://localhost:3000 +VITE_ADMIN_BASE_URL=http://localhost:3001 +VITE_SPACE_BASE_URL=http://localhost:3002 +VITE_LIVE_BASE_URL=http://localhost:3100 +``` + +--- + +## πŸš€ Running the Application + +### Step 1: Start Docker Services + +Start the backing services (PostgreSQL, Redis, RabbitMQ, MinIO): + +```bash +docker compose -f docker-compose-local.yml up -d +``` + +This will start: +- **plane-db**: PostgreSQL database (port 5432) +- **plane-redis**: Redis cache (port 6379) +- **plane-mq**: RabbitMQ message queue (port 5672, management on 15672) +- **plane-minio**: MinIO object storage (port 9000, console on 9090) + +Verify services are running: +```bash +docker compose -f docker-compose-local.yml ps +``` + +### Step 2: Start Development Servers + +In a new terminal, start all frontend and backend services: + +```bash +pnpm dev +``` + +This starts: +- **Web app**: http://localhost:3000 +- **Admin app**: http://localhost:3001 +- **Space app**: http://localhost:3002 +- **Live server**: http://localhost:3100 + +### Step 3: Start Backend API (Optional) + +If you want to run the Django API locally (instead of in Docker): + +#### First-time setup: + +```bash +cd apps/api + +# Create virtual environment +python -m venv venv + +# Activate virtual environment +# On Windows: +venv\Scripts\activate +# On Linux/macOS: +source venv/bin/activate + +# Install dependencies +pip install -r requirements/local.txt + +# Run migrations +python manage.py migrate + +# Create superuser +python manage.py createsuperuser +``` + +#### Run the API server: + +```bash +cd apps/api +source venv/bin/activate # Windows: venv\Scripts\activate +python manage.py runserver 8000 +``` + +#### Run Celery workers (in separate terminals): + +```bash +# Worker +cd apps/api +source venv/bin/activate +celery -A plane worker -l INFO + +# Beat scheduler +cd apps/api +source venv/bin/activate +celery -A plane beat -l INFO +``` + +--- + +## 🌐 Accessing the Application + +### Initial Setup + +1. **Register as Instance Admin** + - Open: http://localhost:3001/god-mode/ + - Fill in the registration form + - This creates your admin account + +2. **Access Main Application** + - Open: http://localhost:3000 + - Log in with the same credentials + - Create your first workspace + +### Application URLs + +| Service | URL | Description | +|---------|-----|-------------| +| **Web App** | http://localhost:3000 | Main user dashboard | +| **Admin Panel** | http://localhost:3001/god-mode/ | Instance administration | +| **Space** | http://localhost:3002/spaces | Public sharing space | +| **Live Server** | http://localhost:3100/live | Real-time collaboration | +| **API** | http://localhost:8000 | REST API backend | +| **API Docs** | http://localhost:8000/api/schema/swagger-ui/ | Swagger documentation | +| **MinIO Console** | http://localhost:9090 | Object storage admin | +| **RabbitMQ Management** | http://localhost:15672 | Queue management (guest/guest) | + +--- + +## πŸ”§ Troubleshooting + +### Common Issues + +#### 1. Docker Services Won't Start + +**Problem**: `docker compose` fails or containers keep restarting + +**Solutions**: +```bash +# Check Docker is running +docker info + +# Check logs +docker compose -f docker-compose-local.yml logs + +# Reset everything +docker compose -f docker-compose-local.yml down -v +docker compose -f docker-compose-local.yml up -d +``` + +#### 2. Port Already in Use + +**Problem**: Error like "port 3000 is already allocated" + +**Solution**: +```bash +# Find process using the port (Windows) +netstat -ano | findstr :3000 +taskkill /PID <PID> /F + +# Find process using the port (Linux/macOS) +lsof -i :3000 +kill -9 <PID> +``` + +#### 3. pnpm install fails + +**Problem**: Dependency installation errors + +**Solutions**: +```bash +# Clear pnpm cache +pnpm store prune + +# Delete node_modules and reinstall +rm -rf node_modules +rm pnpm-lock.yaml +pnpm install + +# Ensure you have Node.js 22+ +node --version +``` + +#### 4. Out of Memory Errors + +**Problem**: Docker or Node processes crash with memory errors + +**Solutions**: +- Increase Docker Desktop memory allocation (Settings β†’ Resources β†’ Memory) +- Set to at least 8 GB (12 GB recommended) +- Close unnecessary applications +- Run fewer services concurrently + +#### 5. Database Connection Errors + +**Problem**: API can't connect to PostgreSQL + +**Solutions**: +```bash +# Check PostgreSQL is running +docker compose -f docker-compose-local.yml ps plane-db + +# Check logs +docker compose -f docker-compose-local.yml logs plane-db + +# Restart database +docker compose -f docker-compose-local.yml restart plane-db + +# Verify connection +docker exec -it plane-db psql -U plane -d plane +``` + +#### 6. MinIO Upload Errors + +**Problem**: File uploads fail + +**Solutions**: +- Verify MinIO is running: http://localhost:9090 +- Login: `access-key` / `secret-key` +- Ensure `uploads` bucket exists +- Check `USE_MINIO=1` in `.env` + +--- + +## πŸ’‘ Development Workflow + +### Common Commands + +```bash +# Start all services +docker compose -f docker-compose-local.yml up -d +pnpm dev + +# Stop all services +docker compose -f docker-compose-local.yml down +# Ctrl+C in the pnpm dev terminal + +# View logs +docker compose -f docker-compose-local.yml logs -f +docker compose -f docker-compose-local.yml logs -f plane-db + +# Rebuild a specific service +docker compose -f docker-compose-local.yml up -d --build plane-db + +# Clean everything (removes volumes) +docker compose -f docker-compose-local.yml down -v +pnpm clean +``` + +### Code Quality + +```bash +# Lint all code +pnpm check:lint + +# Format all code +pnpm fix:format + +# Fix linting issues +pnpm fix + +# Type check +pnpm check + +# Build production version +pnpm build +``` + +### Working with Individual Apps + +```bash +# Web app only +cd apps/web +pnpm dev # Start dev server +pnpm build # Build for production +pnpm check:lint # Lint code + +# Admin app only +cd apps/admin +pnpm dev + +# Space app only +cd apps/space +pnpm dev + +# Live server only +cd apps/live +pnpm dev +``` + +### Database Operations + +```bash +# Access PostgreSQL +docker exec -it plane-db psql -U plane -d plane + +# Run migrations +cd apps/api +python manage.py migrate + +# Create migration +python manage.py makemigrations + +# Django admin +python manage.py createsuperuser +``` + +--- + +## πŸ—οΈ Architecture Overview + +### Monorepo Structure + +``` +plane/ +β”œβ”€β”€ apps/ +β”‚ β”œβ”€β”€ web/ # Main React dashboard (port 3000) +β”‚ β”œβ”€β”€ admin/ # Admin panel (port 3001) +β”‚ β”œβ”€β”€ space/ # Public sharing (port 3002) +β”‚ β”œβ”€β”€ api/ # Django REST API (port 8000) +β”‚ β”œβ”€β”€ live/ # Real-time server (port 3100) +β”‚ └── proxy/ # Caddy reverse proxy +β”œβ”€β”€ packages/ +β”‚ β”œβ”€β”€ ui/ # Shared UI components +β”‚ β”œβ”€β”€ types/ # TypeScript types +β”‚ β”œβ”€β”€ services/ # API clients +β”‚ β”œβ”€β”€ hooks/ # React hooks +β”‚ β”œβ”€β”€ editor/ # Rich text editor +β”‚ └── i18n/ # Internationalization +β”œβ”€β”€ deployments/ # Deployment configs +└── docker-compose-local.yml +``` + +### Service Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Frontend Layer β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”‚ +β”‚ β”‚ Web β”‚ β”‚ Admin β”‚ β”‚ Space β”‚ β”‚ Live β”‚β”‚ +β”‚ β”‚ :3000 β”‚ β”‚ :3001 β”‚ β”‚ :3002 β”‚ β”‚ :3100 β”‚β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ API Layer β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Django REST Framework (:8000) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Background Tasks β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Celery β”‚ β”‚ Celery Beat β”‚ β”‚ +β”‚ β”‚ Worker β”‚ β”‚ Scheduler β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Data Layer β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚PostgreSQLβ”‚ β”‚ Redis β”‚ β”‚ RabbitMQ β”‚ β”‚ MinIO β”‚ β”‚ +β”‚ β”‚ :5432 β”‚ β”‚ :6379 β”‚ β”‚ :5672 β”‚ β”‚ :9000 β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Tech Stack Summary + +| Layer | Technologies | +|-------|-------------| +| **Frontend** | React 18, React Router 7, Vite, MobX, TipTap, TanStack Table | +| **Backend** | Django 4.2, DRF, Uvicorn, Gunicorn | +| **Database** | PostgreSQL 15 | +| **Cache** | Redis (Valkey) | +| **Queue** | RabbitMQ + Celery | +| **Storage** | MinIO (S3-compatible) | +| **Real-time** | Hocuspocus, Yjs CRDT, WebSockets | +| **Build** | Turbo, pnpm workspaces | +| **Container** | Docker, Docker Compose | + +--- + +## ✨ Key Features + +### 1. **Issues (Work Items)** +- Rich text editor with TipTap +- File attachments via MinIO +- Sub-issues and dependencies +- Custom properties and labels +- Issue linking and references + +### 2. **Cycles (Sprints)** +- Sprint planning and execution +- Burn-down charts +- Progress tracking +- Velocity metrics + +### 3. **Modules** +- Break down large projects +- Module dependencies +- Progress visualization + +### 4. **Views** +- Customizable filters +- Multiple layouts (List, Kanban, Calendar, Gantt) +- Saved and shared views +- Private and public views + +### 5. **Pages** +- Rich text documentation +- AI-powered writing assistance +- Convert notes to issues +- Collaborative editing + +### 6. **Analytics** +- Real-time dashboards +- Custom reports +- Trend analysis +- Export capabilities + +### 7. **Workspace Management** +- Multi-workspace support +- Role-based permissions +- Team invitations +- Instance administration (God Mode) + +### 8. **Real-time Collaboration** +- Live cursor tracking +- Concurrent editing with CRDT +- WebSocket-based sync +- Conflict-free merging + +--- + +## πŸ“š Additional Resources + +- **Product Documentation**: https://docs.plane.so/ +- **Developer Documentation**: https://developers.plane.so/ +- **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md) +- **GitHub Repository**: https://github.com/makeplane/plane +- **Discord Community**: https://discord.com/invite/A92xrEGCge +- **Twitter**: https://twitter.com/planepowers + +--- + +## πŸ†˜ Getting Help + +If you encounter issues: + +1. Check this guide's [Troubleshooting](#troubleshooting) section +2. Search [GitHub Issues](https://github.com/makeplane/plane/issues) +3. Join [Discord](https://discord.com/invite/A92xrEGCge) for community support +4. Review [Developer Docs](https://developers.plane.so/) + +--- + +## πŸŽ‰ You're Ready! + +You now have a complete local Plane development environment. Happy coding! + +**Quick Start Checklist**: +- βœ… Prerequisites installed (Node, Docker, pnpm) +- βœ… Repository cloned +- βœ… Setup script executed +- βœ… Docker services running +- βœ… Frontend apps running +- βœ… Instance admin registered +- βœ… First workspace created + +**Next Steps**: +- Explore the codebase +- Make your first contribution +- Join the community +- Build something amazing! diff --git a/setup-windows.bat b/setup-windows.bat new file mode 100644 index 00000000000..8184405bb98 --- /dev/null +++ b/setup-windows.bat @@ -0,0 +1,38 @@ +@echo off +REM Plane Project Setup Script for Windows (Batch) +REM This is a simple launcher that calls the PowerShell script +REM https://github.com/makeplane/plane + +setlocal enabledelayedexpansion + +echo. +echo =============================================================================== +echo Plane - Project Management Tool +echo =============================================================================== +echo. + +REM Check if PowerShell is available +where powershell >nul 2>nul +if %ERRORLEVEL% neq 0 ( + echo [ERROR] PowerShell not found. Please install PowerShell. + echo. + pause + exit /b 1 +) + +echo Starting PowerShell setup script... +echo. + +REM Run the PowerShell script with execution policy bypass +powershell -ExecutionPolicy Bypass -File "%~dp0setup-windows.ps1" + +if %ERRORLEVEL% neq 0 ( + echo. + echo [ERROR] Setup failed. Please check the errors above. + echo. + pause + exit /b 1 +) + +echo. +pause diff --git a/setup-windows.ps1 b/setup-windows.ps1 new file mode 100644 index 00000000000..b4f24f4c60f --- /dev/null +++ b/setup-windows.ps1 @@ -0,0 +1,224 @@ +# Plane Project Setup Script for Windows (PowerShell) +# This script prepares the local development environment by setting up all necessary .env files +# https://github.com/makeplane/plane + +# Requires PowerShell 5.1 or higher +#Requires -Version 5.1 + +# Set error action preference +$ErrorActionPreference = "Stop" + +# Print header +Write-Host "" +Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Blue +Write-Host " Plane - Project Management Tool " -ForegroundColor Blue +Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Blue +Write-Host "Setting up your development environment..." -ForegroundColor Cyan +Write-Host "" + +# Function to copy environment files +function Copy-EnvFile { + param ( + [string]$Source, + [string]$Destination + ) + + if (-Not (Test-Path $Source)) { + Write-Host "βœ— Error: Source file $Source does not exist." -ForegroundColor Red + return $false + } + + try { + Copy-Item -Path $Source -Destination $Destination -Force + Write-Host "βœ“ Copied $Destination" -ForegroundColor Green + return $true + } + catch { + Write-Host "βœ— Failed to copy $Destination : $_" -ForegroundColor Red + return $false + } +} + +# Function to generate random secret key +function New-SecretKey { + param ( + [int]$Length = 50 + ) + + $chars = 'abcdefghijklmnopqrstuvwxyz0123456789' + $secret = -join ((1..$Length) | ForEach-Object { Get-Random -InputObject $chars.ToCharArray() }) + return $secret +} + +# Check prerequisites +Write-Host "Checking prerequisites..." -ForegroundColor Yellow +Write-Host "" + +# Check Node.js +try { + $nodeVersion = node --version + Write-Host "βœ“ Node.js found: $nodeVersion" -ForegroundColor Green + + # Parse version and check if it's >= 22.18.0 + $versionMatch = $nodeVersion -match 'v(\d+)\.(\d+)\.(\d+)' + if ($versionMatch) { + $major = [int]$matches[1] + $minor = [int]$matches[2] + + if ($major -lt 22 -or ($major -eq 22 -and $minor -lt 18)) { + Write-Host "⚠ Warning: Node.js version should be >= 22.18.0. Current: $nodeVersion" -ForegroundColor Yellow + Write-Host " Download from: https://nodejs.org/" -ForegroundColor Yellow + } + } +} +catch { + Write-Host "βœ— Node.js not found. Please install Node.js >= 22.18.0" -ForegroundColor Red + Write-Host " Download from: https://nodejs.org/" -ForegroundColor Yellow + exit 1 +} + +# Check Docker +try { + $dockerVersion = docker --version + Write-Host "βœ“ Docker found: $dockerVersion" -ForegroundColor Green +} +catch { + Write-Host "βœ— Docker not found. Please install Docker Desktop" -ForegroundColor Red + Write-Host " Download from: https://www.docker.com/products/docker-desktop/" -ForegroundColor Yellow + exit 1 +} + +# Check if Docker is running +try { + docker info | Out-Null + Write-Host "βœ“ Docker is running" -ForegroundColor Green +} +catch { + Write-Host "βœ— Docker is not running. Please start Docker Desktop" -ForegroundColor Red + exit 1 +} + +Write-Host "" +Write-Host "Setting up environment files..." -ForegroundColor Yellow +Write-Host "" + +# Array of services +$services = @("", "web", "api", "space", "admin", "live") +$success = $true + +# Copy environment files +foreach ($service in $services) { + if ($service -eq "") { + # Handle root .env file + $prefix = ".\" + } + else { + # Handle service .env files in apps folder + $prefix = ".\apps\$service\" + } + + $source = "${prefix}.env.example" + $destination = "${prefix}.env" + + if (-Not (Copy-EnvFile -Source $source -Destination $destination)) { + $success = $false + } +} + +Write-Host "" + +# Generate SECRET_KEY for Django +if (Test-Path ".\apps\api\.env") { + Write-Host "Generating Django SECRET_KEY..." -ForegroundColor Yellow + + try { + $secretKey = New-SecretKey -Length 50 + + if ($secretKey) { + Add-Content -Path ".\apps\api\.env" -Value "`nSECRET_KEY=`"$secretKey`"" + Write-Host "βœ“ Added SECRET_KEY to apps\api\.env" -ForegroundColor Green + } + else { + Write-Host "βœ— Failed to generate SECRET_KEY" -ForegroundColor Red + $success = $false + } + } + catch { + Write-Host "βœ— Error generating SECRET_KEY: $_" -ForegroundColor Red + $success = $false + } +} +else { + Write-Host "βœ— apps\api\.env not found. SECRET_KEY not added." -ForegroundColor Red + $success = $false +} + +Write-Host "" + +# Enable pnpm +Write-Host "Enabling pnpm..." -ForegroundColor Yellow +try { + corepack enable + corepack prepare pnpm@10.21.0 --activate + $pnpmVersion = pnpm --version + Write-Host "βœ“ pnpm enabled: v$pnpmVersion" -ForegroundColor Green +} +catch { + Write-Host "βœ— Failed to enable pnpm: $_" -ForegroundColor Red + Write-Host " Try running: corepack enable" -ForegroundColor Yellow + $success = $false +} + +Write-Host "" + +# Install dependencies +if ($success) { + Write-Host "Installing Node.js dependencies (this may take a few minutes)..." -ForegroundColor Yellow + Write-Host "" + + try { + pnpm install + Write-Host "" + Write-Host "βœ“ Dependencies installed successfully!" -ForegroundColor Green + } + catch { + Write-Host "βœ— Failed to install dependencies: $_" -ForegroundColor Red + $success = $false + } +} + +Write-Host "" +Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Blue + +# Summary +if ($success) { + Write-Host "" + Write-Host "βœ“ Environment setup completed successfully!" -ForegroundColor Green + Write-Host "" + Write-Host "Next steps:" -ForegroundColor Cyan + Write-Host "1. Review the .env files in each folder if needed" -ForegroundColor White + Write-Host "2. Start Docker services:" -ForegroundColor White + Write-Host " docker compose -f docker-compose-local.yml up -d" -ForegroundColor Yellow + Write-Host "3. Start the development servers:" -ForegroundColor White + Write-Host " pnpm dev" -ForegroundColor Yellow + Write-Host "4. Register as instance admin:" -ForegroundColor White + Write-Host " http://localhost:3001/god-mode/" -ForegroundColor Yellow + Write-Host "5. Access the main app:" -ForegroundColor White + Write-Host " http://localhost:3000" -ForegroundColor Yellow + Write-Host "" + Write-Host "For detailed setup instructions, see SETUP_GUIDE.md" -ForegroundColor Cyan + Write-Host "" + Write-Host "Happy coding! πŸš€" -ForegroundColor Green + Write-Host "" +} +else { + Write-Host "" + Write-Host "βœ— Some issues occurred during setup. Please check the errors above." -ForegroundColor Red + Write-Host "" + Write-Host "For help, visit:" -ForegroundColor Yellow + Write-Host "- Documentation: https://developers.plane.so/" -ForegroundColor Cyan + Write-Host "- GitHub: https://github.com/makeplane/plane" -ForegroundColor Cyan + Write-Host "- Discord: https://discord.com/invite/A92xrEGCge" -ForegroundColor Cyan + Write-Host "" + exit 1 +}