Skip to content

TaskView is a self-hosted project and task management platform focused on clarity, ownership, and control. TaskView is built for teams that want a transparent, self-hosted alternative to SaaS task managers.

fix: #88

Nikolai Giman645f2e21e573
diff --git a/api/ecosystem.config.js b/api/ecosystem.config.js
index 6e52304..317fe0e 100644
--- a/api/ecosystem.config.js
+++ b/api/ecosystem.config.js
@@ -1,9 +1,38 @@
+// https://github.com/Gimanh/taskview-community/issues/88
+// GH-88: one worker per core ('max') multiplied by the per-worker DB pool
+// (DB_POOL_MAX, default 20) exhausts Postgres max_connections (default 100)
+// on many-core hosts. Default to 2 workers; scale explicitly via PM2_INSTANCES.
+// If you set PM2_INSTANCES to 'max', size DB_POOL_MAX yourself so that
+// workers × DB_POOL_MAX stays below the Postgres max_connections limit.
+const rawInstances = process.env.PM2_INSTANCES;
+const instances = rawInstances === 'max'
+ ? 'max'
+ : Number(rawInstances) > 0
+ ? Number(rawInstances)
+ : 2;
+
+const poolMax = Number(process.env.DB_POOL_MAX) > 0 ? Number(process.env.DB_POOL_MAX) : 20;
+
+if (instances === 'max') {
+ console.warn(
+ '[taskview] PM2_INSTANCES=max spawns one worker per CPU core, each with its own '
+ + `DB pool (${poolMax} connections). Make sure workers x DB_POOL_MAX stays below `
+ + 'the Postgres max_connections limit (default 100).'
+ );
+} else if (instances * poolMax > 80) {
+ console.warn(
+ `[taskview] DB connection budget: ${instances} worker(s) x ${poolMax} pool connections = `
+ + `${instances * poolMax} potential connections. Postgres default max_connections is 100 - `
+ + 'lower PM2_INSTANCES or DB_POOL_MAX if the database rejects connections.'
+ );
+}
+
module.exports = {
apps: [
{
name: 'taskview-server',
script: 'taskview-server.js',
- instances: 'max',
+ instances,
watch: true,
ignore_watch: ['logs'],
autorestart: true,
diff --git a/api/package.json b/api/package.json
index fa618f1..7f2c6f7 100644
--- a/api/package.json
+++ b/api/package.json
@@ -1,6 +1,6 @@
{
"name": "taskview-ce-api-server",
- "version": "1.50.3",
+ "version": "1.50.4",
"scripts": {
"dev": "bun run --watch ./server.ts",
"start": "NODE_ENV=production node ./dist/taskview-server.js",
@@ -83,4 +83,4 @@
"engines": {
"node": ">=24 <25"
}
-}
\ No newline at end of file
+}
diff --git a/api/production.ecosystem.config.js b/api/production.ecosystem.config.js
index 6e52304..8cdb4d9 100644
--- a/api/production.ecosystem.config.js
+++ b/api/production.ecosystem.config.js
@@ -1,11 +1,38 @@
+// GH-88: one worker per core ('max') multiplied by the per-worker DB pool
+// (DB_POOL_MAX, default 20) exhausts Postgres max_connections (default 100)
+// on many-core hosts. Default to 2 workers; scale explicitly via PM2_INSTANCES.
+// If you set PM2_INSTANCES to 'max', size DB_POOL_MAX yourself so that
+// workers × DB_POOL_MAX stays below the Postgres max_connections limit.
+const rawInstances = process.env.PM2_INSTANCES;
+const instances = rawInstances === 'max'
+ ? 'max'
+ : Number(rawInstances) > 0
+ ? Number(rawInstances)
+ : 2;
+
+const poolMax = Number(process.env.DB_POOL_MAX) > 0 ? Number(process.env.DB_POOL_MAX) : 20;
+
+if (instances === 'max') {
+ console.warn(
+ '[taskview] PM2_INSTANCES=max spawns one worker per CPU core, each with its own '
+ + `DB pool (${poolMax} connections). Make sure workers x DB_POOL_MAX stays below `
+ + 'the Postgres max_connections limit (default 100).'
+ );
+} else if (instances * poolMax > 80) {
+ console.warn(
+ `[taskview] DB connection budget: ${instances} worker(s) x ${poolMax} pool connections = `
+ + `${instances * poolMax} potential connections. Postgres default max_connections is 100 - `
+ + 'lower PM2_INSTANCES or DB_POOL_MAX if the database rejects connections.'
+ );
+}
+
module.exports = {
apps: [
{
name: 'taskview-server',
script: 'taskview-server.js',
- instances: 'max',
- watch: true,
- ignore_watch: ['logs'],
+ instances,
+ watch: false,
autorestart: true,
max_memory_restart: '1G',
env_production: {
diff --git a/docs/1.getting-started/2.installation.md b/docs/1.getting-started/2.installation.md
index 4dc7cec..b5a37d9 100644
--- a/docs/1.getting-started/2.installation.md
+++ b/docs/1.getting-started/2.installation.md
@@ -40,7 +40,12 @@ DB_USER="taskview_db_user"
DB_PASSWORD="your_secure_password"
DB_NAME="taskviewdb"
DB_PORT=5432
+# Postgres connections per API worker (this is the default)
+DB_POOL_MAX=20
APP_PORT=1401
+# API worker processes (this is the default). Accepts a number or "max" (one worker per CPU core).
+# Keep PM2_INSTANCES x DB_POOL_MAX below the Postgres max_connections limit (default 100).
+PM2_INSTANCES=2
JWT_ALG="HS256"
JWT_SIGN="secret"
ACCESS_LIFE_TIME="3d"
@@ -235,6 +240,7 @@ The migration container will automatically apply any new database changes on sta
- **Use a reverse proxy** (Nginx, Caddy, Traefik) to terminate SSL and serve everything over HTTPS
- **Update `APP_URL`** in `.env.taskview` and `TASKVIEW_API_URL` on the webapp service to match your production domains
- **Trim the login page** — set `AUTH_LOGIN_METHODS` in `.env.taskview` to offer only the sign-in methods you actually use (e.g. `AUTH_LOGIN_METHODS="password"`). Google/GitHub/Apple buttons are shown only when the provider is configured.
+- **Scale API workers deliberately** — the API runs `PM2_INSTANCES` worker processes (default `2`), and each worker opens its own pool of up to `DB_POOL_MAX` Postgres connections (default `20`). Before raising either value (or using `PM2_INSTANCES=max`), make sure `workers × DB_POOL_MAX` stays below your Postgres `max_connections` (default `100`) — otherwise the API fails with *"sorry, too many clients already"*. The API logs a warning on startup when the budget looks too high.
- **Back up the database** - the `pgdata` volume contains all your data
- **Set `restart: unless-stopped`** on all services so they survive server reboots
- **SMTP setup** - add SMTP variables to `.env.taskview` if you want email features (password recovery, invitations). See [Configuration](/docs/configuration/environment-variables) for details.
diff --git a/docs/4.configuration/1.environment-variables.md b/docs/4.configuration/1.environment-variables.md
index 13f9386..5ca1c85 100644
--- a/docs/4.configuration/1.environment-variables.md
+++ b/docs/4.configuration/1.environment-variables.md
@@ -18,12 +18,16 @@ These must match your PostgreSQL setup.
| `DB_PASSWORD` | Yes | - | Database password |
| `DB_NAME` | Yes | - | Database name |
| `DB_PORT` | No | `5432` | Database port |
+| `DB_POOL_MAX` | No | `20` | Maximum Postgres connections **per API worker** (each worker opens its own pool) |
+
+**Connection budget:** the total number of Postgres connections is roughly `PM2_INSTANCES × DB_POOL_MAX`. Keep it below the `max_connections` of your PostgreSQL (default `100`), leaving ~10 connections of headroom for migrations and maintenance. The API logs a warning at startup when the estimate exceeds 80.
## Application
| Variable | Required | Default | Description |
|---|---|---|---|
| `APP_PORT` | No | `1401` | Port the API server listens on |
+| `PM2_INSTANCES` | No | `2` | Number of API worker processes (PM2 cluster mode). Accepts a number or `max` (one worker per CPU core). When using `max`, set `DB_POOL_MAX` yourself so the connection budget above still fits. |
| `APP_URL` | Yes | https://app.taskview.tech | Full URL of the web app (e.g. `https://tasks.company.com`). Used for OAuth redirects and email links. |
| `TRUST_PROXY` | No | `false` | Set when running behind a reverse proxy so `X-Forwarded-Proto`/`X-Forwarded-For` are honoured (correct `https` URLs, real client IP). Use the number of proxies in front of the app (`1` for a single Caddy/nginx), or an IP/subnet list (`10.0.0.0/8`, `uniquelocal`). Leave unset for direct access. Avoid `true` (trusts any hop, allows header spoofing). |
@@ -213,7 +217,12 @@ DB_USER="taskview_db_user"
DB_PASSWORD="password"
DB_NAME="taskview"
DB_PORT=5432
+# Postgres connections per API worker (this is the default)
+DB_POOL_MAX=20
APP_PORT=1401
+# API worker processes (this is the default). Accepts a number or "max" (one worker per CPU core).
+# Keep PM2_INSTANCES x DB_POOL_MAX below the Postgres max_connections limit (default 100).
+PM2_INSTANCES=2
JWT_ALG="HS256"
JWT_SIGN="secret"
ACCESS_LIFE_TIME="3d"
diff --git a/package.json b/package.json
index 2ef8b4e..1765eb4 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "taskview-ce-monorepo",
- "version": "1.50.3",
+ "version": "1.50.4",
"private": true,
"description": "TaskView CE monorepo containing web, API, and packages",
"workspaces": [
@@ -44,4 +44,4 @@
"passport-github2": "^0.1.12",
"passport-google-oauth20": "^2.0.0"
}
-}
\ No newline at end of file
+}
diff --git a/web/package.json b/web/package.json
index 762f8c8..79ac224 100644
--- a/web/package.json
+++ b/web/package.json
@@ -2,7 +2,7 @@
"name": "web-nuxt-ui",
"private": true,
"type": "module",
- "version": "1.50.3",
+ "version": "1.50.4",
"scripts": {
"dev": "vite",
"build:packages": "pnpm --filter taskview-db-schemas build && pnpm --filter taskview-api build && pnpm --filter capacitor-widget-bridge build",
@@ -92,4 +92,4 @@
"vue-tsc": "^3.2.2"
},
"packageManager": "[email protected]"
-}
\ No newline at end of file
+}