worklenz

Meet Worklenz, 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 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 and start managing projects in minutes.

🖥️ Self-Host Worklenz

Prefer full control over your data? Run Worklenz on your own server.

🌟 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

⚙️ Tech Stack

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

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

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

# 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

Video Guide: For a visual walkthrough of the local Docker deployment process, check out our step-by-step video guide.

🛠️ 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:

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

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:

EMAIL_PROVIDER=smtp
EMAIL_FROM="Worklenz <[email protected]>"
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:

# Backend dependencies
cd worklenz-backend
npm install

# 🖥️ Frontend dependencies
cd ../worklenz-frontend
npm install

4. 🗄️ Set up the database:

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

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

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:

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) section above.

🌍 Production Deployment

The new Docker setup includes production-ready features for secure and scalable deployments.

⚡ Quick Production Setup

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

   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
   # - [email protected]
   # - 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:

   docker compose up -d
   

4. Access your application at: https://your-domain.com

🛠️ Management Commands

./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)

  docker compose up -d
  

• 🔵 Advanced Mode: Use external services (AWS S3, Azure Blob, external PostgreSQL)

  # Set DEPLOYMENT_MODE=advanced in .env
  docker compose up -d
  

For complete deployment documentation, see DOCKER_SETUP.md

Video Guide: For a complete walkthrough of deploying Worklenz to a remote server, check out our deployment video guide.

⚙️ 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:

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

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 [email protected] 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.
  

🤝 Contributing

We love contributions from the community! Here’s how you can help:

• 🐛 Report bugs
• ✨ Request features
• 📖 Improve the documentation
• 💬 Share Worklenz with your team or write about it

Please read CONTRIBUTING.md before submitting a pull request.

Contributors

Thanks to everyone who has contributed to Worklenz! 💙

💙 Community

Join the Worklenz community:

• 💬 Discord Server - chat with contributors and users
• 🐙 GitHub Discussions - longer form conversations
• 🐦 Follow updates on our website

We follow a Code of Conduct across all community spaces.

📄 License

Worklenz is open source, released under the GNU Affero General Public License v3.0.

By contributing to Worklenz, you agree your contributions will be licensed under AGPL v3.0.