Worklenz
Sign in
Selfhost

Worklenz Docker Guide - The Agency Guide to Secure Self-Hosting

Chamika Jayasri
#Selfhost#Docker#WorklenzGuide
Worklenz Docker Guide

Worklenz Docker Guide

Efficient project management starts with tools that are not only powerful but also easy to deploy. Docker, a leading platform for containerized application deployment, is transforming the way businesses manage software installations. By simplifying complex configurations and ensuring consistency across environments, Docker has become an essential tool for modern teams.

For Worklenz, Docker offers a seamless deployment experience tailored to the needs of both startups and enterprises. With its portability, scalability, and efficient resource management, Docker eliminates the challenges of traditional installations, allowing teams to focus on what truly matters, achieving project success.

Discover how deploying Worklenz with Docker can elevate your team’s efficiency and simplify your IT operations.

Who Should Use This?

If you’re a tech-savvy startup, a growing business, or an enterprise looking for a cost-effective, scalable task management solution, self-hosting Worklenz with Docker is a game-changer! With full control over your data, seamless scalability, and flexibility, Docker deployment is ideal for teams that want a robust and secure task management platform without relying on third-party hosting.

Table of Contents

What You Need to Begin

Before you begin, ensure you have the following:

  • Docker - For containerization
  • Docker Compose - For managing multiple services
  • Git (recommended) - For cloning the repository
  • Internet access to download required files
  • Basic familiarity with opening a terminal (Command Prompt or equivalent)

If Docker isn’t installed yet, follow this guide to set it up first. If Docker Compose isn’t installed yet, follow this guide to set it up. If Git isn’t installed yet, follow this guide to set up Git on your computer.

Minimum system requirements

  • CPU: 2+ cores
  • RAM: 4GB minimum (8GB recommended)
  • Disk Space: 10GB free for Docker images and containers

The fastest way to get Worklenz running is to use the automated setup script. This method handles environment configuration, SSL setup, and service initialization automatically.

Step 1: Clone the Repository

Open your terminal and clone the Worklenz repository:

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

Step 2: Run the Quick Setup Script

Execute the quick-setup script which will:

  • Create a .env file with auto-generated security secrets
  • Configure URLs based on your domain
  • Set up SSL certificates (self-signed for localhost, Let’s Encrypt for production)
./quick-setup.sh

Step 3: Start the Services

For the default Express profile (PostgreSQL, Redis, and MinIO included):

docker compose --profile express up -d

That’s it! Your Worklenz instance should now be running.

Manual Setup Method

For more control over the configuration, you can set up Worklenz manually.

Step 1: Cloning from the Repository

Option 1: Use Git to Clone the Repository

Open your terminal (or Command Prompt, PowerShell, or Git Bash) and execute the following command to clone the repository to your local machine:

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

Option 2: Download the Application Files

If Git is not installed, you can manually download the files. Visit the Worklenz repository, click on the “Code” button, and select “Download ZIP.” Extract the downloaded ZIP file and navigate to the folder:

cd worklenz

Step 2: Prepare the Docker Environment

Copy the environment template file to create your .env file:

cp .env.template .env

Open the .env file in your preferred text editor and configure it according to your environment. The template file contains all necessary variables with comments explaining what each one does. Key variables to configure include:

  • Database credentials (DB_USER, DB_PASSWORD, DB_NAME)
  • Security secrets (SESSION_SECRET, COOKIE_SECRET, JWT_SECRET)
  • Optional services (Google OAuth, AWS S3, Slack webhooks)

Refer to the .env.template file in the repository for the complete list of available configuration options.

Step 3: Build and Start Containers

Make sure your Docker engine is running, then use Docker Compose to build and start the containers:

docker compose --profile express up -d

This command will:

  • Build the Docker images if they don’t exist
  • Start all containers (database, Redis, MinIO, backend, frontend) in detached mode (-d)
  • Ensure all necessary services are running

Stopping Containers

To stop all running containers:

docker compose down

To stop containers and remove volumes (be careful - this will delete data):

docker compose down -v

Deployment Profiles

Worklenz supports different deployment profiles for different use cases:

Express Mode (Default - Recommended)

Includes PostgreSQL, Redis, and MinIO in one setup. Best for most deployments:

docker compose --profile express up -d

Advanced Mode

Allows you to use external services like AWS S3 or Azure Blob Storage instead of MinIO. Configure your cloud storage credentials in .env and run:

docker compose up -d

Managing Your Deployment

Use the manage.sh script for common operations:

# Check status of all services
./manage.sh status

# View logs
./manage.sh logs

# Create a backup
./manage.sh backup

# Manage SSL certificates
./manage.sh ssl

Access the App

Once the containers are running, you can access Worklenz through the following URLs:

  • Frontend (Web App): http://localhost or https://localhost (if SSL is configured)
  • Backend API: http://localhost:3000
  • MinIO Storage Console: http://localhost:9001
    • Default Credentials: minioadmin / minioadmin

Note: For production deployments, configure proper domain names and SSL certificates for secure access.

Troubleshooting Common Issues

While setting up Worklenz with Docker, you may encounter some common issues. Here are some solutions to resolve them:

Issue 1: Containers Not Starting

Solution for Linux/macOS: Check the Docker container logs for any errors:

docker compose logs

If you see errors related to missing environment variables or other issues, ensure that your .env file is properly configured and all necessary fields are filled.

You can also check if there are any conflicting services or ports in use:

sudo lsof -i :3000

If port 3000 is in use, stop the process using it:

sudo kill -9 <PID>

Restart the Docker containers:

docker compose down
docker compose up -d

