Before you begin, ensure you have the following:
Start by cloning the Worklenz repository to your local machine:
git clone https://github.com/Worklenz/worklenz.git
Navigate to the project folder:
cd worklenz
The app uses Docker Compose for easier management of multiple containers. To configure the app with Docker Compose:
cp .env.sample .env
.env File with the Necessary CredentialsDB_NAME=worklenz_db
DB_USER=<your-db-username>
DB_PASSWORD=<your-db-password>
DB_HOST=localhost
DB_PORT=5432
AWS_REGION=<your-aws-region>
S3_URL=<your-s3-url>
S3_ACCESS_KEY_ID=<your-access-key>
S3_SECRET_ACCESS_KEY=<your-secret-key>
GOOGLE_CLIENT_ID=<your-google-client-id>
GOOGLE_CLIENT_SECRET=<your-google-client-secret>
GOOGLE_CALLBACK_URL=<your-callback-url>
SLACK_WEBHOOK=<your-slack-webhook-url>
COOKIE_SECRET=<your-cookie-secret>
SESSION_NAME=<your-session-name>
SESSION_SECRET=<your-session-secret>
ANGULAR_DIST_DIR=./dist
ANGULAR_SRC_DIR=./src
BACKEND_PUBLIC_DIR=./public
BACKEND_VIEWS_DIR=./views
COMMIT_BUILD_IMMEDIATELY=true
NODE_ENV=development
PORT=3000
HOSTNAME=localhost
Start your docker engine if it’s haven’t Use Docker Compose to build and start the containers:
docker-compose up --build -d
This command will do the following:
Stopping and Removing Containers To stop all running containers:
docker-compose down
To remove all containers and images (use with caution):
docker system prune -a
Once the containers are running, you can access the Worklenz App through the following:
While setting up Worklenz with Docker, you may encounter some common issues. Here are some solutions to resolve them:
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 --build -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 --build -d
Solution for Linux/macOS:
Ensure the database container is running:
docker ps
Check the database configuration in your .env file, especially:
DB_HOST DB_USER DB_PASSWORD
If the database container isn’t running, try restarting it:
docker-compose down
docker-compose up --build -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 --build -d
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.
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.
Solution for Linux/macOS:
Ensure your .env file is properly configured for external services like AWS or Google OAuth. Check that the required keys and URLs are correct.
You can test if external services are accessible by using curl:
curl https://your-service-url.com
Solution for Windows:
Similarly, verify that your .env file is correctly configured.
Test connectivity using curl (if installed) or use a web browser to check if external services are accessible.
Solution for Linux/macOS:
If Docker is running slowly, ensure that your machine has sufficient resources (CPU, RAM, Disk Space).
You can check resource usage with:
top
Consider increasing Docker’s allocated memory and CPU via the Docker Desktop settings.
Solution for Windows:
Similarly, monitor the system’s resource usage in Task Manager.
You can adjust Docker Desktop’s resource allocation through the Docker Desktop settings:
Open Docker Desktop > Go to Settings > Resources and adjust memory, CPU, and disk settings.
Solution for Linux/macOS:
Ensure that the Docker service is running. You can start Docker with:
sudo systemctl start docker
To check the Docker daemon status:
sudo systemctl status docker
Solution for Windows:
Ensure that Docker Desktop is running. You can start it from the Start Menu.
If Docker isn’t starting, try restarting Docker Desktop or reinstalling it if necessary.
Solution for Linux/macOS:
Make sure the containers are running:
docker ps
Check the port mappings in your docker-compose.yml file to ensure the correct ports are exposed.
If you’re accessing the app from a remote machine, ensure that your firewall is configured to allow traffic on ports 3000 and 4200.
Solution for Windows:
Check if the containers are running:
docker ps
Ensure your firewall is not blocking access to the relevant ports (3000 and 4200). You can add rules to allow these ports.
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 --build -d
If your Docker setup uses volumes for persistent data storage (e.g., for databases), make sure to back up your data regularly. You can do this with:
docker run --rm -v worklenz_db_volume:/data -v $(pwd):/backup ubuntu tar czf /backup/db_backup.tar.gz /data
Adjust the resource allocation (CPU and memory) in Docker Desktop settings (Windows/Mac) or through Docker Daemon configurations (Linux) to ensure smooth operation of the app.
If the application dependencies or Docker images are outdated, consider updating them. Use package managers (e.g., npm for Node.js) to update app dependencies inside the containers.
To free up disk space, remove unused Docker objects periodically:
docker system prune -a
If you need to run multiple instances of Worklenz on the same machine, update the ports in the docker-compose.yml file to avoid conflicts. For example, change 3000 to 3100 for the backend and 4200 to 4300 for the frontend.
To monitor container logs in real-time for debugging, use:
docker-compose logs -f