README.md
Rama main · réplica de lectura del repositorio original.
<div align="center">
<h1 align="center">
<a href="https://worklenz.com" target="_blank" rel="noopener noreferrer">
<img src="https://s3.dualstack.us-west-2.amazonaws.com/worklenz.com/assets/worklenz-light-mode.png" alt="Worklenz Logo" width="400">
</a>
</h1>
<h3 align="center">All-in-one open-source project management for efficient teams</h3>
<p align="center">
<a href="https://github.com/Worklenz/worklenz/blob/main/LICENSE">
<img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License">
</a>
<a href="https://github.com/Worklenz/worklenz/releases">
<img src="https://img.shields.io/github/v/release/Worklenz/worklenz" alt="Release">
</a>
<a href="https://github.com/Worklenz/worklenz/stargazers">
<img src="https://img.shields.io/github/stars/Worklenz/worklenz" alt="Stars">
</a>
<a href="https://github.com/Worklenz/worklenz/network/members">
<img src="https://img.shields.io/github/forks/Worklenz/worklenz" alt="Forks">
</a>
<a href="https://github.com/Worklenz/worklenz/issues">
<img src="https://img.shields.io/github/issues/Worklenz/worklenz" alt="Issues">
</a>
<a href="https://discord.com/invite/6Qmm839mgr">
<img src="https://img.shields.io/discord/1202616582757556276?style=flat&logo=discord&logoColor=white&label=Discord&color=5865F2" alt="Discord">
</a>
</p>
<p align="center">
<a href="https://worklenz.com"><b>Website</b></a> •
<a href="https://app.worklenz.com/auth/signup"><b>Sign in</b></a> •
<a href="https://docs.worklenz.com/en/start/introduction/"><b>Documentation</b></a>
</p>
</div>
---
Meet [Worklenz](https://worklenz.com), a powerful, open-source project management platform built to help teams plan smarter, collaborate better, and ship faster. No bloated tools. No unnecessary complexity. Just everything your team needs, in one place. 🚀
> Worklenz is growing every day. Your bug reports, feature ideas, and feedback shape what we build next. Jump into [Discord](https://discord.com/invite/6Qmm839mgr) or open a GitHub issue - we read everything!
## 🚀 Getting Started
Pick the setup that works best for you:
<br>
### ☁️ Worklenz Cloud
The fastest way to get started - no setup, no infrastructure. Just sign up at [worklenz.com](https://worklenz.com) and start managing projects in minutes.
### 🖥️ Self-Host Worklenz
Prefer full control over your data? Run Worklenz on your own server.
| Method | Guide |
|--------|-------|
| 🐳 Docker (Recommended) | [Quick Docker Setup](#quick-start-docker) |
| 🔧 Manual Installation | [Manual Dev Setup](#manual-installation) |
<br>
## 🌟 Features
- **🗺️ Project Management** - Plan, execute, and monitor projects from start to finish with full visibility across every stage.
- **📋 Task Management** - Break projects into tasks, set priorities, due dates, and track progress with multiple views (list, board, Gantt).
- **📐 Resource Planning** - Allocate the right people to the right tasks at the right time - keep your team balanced and productive.
- **👥 Team & Client Collaboration** - Bring your team and clients together in one shared space to align on goals, updates, and deliverables.
- **💰 Financial Insights** - Track budgets, costs, and financial performance across projects to keep spending on track and transparent.
- **⏱️ Time Tracking** - Log time directly on tasks to understand where your team's hours are actually going.
- **📊 Analytics & Reporting** - Get real-time insights into project health, team workload, and performance.
- **🗓️ Resource Management** - Plan team capacity, avoid overallocation, and schedule work with a visual scheduler.
- **🧩 Project Templates** - Start new projects in seconds using pre-built templates for common workflows.
- **🤝 Team Collaboration** - Comment on tasks, share files, and keep all communication in context - right where the work is.
- **📅 Planner** - Schedule and visualize project timelines across a cross-project view, with team-wide member utilization at a glance.
- **🔄 Import & Export** - Import tasks from a CSV file and export entire projects to CSV for easy data portability.
<br><br>
## 📸 Screenshots
<div align="center">
[](https://worklenz.com/task-management/)
_**Task Management Task List View**_
[](https://worklenz.com/task-management/)
_**Task Management Kanban View**_
[](https://worklenz.com/resource-management/)
_**Resource Management**_
[](https://worklenz.com/project-templates/)
_**Projects & Tasks Templates**_
[](https://worklenz.com/time-tracking/)
_**Time Tracking**_
[](https://worklenz.com/analytics/)
_**Project Insights**_
[](https://worklenz.com/team-utilization/)
_**Team Utilization**_
[](https://worklenz.com/timesheets/)
_**Scheduler**_
[](https://worklenz.com/project-finance/)
_**Project Profitability Monitor**_
[](https://worklenz.com/client-portal/)
_**Client Portal**_
</div>
<br>
## ⚙️ Tech Stack
[](https://reactjs.org/)
[](https://www.typescriptlang.org/)
[](https://expressjs.com/)
[](https://www.postgresql.org/)
[](https://www.docker.com/)
| Layer | Technology |
|-------|-----------|
| **Frontend** | React + Ant Design |
| **Backend** | TypeScript + Express.js |
| **Database** | PostgreSQL |
| **Storage** | SeaweedFS (S3-compatible) / AWS S3 / Azure Blob |
| **Cache** | Redis |
| **Proxy** | Nginx |
### Requirements
- Node.js version v22.12.0 or newer
- PostgreSQL version v15 or newer
- Docker and Docker Compose (for containerized setup)
## 📝 Documentation
Explore Worklenz's [product documentation](https://docs.worklenz.com/en/start/introduction/) to learn about features, setup, and usage and more.
<br>
<a id="quick-start-docker"></a>
### 🐳 Quick Start (Docker — Recommended)
The fastest way to get Worklenz running locally with all dependencies included. This setup includes **production-ready features** like nginx reverse proxy, SSL/TLS support, Redis caching, and automated backups.
**📋 Prerequisites:**
- Docker and Docker Compose installed on your system
- Git
**🪜 Steps:**
#### Option 1: Automated Setup (Easiest)
```bash
# 📥 Clone the repository
git clone https://github.com/Worklenz/worklenz.git
cd worklenz
# Run the automated setup script
./quick-setup.sh
```
This script will:
- ✅ Create `.env` file with auto-generated security secrets
- ✅ Configure URLs based on your domain (localhost or production)
- ✅ Set up SSL certificates (self-signed for localhost, Let's Encrypt for production)
- ✅ Install and start all services
#### Option 2: Manual Setup
```bash
# 📥 Clone the repository
git clone https://github.com/Worklenz/worklenz.git
cd worklenz
# 📄 Copy and configure environment file
cp .env.example .env
# Edit .env and set required values (DB_PASSWORD, SESSION_SECRET, etc.)
# ▶️ Start services (includes PostgreSQL, Redis, SeaweedFS)
docker compose up -d
```
**🌐 Access the application:**
- **Application**: https://localhost (or http://localhost)
- **SeaweedFS S3 API**: http://localhost:8333
**🛠️ Management:**
```bash
# Use the management script for common operations
./manage.sh status # View service status
./manage.sh logs # View logs
./manage.sh backup # Create database backup
./manage.sh stop # Stop all services
./manage.sh start # Start all services
```
**For detailed documentation**, see [DOCKER_SETUP.md](DOCKER_SETUP.md)
**Video Guide**: For a visual walkthrough of the local Docker deployment process, check out our [step-by-step video guide](https://www.youtube.com/watch?v=AfwAKxJbqLg).
<a id="manual-installation"></a>
### 🛠️ Manual Installation (For Development)
Use this path to run the services individually, either for development or on a
server that does not use Docker.
**📋 Prerequisites:**
- Node.js (version 22.12.0 or higher)
- PostgreSQL (version 15 or higher)
- An S3-compatible storage service (SeaweedFS is bundled) or Azure Blob Storage
**🪜 Steps:**
1. 📥 Clone the repository:
```bash
# Open a terminal and navigate to the directory where you want to clone Worklenz.
cd /path/to/your/projects
git clone https://github.com/Worklenz/worklenz.git
cd worklenz
git switch main
```
2. ⚙️ Set up environment variables:
```bash
cp worklenz-backend/.env.template worklenz-backend/.env
# Update the environment variables with your configuration
```
#### Self-hosted features and email
The OSS distribution is self-hosted by default. Planner, Finance, and Client
Portal are included for every organization; do not change
`WORKLENZ_DEPLOYMENT_MODE=self_hosted`.
Email invitations use the SMTP relay you configure in
`worklenz-backend/.env`:
```env
EMAIL_PROVIDER=smtp
EMAIL_FROM="Worklenz <noreply@your-domain.com>"
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-smtp-username
SMTP_PASSWORD=your-smtp-password
CLIENT_PORTAL_HOSTNAME=client.your-domain.com
```
Use `SMTP_SECURE=true` for an implicit-TLS SMTP service (normally port 465).
For submission with STARTTLS, use port 587 and leave it `false`.
3. 📦 Install dependencies:
```bash
# Backend dependencies
cd worklenz-backend
npm install
# 🖥️ Frontend dependencies
cd ../worklenz-frontend
npm install
```
4. 🗄️ Set up the database:
```bash
# Create a PostgreSQL database named worklenz_db
cd worklenz-backend
# Execute the SQL setup files in the correct order
psql -U your_username -d worklenz_db -f database/sql/0_extensions.sql
psql -U your_username -d worklenz_db -f database/sql/1_tables.sql
psql -U your_username -d worklenz_db -f database/sql/indexes.sql
psql -U your_username -d worklenz_db -f database/sql/4_functions.sql
psql -U your_username -d worklenz_db -f database/sql/triggers.sql
psql -U your_username -d worklenz_db -f database/sql/3_views.sql
psql -U your_username -d worklenz_db -f database/sql/2_dml.sql
psql -U your_username -d worklenz_db -f database/sql/5_database_user.sql
# Apply versioned migrations after the base schema is initialized
npm run migrate:up
```
5. ▶️ Start the development servers:
```bash
# Backend (builds, watches, and auto-restarts)
cd worklenz-backend
npm run dev
# Frontend (in another terminal)
cd worklenz-frontend
npm run dev
```
6. 🌐 Access the application at http://localhost:5000
#### Production server (without Docker)
For a production server, build the applications and run the backend through a
process manager such as systemd or PM2. Do not leave `npm start` running only in
an SSH session.
```bash
cd worklenz-backend
npm run build
npm run migrate:up
cd ../worklenz-frontend
npm run build
```
The frontend production files are written to `worklenz-frontend/build`. Configure
your web server to serve that directory and proxy `/api` and `/socket.io` to the
backend. Configure the process manager to run `npm start` from the
`worklenz-backend` directory.
To update a manual deployment, back up the database, then pull the latest
`main` branch, rebuild both applications, apply migrations, and restart the
backend process:
```bash
cd /path/to/your/projects/worklenz
git pull --ff-only origin main
cd worklenz-backend
npm ci
npm run build
npm run migrate:up
cd ../worklenz-frontend
npm ci
npm run build
```
## 🚢 Deployment
### 🏠 Local Development
For local development, follow the [Quick Start (Docker)](#quick-start-docker) section above.
### 🌍 Production Deployment
The new Docker setup includes production-ready features for secure and scalable deployments.
#### ⚡ Quick Production Setup
```bash
# Clone and navigate to the repository
git clone https://github.com/Worklenz/worklenz.git
cd worklenz
# Run the automated setup
./quick-setup.sh
# When prompted, enter your production domain (e.g., worklenz.example.com)
# The script will configure SSL with Let's Encrypt automatically
```
#### 🔧 Manual Production Setup
1. **Configure environment for your domain:**
```bash
cp .env.example .env
# Edit .env and set:
# - DOMAIN=your-domain.com
# - VITE_API_URL=https://your-domain.com
# - VITE_SOCKET_URL=wss://your-domain.com
# - ENABLE_SSL=true
# - LETSENCRYPT_EMAIL=your-email@domain.com
# - Generate secure secrets for DB_PASSWORD, SESSION_SECRET, etc.
```
2. **Point your domain's DNS A record to your server IP**
3. **Start services with SSL:**
```bash
docker compose up -d
```
4. **Access your application at:** https://your-domain.com
#### 🛠️ Management Commands
```bash
./manage.sh install # Interactive installation
./manage.sh upgrade # Upgrade to latest version
./manage.sh backup # Create database backup
./manage.sh restore # Restore from backup
./manage.sh ssl # Manage SSL certificates
./manage.sh status # View service status
```
#### 🗂️ Deployment Modes
- 🟢 **Express Mode** (default): All services bundled (PostgreSQL, Redis, SeaweedFS)
```bash
docker compose up -d
```
- 🔵 **Advanced Mode**: Use external services (AWS S3, Azure Blob, external PostgreSQL)
```bash
# Set DEPLOYMENT_MODE=advanced in .env
docker compose up -d
```
**For complete deployment documentation**, see [DOCKER_SETUP.md](DOCKER_SETUP.md)
**Video Guide**: For a complete walkthrough of deploying Worklenz to a remote server, check out our [deployment video guide](https://www.youtube.com/watch?v=CAZGu2iOXQs&t=10s).
## ⚙️ Configuration
### Environment Variables
Worklenz uses a comprehensive environment configuration system. Copy `.env.example` to `.env` and configure according to your needs.
**📂 Key Configuration Areas:**
- **Infrastructure Mode**: `DEPLOYMENT_MODE=express` (all services bundled) or
`advanced` (external services)
- **OSS Feature Entitlement**: `WORKLENZ_DEPLOYMENT_MODE=self_hosted` enables
Planner, Finance, and Client Portal for all organizations
- **Domain & URLs**: Configure for localhost or production domain
- **Database**: PostgreSQL credentials and connection settings
- **Security Secrets**: Session, cookie, and JWT secrets (auto-generated by setup scripts)
- **Storage**: SeaweedFS (default), AWS S3, or Azure Blob Storage
- **Redis**: Cache configuration (Express mode)
- **SSL/TLS**: Let's Encrypt for production, self-signed for localhost
- **Backups**: Automated backup retention settings
- **Optional Features**: Google OAuth, reCAPTCHA, email notifications
**OSS entitlement and email defaults:**
- `WORKLENZ_DEPLOYMENT_MODE`: always `self_hosted` in this public distribution;
this enables Planner, Finance, and Client Portal for all organizations.
- `EMAIL_PROVIDER`: `smtp`; configure `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`,
`SMTP_PASSWORD`, and `EMAIL_FROM` before sending invitations.
- `CLIENT_PORTAL_HOSTNAME`: public client-portal hostname used in invitation and
password-reset links.
**⚡ Quick Configuration:**
```bash
# Auto-generate all secrets and configure based on domain
./manage.sh auto-configure
# Or manually generate secrets
openssl rand -hex 32 # Use for SESSION_SECRET, COOKIE_SECRET, JWT_SECRET
```
**📌 Important Variables:**
- `DOMAIN`: Your domain (localhost for local testing)
- `DEPLOYMENT_MODE`: express or advanced
- `WORKLENZ_DEPLOYMENT_MODE`: self_hosted (OSS default; do not change)
- `STORAGE_PROVIDER`: s3 (SeaweedFS/AWS) or azure
- `ENABLE_SSL`: true/false for SSL/TLS
- `BACKUP_RETENTION_DAYS`: Days to keep backups (default: 30)
For a complete list of variables with detailed documentation, see `.env.example`.
## 🪣 SeaweedFS Integration
The Docker setup uses SeaweedFS as its bundled S3-compatible object storage service. The default bucket is created automatically when the service starts.
### 🔧 Working with SeaweedFS
SeaweedFS exposes an S3-compatible API on port `8333`. Worklenz uses a private container endpoint for API calls and a separate public bucket URL for attachment links.
- **🖥️ S3 API**: http://localhost:8333
- **Access key**: configured with `S3_ACCESS_KEY_ID`
- **Secret key**: configured with `S3_SECRET_ACCESS_KEY`
- **🪣 Default Bucket**: worklenz-bucket (created automatically when the containers start)
### ⬆️ Upgrading from MinIO
SeaweedFS uses a different on-disk format. An existing `worklenz_minio_data`
Docker volume is intentionally left untouched and is not mounted into
SeaweedFS. Copy existing objects through the S3 API before removing the old
volume; do not copy the raw volume contents into `worklenz_seaweedfs_data`.
### 🛠️ Backend Storage Configuration
The backend is pre-configured to use SeaweedFS with the following settings:
```javascript
export const REGION = process.env.S3_REGION || "us-east-1";
export const BUCKET = process.env.S3_BUCKET || "worklenz-bucket";
export const S3_ENDPOINT = process.env.S3_ENDPOINT;
export const S3_URL = process.env.S3_PUBLIC_URL || process.env.S3_URL;
export const S3_ACCESS_KEY_ID = process.env.S3_ACCESS_KEY_ID || "";
export const S3_SECRET_ACCESS_KEY = process.env.S3_SECRET_ACCESS_KEY || "";
```
## 🔒 Security
Worklenz is built with security in mind:
- 🔐 Non-root Docker containers
- 🌐 Network isolation (backend is internal-only)
- 🔑 SSL/TLS (Let's Encrypt for production, self-signed for localhost)
- 🛡️ Rate limiting on API and login endpoints
- 🔒 Security headers (HSTS, CSP, X-Frame-Options, etc.)
- 🗝️ Auto-generated secure secrets via `openssl rand -hex 32`
Found a security vulnerability? Please **do not** open a public issue. Email us at [info@worklenz.com](mailto:info@worklenz.com) instead. We take all legitimate reports seriously.
<br>
## 📈 Analytics
Worklenz uses Google Analytics, Mixpanel, and Microsoft Clarity to understand how the application is used - helping us prioritize improvements and make smarter product decisions.
**What we track:**
- 📊 Usage statistics
- 🗺️ Page views and navigation patterns
- 🧩 Feature usage
- 💻 Browser and device information
**Privacy and consent:**
- 🍪 Microsoft Clarity loads only after consent. The cookie banner's "Reject All" / "Accept" choice is stored in your browser's local storage and applies to Clarity only.
- 📈 Google Analytics (always) and Mixpanel (when `VITE_MIXPANEL_TOKEN` is set) are initialized without waiting for that choice, so declining the banner does **not** disable them.
- 🔎 Analytics data may include identifiers such as cookies, IP-derived location, and device details. Data is handled according to the providers' policies, including [Google's Privacy Policy](https://policies.google.com/privacy).
<br/>
## 🤝 Contributing
We love contributions from the community! Here's how you can help:
- 🐛 [Report bugs](https://github.com/Worklenz/worklenz/issues/new)
- ✨ [Request features](https://github.com/Worklenz/worklenz/issues/new)
- 📖 Improve the documentation
- 💬 Share Worklenz with your team or write about it
Please read [CONTRIBUTING.md](https://github.com/Worklenz/worklenz/blob/main/CONTRIBUTING.md) before submitting a pull request.
<br>
## Contributors
Thanks to everyone who has contributed to Worklenz! 💙
[](https://github.com/Worklenz/worklenz/graphs/contributors)
<br>
## 💙 Community
Join the Worklenz community:
- 💬 [Discord Server](https://discord.gg/6Qmm839mgr) - chat with contributors and users
- 🐙 [GitHub Discussions](https://github.com/Worklenz/worklenz/discussions) - longer form conversations
- 🐦 Follow updates on our [website](https://worklenz.com)
We follow a [Code of Conduct](https://github.com/Worklenz/worklenz/blob/main/CODE_OF_CONDUCT.md) across all community spaces.
<br>
## 📄 License
Worklenz is open source, released under the [GNU Affero General Public License v3.0](https://github.com/Worklenz/worklenz/blob/main/LICENSE).
By contributing to Worklenz, you agree your contributions will be licensed under AGPL v3.0.
<br>
---
<br>
<div align="center">
<strong>Built with 💙 by the Worklenz team and amazing contributors around the world.</strong>
<br/>
<a href="https://worklenz.com">www.worklenz.com</a>
</div>