Self-host Worklenz

Worklenz is fully open-source and can be hosted on your own servers, giving you complete control over your data and infrastructure. This guide covers everything you need to get Worklenz running on your own machine or production server.

Prerequisites

Before you begin, make sure you have the following installed:

Requirement	Version
Node.js	v18 or newer
PostgreSQL	v15 or newer
Docker and Docker Compose	Latest stable
Git	Any recent version

Quick start with Docker (recommended)

Docker is the fastest and most reliable way to get Worklenz running. The automated setup script handles configuration, secrets, and SSL for you.

Automated setup

git clone https://github.com/Worklenz/worklenz.git
cd worklenz
./quick-setup.sh

The script automatically:

Creates a .env file with generated security secrets
Configures URLs for your domain
Sets up SSL certificates (self-signed for local, Let’s Encrypt for production)
Starts all services

Access points after setup:

Service	URL
Worklenz app	`https://localhost` or `http://localhost`
MinIO console	`http://localhost:9001`

Manual Docker setup

If you prefer to configure things yourself:

cp .env.example .env
# Edit .env with your required values
docker compose --profile express up -d

Manual installation (development)

Use this approach if you want to run Worklenz locally for development or testing without Docker.

1. Clone the repository:

git clone https://github.com/Worklenz/worklenz.git
cd worklenz

2. Configure the environment:

cp worklenz-backend/.env.template worklenz-backend/.env

3. Install dependencies:

cd worklenz-backend && npm install
cd ../worklenz-frontend && npm install

4. Initialize the database:

Run the following SQL files in order against your PostgreSQL database:

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

5. Start the services:

Open two terminal windows and run:

# Terminal 1 - Backend
cd worklenz-backend
npm run dev:all

# Terminal 2 - Frontend
cd worklenz-frontend
npm run dev

Access the app at http://localhost:5000.

Production deployment

Quick production setup

git clone https://github.com/Worklenz/worklenz.git
cd worklenz
./quick-setup.sh
# Enter your production domain when prompted (e.g., worklenz.example.com)

Manual production configuration

1. Configure the environment file:

cp .env.example .env

Edit .env and set the following key values:

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

Also generate secure secrets for DB_PASSWORD, SESSION_SECRET, and other sensitive variables:

openssl rand -hex 32

2. Point your DNS A record to your server IP.

3. Start with SSL:

docker compose --profile express --profile ssl up -d

Access your instance at https://your-domain.com.

Configuration

Key environment variables

Variable	Purpose
`DOMAIN`	Your domain (use `localhost` for local testing)
`DEPLOYMENT_MODE`	`express` (bundled services) or `advanced` (external services)
`STORAGE_PROVIDER`	`s3` (MinIO or AWS) or `azure`
`ENABLE_SSL`	`true` or `false` for SSL/TLS
`BACKUP_RETENTION_DAYS`	Number of days to retain backups (default: 30)
`DB_PASSWORD`	PostgreSQL password
`SESSION_SECRET`	Session encryption key

Deployment modes

Express mode (default) - includes PostgreSQL, Redis, and MinIO bundled together:

docker compose --profile express up -d

Advanced mode - use external services such as AWS S3, Azure Blob Storage, or an external PostgreSQL instance:

Set DEPLOYMENT_MODE=advanced in your .env file before starting.

Storage configuration

Worklenz uses MinIO by default for file storage, but supports multiple storage backends.

Provider	Details
MinIO (default)	S3-compatible, included in Docker setup. Console at `http://localhost:9001` (credentials: `minioadmin` / `minioadmin`). Default bucket: `worklenz-bucket` (created automatically).
AWS S3	Set `STORAGE_PROVIDER=s3` and configure AWS credentials in `.env`.
Azure Blob Storage	Set `STORAGE_PROVIDER=azure` and configure Azure credentials in `.env`.

Management commands

Use the manage.sh script to manage your Worklenz instance:

./manage.sh status          # View service status
./manage.sh logs            # View logs
./manage.sh backup          # Create a database backup
./manage.sh restore         # Restore from a backup
./manage.sh stop            # Stop all services
./manage.sh start           # Start all services
./manage.sh ssl             # Manage SSL certificates
./manage.sh upgrade         # Upgrade to the latest version
./manage.sh auto-configure  # Auto-generate secrets

Backups

Enable automated backups

docker compose --profile express --profile backup up -d

Manual backup and restore

./manage.sh backup    # Create a backup
./manage.sh restore   # Restore from a backup

Set BACKUP_RETENTION_DAYS in your .env file to control how long backups are kept.

Security best practices

Worklenz includes several security features out of the box:

Non-root containers (all services run as non-privileged users)
Network isolation (backend network is internal-only)
SSL/TLS support (Let’s Encrypt for production, self-signed for localhost)
Rate limiting on API and login endpoints
Security headers (HSTS, CSP, X-Frame-Options)
Auto-generated secure secrets

Video guides

Step-by-step video walkthroughs are available if you prefer a visual guide:

License

Worklenz is released under the GNU Affero General Public License v3 (AGPLv3).

For detailed Docker deployment documentation, see the DOCKER_SETUP.md file in the repository. For security vulnerability reports, contact info@worklenz.com.