DEV Community

Cover image for How I Self-Hosted Worklenz (And Why It Was Easier Than I Expected)
Gayan Thakshila
Gayan Thakshila

Posted on AI-assisted

How I Self-Hosted Worklenz (And Why It Was Easier Than I Expected)

I've been looking for a project management tool that I could run on my own server. Something where my data stays with me, and I don't have to worry about another monthly subscription. That's how I found Worklenz.

Worklenz is open source, and the team has made self-hosting pretty painless. Here's how I got it running, step by step.

What you need first

Before starting, make sure your machine (or server) has a few things installed:

  • Docker and Docker Compose (this does most of the heavy lifting)
  • Git (to grab the code)
  • Node.js 18+ and PostgreSQL 15+ if you plan to run it without Docker

Honestly, if you go the Docker route, Docker and Git are all you really need to think about.

Step 1: Get the code

Head over to the Worklenz GitHub repository and clone it to your machine. Then move into the project folder.

Step 2: Run the quick setup script

This is my favorite part. Inside the project there's a script called quick-setup.sh. Run it, and it takes care of the boring stuff for you:

  • It creates your environment file with secure secrets already generated
  • It sets up the URLs for your domain
  • It handles SSL certificates (self-signed for local, Let's Encrypt for production)
  • It starts all the services

No hunting for config values. No copy pasting random keys.

Step 3: Open it in your browser

Once the script finishes, go to localhost in your browser and Worklenz should be waiting for you. There's also a MinIO console on port 9001, which is where your uploaded files live.

That's it for local setup. Seriously.

Going live on a real server

If you want your team to use it, the process is almost the same:

  1. Point your domain's DNS A record to your server's IP address.
  2. Clone the repo on your server.
  3. Run the same quick setup script, and enter your domain when it asks (something like worklenz.yourcompany.com).
  4. Visit your domain with https and you're live.

The script will grab a free SSL certificate from Let's Encrypt for you.

Keeping things running smoothly

Worklenz comes with a handy manage.sh script. With it you can check status, view logs, stop or start services, create backups, restore them, and even upgrade to the latest version. You can also turn on automatic backups and decide how many days to keep them (30 by default).

A few tips I learned

  • Never push your .env file to GitHub. It holds your secrets.
  • Always use SSL in production.
  • Set up automatic backups early. Future you will be grateful.
  • Lock down your server with firewall rules.
  • Check your logs once in a while.

By default, Worklenz bundles PostgreSQL, Redis and MinIO together. If you'd rather use AWS S3, Azure Blob Storage or your own database, you can switch to "advanced" mode in the settings.

Wrapping up

I expected self-hosting an agency management tool to eat my whole weekend. It took me less than 30 minutes. If you like owning your data, give Worklenz a try.

If you get stuck, the official self-host guide has more detail, and there are video walkthroughs for both local and server setups.

Happy hosting!

Top comments (0)