diff --git a/README.md b/README.md
index f2c045251..ca58f627b 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
All-in-one open-source project management for efficient teams
@@ -52,7 +52,7 @@ Prefer full control over your data? Run Worklenz on your own server.
| Method | Guide |
|--------|-------|
-| 🐳 Docker (Recommended) | [Quick Docker Setup](#quick-start-docker) |
+| 🐳 Docker (Recommended) | [Quick Docker Setup](#quick-start-docker) |
| 🔧 Manual Installation | [Manual Dev Setup](#manual-installation) |
@@ -200,7 +200,8 @@ docker compose up -d
### 🛠️ Manual Installation (For Development)
-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 20 or higher)
@@ -211,8 +212,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:
@@ -246,6 +251,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:
@@ -261,6 +269,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
### 🏠 Local Development
@@ -478,4 +524,3 @@ By contributing to Worklenz, you agree your contributions will be licensed under
www.worklenz.com
-
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:**