Solution for Windows:

Check the Docker container logs for any errors:

docker compose logs

If you see errors related to missing environment variables or other issues, verify your .env file.

To check if port 3000 is in use, run:

netstat -ano | findstr :3000

Find the PID (Process ID) from the output, and stop the process using:

taskkill /PID <PID> /F

Restart the Docker containers:

docker compose down
docker compose up -d

Issue 2: Database Connection Issues

Solution for Linux/macOS:

Ensure the database container is running:

docker ps

Check the database configuration in your .env file, especially:

  • DB_HOST (should be postgres for Docker)
  • DB_USER
  • DB_PASSWORD

If the database container isn’t running, try restarting it:

docker compose down
docker compose up -d

Solution for Windows:

Check if the database container is running:

docker ps

Verify the database configuration in your .env file.

Restart the containers if needed:

docker compose down
docker compose up -d

Issue 3: Port Already in Use

Solution for Linux/macOS:

If you get an error saying a port is already in use (e.g., port 3000), you can find the process using the port:

sudo lsof -i :3000

If a process is using the port, kill it with:

sudo kill -9 <PID>

Alternatively, you can change the port in your .env file and restart the containers.

Solution for Windows:

Check if port 3000 is in use:

netstat -ano | findstr :3000

Find the PID (Process ID) from the output, then terminate the process:

taskkill /PID <PID> /F

You can also change the port in your .env file and restart the containers.

Issue 4: Permissions Issues with Files

Solution for Linux/macOS:

If you encounter permission errors, ensure that the necessary files and directories are accessible by Docker. Check file permissions:

ls -l

Adjust file permissions using:

sudo chmod -R 755 <directory>

Solution for Windows:

If you encounter permission errors, ensure Docker Desktop has access to the necessary directories. Right-click on the folder, select Properties, and go to the Security tab to check the permissions.

Issue 5: Slow Performance or Timeout Errors

Solution:

If Docker is running slowly, ensure that your machine has sufficient resources (CPU, RAM, Disk Space). Adjust Docker Desktop’s resource allocation:

  • Windows/macOS: Open Docker Desktop > Settings > Resources and increase memory and CPU allocation
  • Linux: Configure Docker daemon settings to allocate more resources

Consider increasing allocated memory to at least 4GB for smooth operation.

Issue 6: Unable to Access App in Browser

Solution:

Ensure the containers are running:

docker ps

Check that your firewall allows access to the required ports. Try accessing:

  • Frontend: http://localhost
  • Backend API: http://localhost:3000

If accessing from a remote machine, configure your firewall to allow traffic on these ports.

Additional notes

  • Updating Docker Images:

To ensure you are using the latest versions of the Docker images, you can pull the latest versions before building the containers:

docker compose pull
docker compose up -d
  • Backing Up Your Data:

If your Docker setup uses volumes for persistent data storage (e.g., for databases), make sure to back up your data regularly. You can use the manage.sh script:

./manage.sh backup

Or manually backup volumes:

docker run --rm -v worklenz_db_volume:/data -v $(pwd):/backup ubuntu tar czf /backup/db_backup.tar.gz /data
  • Docker Resource Allocation:

Adjust resource allocation (CPU and memory) in Docker Desktop settings (Windows/Mac) or through Docker Daemon configurations (Linux) to ensure smooth operation of the app.

  • Updating Dependencies:

If application dependencies are outdated, consider updating them. For Node.js applications, dependencies inside containers can be updated using package managers (npm, yarn, etc.).

  • Clean Up Unused Resources:

To free up disk space, remove unused Docker objects periodically:

docker system prune -a
⚠️ Be cautious! This command will delete unused images and volumes, which may result in losing any unsaved data. Always ensure that you have backed up important data before running this command.
  • Custom Ports:

If you need to run multiple instances of Worklenz on the same machine, modify the ports in the docker-compose.yml file to avoid conflicts. For example, change port 3000 to 3100 for the backend.

  • Monitor Logs:

To monitor container logs in real-time for debugging, use:

docker compose logs -f
  • SSL/HTTPS Configuration:

For production deployments, configure proper SSL certificates. Use the manage.sh script to manage SSL:

./manage.sh ssl

For Let’s Encrypt integration, follow the setup wizard to automatically configure HTTPS.

Wrapping Up: Simplify Your Deployment with Docker

Deploying Worklenz using Docker streamlines the deployment process, eliminating the complexities of traditional installation methods. With the automated quick-setup.sh script and Docker Compose, you can have a fully functional, production-ready instance of Worklenz running in just a few commands.

Whether you choose the quick-setup method for ease or the manual method for more control, Docker provides the flexibility and reliability needed for modern project management. With easy scaling, efficient resource management, and the ability to use different deployment profiles (Express Mode with MinIO, or Advanced Mode with external cloud storage), Docker deployments work for startups, growing teams, and enterprises alike.

The manage.sh script provides easy access to common operations like checking status, viewing logs, managing backups, and configuring SSL certificates. Everything you need to keep your deployment running smoothly.

Ready to Get Started?

Don’t let deployment challenges slow you down. Here’s your quick start:

  1. Clone the repository: git clone https://github.com/Worklenz/worklenz.git
  2. Run the setup: ./quick-setup.sh
  3. Start the services: docker compose --profile express up -d
  4. Access your instance: http://localhost

Take the first step towards a smoother, more efficient project management experience. Download Worklenz from our GitHub repository today and begin your journey to enhanced productivity.

Need help? Our team is here for you. Contact us for any assistance or inquiries, or check out the official documentation for more details. You can also join our Discord community for real-time support and discussions with other Worklenz users.