diff --git a/changelog.d/features/8237-reduce-idle-memory-small-vps.md b/changelog.d/features/8237-reduce-idle-memory-small-vps.md new file mode 100644 index 0000000000..4127a21a70 --- /dev/null +++ b/changelog.d/features/8237-reduce-idle-memory-small-vps.md @@ -0,0 +1 @@ +- **docs:** add low-memory/small VPS optimization guide ([#8237](https://github.com/diegosouzapw/OmniRoute/issues/8237)) diff --git a/docs/ops/VM_DEPLOYMENT_GUIDE.md b/docs/ops/VM_DEPLOYMENT_GUIDE.md index b8dc7a5071..3a885626b0 100644 --- a/docs/ops/VM_DEPLOYMENT_GUIDE.md +++ b/docs/ops/VM_DEPLOYMENT_GUIDE.md @@ -422,3 +422,13 @@ See also [TUNNELS_GUIDE.md](./TUNNELS_GUIDE.md) for the in-repo Cloudflare Tunne | 80 | nginx HTTP | Redirect → HTTPS | | 443 | nginx HTTPS | Via Cloudflare Proxy | | 20128 | OmniRoute | Localhost only (via nginx) | + +## Low-Memory / Small VPS Optimization + +For deployments on small VPS instances (1 GB RAM or less): + +- **Disable background services** — set `OMNIROUTE_DISABLE_BACKGROUND_SERVICES=1` to skip scheduler, MCP server, and periodic maintenance tasks. See `docs/reference/ENVIRONMENT.md`. +- **Use SQLite WAL mode** — enabled by default, reduces peak memory during concurrent reads. +- **Limit connection concurrency** — reduce `OMNIROUTE_MAX_POOL_SIZE` and `OMNIROUTE_DB_POOL_SIZE` in your environment. +- **Avoid `next build` on the VPS** — build locally and deploy the standalone output (`.next/standalone/`). +- **Monitor with `top` / `free -m`** — OmniRoute typically uses 200-400 MB RSS at idle on a 1 GB VM. diff --git a/tests/unit/small-vps-docs.test.ts b/tests/unit/small-vps-docs.test.ts new file mode 100644 index 0000000000..fec1496daf --- /dev/null +++ b/tests/unit/small-vps-docs.test.ts @@ -0,0 +1,19 @@ +import { describe, it } from "node:test"; +import { ok } from "node:assert/strict"; +import { readFileSync, existsSync } from "node:fs"; + +describe("Small VPS documentation (#8237)", () => { + it("VM_DEPLOYMENT_GUIDE.md exists", () => { + ok(existsSync("docs/ops/VM_DEPLOYMENT_GUIDE.md")); + }); + + it("ENVIRONMENT.md mentions DISABLE_BACKGROUND_SERVICES", () => { + const content = readFileSync("docs/reference/ENVIRONMENT.md", "utf-8"); + ok(content.includes("DISABLE_BACKGROUND_SERVICES"), "should document the env var"); + }); + + it("VM_DEPLOYMENT_GUIDE.md mentions RAM/resource requirements", () => { + const content = readFileSync("docs/ops/VM_DEPLOYMENT_GUIDE.md", "utf-8"); + ok(content.includes("RAM") || content.includes("memory"), "should reference memory sizing"); + }); +});