From 0d285bf4791481cdc52aaad3af3ba7f0dacbcf50 Mon Sep 17 00:00:00 2001 From: chamikaJ Date: Wed, 7 Oct 2026 18:49:26 +0530 Subject: [PATCH 1/2] docs: clarify manual server deployment --- README.md | 52 +++++++++++++++++++++++++++++++++++--- SETUP_THE_PROJECT.md | 2 +- worklenz-backend/README.md | 2 +- 3 files changed, 51 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d07528282..83b1f9031 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ comprehensive solution for managing projects, tasks, and collaboration within te - [Tech Stack](#tech-stack) - [Getting Started](#getting-started) - [Quick Start (Docker)](#-quick-start-docker---recommended) - - [Manual Installation](#️-manual-installation-for-development) + - [Manual Installation](#️-manual-installation-no-docker) - [Deployment](#deployment) - [Local Development](#local-development-with-docker) - [Remote Server Deployment](#remote-server-deployment) @@ -128,9 +128,10 @@ docker compose down **Video Guide**: For a visual walkthrough of the local Docker deployment process, check out our [step-by-step video guide](https://www.youtube.com/watch?v=AfwAKxJbqLg). -### 🛠️ Manual Installation (For Development) +### 🛠️ Manual Installation (No Docker) -For developers who want to run the services individually or customize the setup. +Use this path to run the services individually, either for development or on a +server that does not use Docker. **Prerequisites:** - Node.js (version 18 or higher) @@ -141,8 +142,12 @@ For developers who want to run the services individually or customize the setup. 1. Clone the repository: ```bash +# 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: @@ -176,6 +181,9 @@ 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: @@ -191,6 +199,44 @@ 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. + +```bash +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: + +```bash +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 For local development, follow the [Quick Start (Docker)](#-quick-start-docker---recommended) section above. diff --git a/SETUP_THE_PROJECT.md b/SETUP_THE_PROJECT.md index ff4dcaca1..1c004047f 100644 --- a/SETUP_THE_PROJECT.md +++ b/SETUP_THE_PROJECT.md @@ -54,7 +54,7 @@ Getting started with development is a breeze! Follow these steps and you'll be c 3. **Configure Environment Variables:** - - Create a copy of the `.env.example` file and name it `.env`. + - Create a copy of the `.env.template` file and name it `.env`. - Update the required fields in `.env` with your specific configuration. 4. **Set up Database** diff --git a/worklenz-backend/README.md b/worklenz-backend/README.md index 96c6c5d51..f45781fbe 100644 --- a/worklenz-backend/README.md +++ b/worklenz-backend/README.md @@ -8,7 +8,7 @@ Follow these steps to set up the backend for development: 1. **Configure Environment Variables:** - - Create a copy of the `.env.example` file and name it `.env`. + - Create a copy of the `.env.template` file and name it `.env`. - Update the required fields in `.env` with your specific configuration. 2. **Set up Database:** From 8dbaedb6552e752a65cb9f72425e39bcb4eb5df8 Mon Sep 17 00:00:00 2001 From: chamikaJ Date: Wed, 7 Oct 2026 18:51:28 +0530 Subject: [PATCH 2/2] docs: retain manual installation heading --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 83b1f9031..2787d8a90 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ comprehensive solution for managing projects, tasks, and collaboration within te - [Tech Stack](#tech-stack) - [Getting Started](#getting-started) - [Quick Start (Docker)](#-quick-start-docker---recommended) - - [Manual Installation](#️-manual-installation-no-docker) + - [Manual Installation](#️-manual-installation-for-development) - [Deployment](#deployment) - [Local Development](#local-development-with-docker) - [Remote Server Deployment](#remote-server-deployment) @@ -128,7 +128,7 @@ docker compose down **Video Guide**: For a visual walkthrough of the local Docker deployment process, check out our [step-by-step video guide](https://www.youtube.com/watch?v=AfwAKxJbqLg). -### 🛠️ Manual Installation (No Docker) +### 🛠️ Manual Installation (For Development) Use this path to run the services individually, either for development or on a server that does not use Docker.