---
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:
### βοΈ 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) |
## π 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.
## πΈ Screenshots
[](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**_
## βοΈ 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.
### π³ 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).
### π οΈ 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 "
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.
## π 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).
## π€ 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.
## Contributors
Thanks to everyone who has contributed to Worklenz! π
[](https://github.com/Worklenz/worklenz/graphs/contributors)
## π 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.
## π 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.
---
Built with π by the Worklenz team and amazing contributors around the world.
www.worklenz.com
