@seip/bluebird-js 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/.env_example +54 -0
  2. package/AGENTS.md +403 -0
  3. package/LICENSE +21 -0
  4. package/README.md +284 -2
  5. package/app/routes/api.js +50 -0
  6. package/app/routes/web.js +53 -0
  7. package/app/views/about.html +161 -0
  8. package/app/views/dashboard.html +140 -0
  9. package/app/views/index.html +150 -0
  10. package/app/views/login.html +144 -0
  11. package/core/app.d.ts +18 -0
  12. package/core/app.js +644 -0
  13. package/core/auth.d.ts +13 -0
  14. package/core/auth.js +326 -0
  15. package/core/cache.d.ts +17 -0
  16. package/core/cache.js +475 -0
  17. package/core/cli/doctor.js +287 -0
  18. package/core/cli/ecosystem.js +162 -0
  19. package/core/cli/init.js +779 -0
  20. package/core/cli/migrate.js +541 -0
  21. package/core/cli/model.js +66 -0
  22. package/core/cli/nginx.js +199 -0
  23. package/core/cli/route.js +121 -0
  24. package/core/cli/swagger.js +45 -0
  25. package/core/cli/view.js +77 -0
  26. package/core/config.d.ts +3 -0
  27. package/core/config.js +111 -0
  28. package/core/csrf.d.ts +3 -0
  29. package/core/csrf.js +114 -0
  30. package/core/database.d.ts +15 -0
  31. package/core/database.js +636 -0
  32. package/core/debug.d.ts +3 -0
  33. package/core/debug.js +250 -0
  34. package/core/hash.d.ts +3 -0
  35. package/core/hash.js +194 -0
  36. package/core/index.d.ts +1071 -0
  37. package/core/logger.d.ts +3 -0
  38. package/core/logger.js +124 -0
  39. package/core/middleware.d.ts +3 -0
  40. package/core/middleware.js +28 -0
  41. package/core/model.d.ts +19 -0
  42. package/core/model.js +600 -0
  43. package/core/queue.d.ts +13 -0
  44. package/core/queue.js +172 -0
  45. package/core/ratelimit.d.ts +3 -0
  46. package/core/ratelimit.js +145 -0
  47. package/core/redis.d.ts +21 -0
  48. package/core/redis.js +230 -0
  49. package/core/render.d.ts +3 -0
  50. package/core/render.js +676 -0
  51. package/core/router.d.ts +3 -0
  52. package/core/router.js +171 -0
  53. package/core/seo.d.ts +3 -0
  54. package/core/seo.js +106 -0
  55. package/core/swagger.d.ts +3 -0
  56. package/core/swagger.js +60 -0
  57. package/core/upload.d.ts +13 -0
  58. package/core/upload.js +102 -0
  59. package/core/util/colors.js +82 -0
  60. package/core/validate.d.ts +15 -0
  61. package/core/validate.js +364 -0
  62. package/core/vite.d.ts +3 -0
  63. package/core/vite.js +145 -0
  64. package/core/ws.d.ts +13 -0
  65. package/core/ws.js +245 -0
  66. package/index.js +18 -0
  67. package/jsconfig.json +15 -0
  68. package/package.json +84 -3
  69. package/production.md +273 -0
  70. package/public/css/bluebird.min.css +2 -0
  71. package/public/images/favicon.ico +0 -0
  72. package/public/js/bluebird-client.js +1663 -0
  73. package/public/js/bluebird.min.js +1073 -0
package/core/ws.js ADDED
@@ -0,0 +1,245 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { getRedisClient } from "./cache.js";
3
+ import Auth from "./auth.js";
4
+
5
+ let WebSocketServer = null;
6
+ let WebSocket = null;
7
+
8
+ try {
9
+ const wsModule = await import("ws");
10
+ WebSocketServer = wsModule.WebSocketServer || wsModule.default?.WebSocketServer;
11
+ WebSocket = wsModule.WebSocket || wsModule.default?.WebSocket;
12
+ } catch {}
13
+
14
+ /**
15
+ * High-performance WebSocketManager providing real-time channels, room management,
16
+ * heartbeat ping/pong, Auth token verification, and Redis Pub/Sub multi-process cluster scaling.
17
+ */
18
+ class WebSocketManager {
19
+ /**
20
+ * Initializes the WebSocket manager attached to an HTTP server.
21
+ * @param {import('http').Server} server - Express HTTP server instance.
22
+ * @param {Object} [options={}] - Configuration options.
23
+ * @param {string} [options.path="/ws"] - WebSocket endpoint route.
24
+ * @param {boolean} [options.auth=false] - Require valid Auth JWT token on connection.
25
+ * @param {number} [options.maxPayload=1048576] - Maximum payload size in bytes (default 1MB).
26
+ */
27
+ constructor(server, options = {}) {
28
+ if (!WebSocketServer || !WebSocket) {
29
+ throw new Error(
30
+ "[WS ERROR] 'ws' package is not installed. Install it with: npm install ws or npx blue-bird add ws",
31
+ );
32
+ }
33
+
34
+ this.server = server;
35
+ this.path = options.path || "/ws";
36
+ this.requireAuth = options.auth ?? false;
37
+ this.maxPayload = options.maxPayload || 1024 * 1024;
38
+ this.instanceId = randomUUID();
39
+ this.rooms = new Map();
40
+ this.clients = new Set();
41
+ this.connectionHandler = null;
42
+ this.redisPublisher = null;
43
+ this.redisSubscriber = null;
44
+
45
+ this.wss = new WebSocketServer({
46
+ noServer: true,
47
+ maxPayload: this.maxPayload,
48
+ });
49
+
50
+ this._setupUpgrade();
51
+ this._setupHeartbeat();
52
+ this._setupRedisPubSub();
53
+ }
54
+
55
+ /**
56
+ * Attaches the HTTP Upgrade listener to the Express HTTP server instance.
57
+ * @private
58
+ */
59
+ _setupUpgrade() {
60
+ this.server.on("upgrade", async (request, socket, head) => {
61
+ try {
62
+ const urlObj = new URL(request.url, `http://${request.headers.host || "localhost"}`);
63
+ if (urlObj.pathname !== this.path) {
64
+ return;
65
+ }
66
+
67
+ if (this.requireAuth) {
68
+ const cookieHeader = request.headers.cookie || "";
69
+ const cookies = {};
70
+ cookieHeader.split(";").forEach((c) => {
71
+ const parts = c.trim().split("=");
72
+ if (parts[0]) cookies[parts[0]] = decodeURIComponent(parts[1] || "");
73
+ });
74
+
75
+ const token = cookies.auth || urlObj.searchParams.get("token") || request.headers.authorization?.split(" ")[1];
76
+ const user = token ? Auth.verifyToken(token) : null;
77
+
78
+ if (!user) {
79
+ socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
80
+ socket.destroy();
81
+ return;
82
+ }
83
+ request.user = user;
84
+ }
85
+
86
+ this.wss.handleUpgrade(request, socket, head, (ws) => {
87
+ this.wss.emit("connection", ws, request);
88
+ });
89
+ } catch (err) {
90
+ socket.destroy();
91
+ }
92
+ });
93
+
94
+ this.wss.on("connection", (ws, req) => {
95
+ ws.isAlive = true;
96
+ ws.user = req.user || null;
97
+ ws.rooms = new Set();
98
+ this.clients.add(ws);
99
+
100
+ ws.on("pong", () => {
101
+ ws.isAlive = true;
102
+ });
103
+
104
+ ws.on("close", () => {
105
+ this.clients.delete(ws);
106
+ ws.rooms.forEach((room) => this.leave(room, ws));
107
+ });
108
+
109
+ ws.on("error", () => {
110
+ this.clients.delete(ws);
111
+ });
112
+
113
+ ws.join = (room) => this.join(room, ws);
114
+ ws.leave = (room) => this.leave(room, ws);
115
+ ws.sendJSON = (data) => {
116
+ if (ws.readyState === WebSocket.OPEN) {
117
+ ws.send(JSON.stringify(data));
118
+ }
119
+ };
120
+
121
+ if (this.connectionHandler) {
122
+ this.connectionHandler(ws, req);
123
+ }
124
+ });
125
+ }
126
+
127
+ /**
128
+ * Registers a connection callback handler.
129
+ * @param {Function} handler - Callback function: (ws, req) => {}
130
+ */
131
+ onConnection(handler) {
132
+ this.connectionHandler = handler;
133
+ }
134
+
135
+ /**
136
+ * Subscribes a WebSocket connection to a room.
137
+ * @param {string} room - Room identifier.
138
+ * @param {WebSocket} ws - Target WebSocket instance.
139
+ */
140
+ join(room, ws) {
141
+ if (!this.rooms.has(room)) {
142
+ this.rooms.set(room, new Set());
143
+ }
144
+ this.rooms.get(room).add(ws);
145
+ ws.rooms.add(room);
146
+ }
147
+
148
+ /**
149
+ * Unsubscribes a WebSocket connection from a room.
150
+ * @param {string} room - Room identifier.
151
+ * @param {WebSocket} ws - Target WebSocket instance.
152
+ */
153
+ leave(room, ws) {
154
+ if (this.rooms.has(room)) {
155
+ this.rooms.get(room).delete(ws);
156
+ if (this.rooms.get(room).size === 0) {
157
+ this.rooms.delete(room);
158
+ }
159
+ }
160
+ ws.rooms.delete(room);
161
+ }
162
+
163
+ /**
164
+ * Broadcasts a JSON payload or string to all connected clients (or specific room).
165
+ * Automatically synchronizes across cluster workers via Redis Pub/Sub without duplicate delivery.
166
+ * @param {any} data - Data to send.
167
+ * @param {string} [room=null] - Optional target room.
168
+ */
169
+ broadcast(data, room = null) {
170
+ const payload = typeof data === "string" ? data : JSON.stringify(data);
171
+
172
+ this._sendLocal(payload, room);
173
+
174
+ if (this.redisPublisher && this.redisPublisher.isOpen) {
175
+ this.redisPublisher
176
+ .publish(
177
+ "bluebird:ws:broadcast",
178
+ JSON.stringify({ instanceId: this.instanceId, room, payload })
179
+ )
180
+ .catch(() => {});
181
+ }
182
+ }
183
+
184
+ /**
185
+ * Transmits payload to local WebSocket connections.
186
+ * @private
187
+ */
188
+ _sendLocal(payload, room = null) {
189
+ const targetSockets = room && this.rooms.has(room) ? this.rooms.get(room) : this.clients;
190
+ targetSockets.forEach((client) => {
191
+ if (client.readyState === WebSocket.OPEN) {
192
+ client.send(payload);
193
+ }
194
+ });
195
+ }
196
+
197
+ /**
198
+ * Sets up 30s ping/pong heartbeat to clear dead TCP sockets.
199
+ * @private
200
+ */
201
+ _setupHeartbeat() {
202
+ this.heartbeatInterval = setInterval(() => {
203
+ this.clients.forEach((ws) => {
204
+ if (ws.isAlive === false) {
205
+ this.clients.delete(ws);
206
+ return ws.terminate();
207
+ }
208
+ ws.isAlive = false;
209
+ ws.ping();
210
+ });
211
+ }, 30000);
212
+ this.heartbeatInterval.unref();
213
+ }
214
+
215
+ /**
216
+ * Initializes Redis Pub/Sub channels for multi-process cluster synchronization.
217
+ * @private
218
+ */
219
+ async _setupRedisPubSub() {
220
+ try {
221
+ const redisClient = getRedisClient();
222
+ if (!redisClient) return;
223
+
224
+ this.redisPublisher = redisClient.duplicate();
225
+ this.redisSubscriber = redisClient.duplicate();
226
+
227
+ this.redisPublisher.on("error", () => {});
228
+ this.redisSubscriber.on("error", () => {});
229
+
230
+ await this.redisPublisher.connect();
231
+ await this.redisSubscriber.connect();
232
+
233
+ await this.redisSubscriber.subscribe("bluebird:ws:broadcast", (message) => {
234
+ try {
235
+ const messageData = JSON.parse(message);
236
+ if (messageData.instanceId === this.instanceId) return;
237
+ this._sendLocal(messageData.payload, messageData.room);
238
+ } catch {}
239
+ });
240
+ } catch {}
241
+ }
242
+ }
243
+
244
+ export { WebSocketManager };
245
+ export default WebSocketManager;
package/index.js ADDED
@@ -0,0 +1,18 @@
1
+ import App from "@seip/bluebird-js/core/app.js";
2
+ import routerApi from "./app/routes/api.js";
3
+ import routerWeb from "./app/routes/web.js";
4
+
5
+ /**
6
+ * Main entry point for the Blue Bird application.
7
+ * Initializes the App instance with routes, configuration, and starts the server.
8
+ */
9
+ const app = new App({
10
+ routes: [routerWeb, routerApi],
11
+ cors: {},
12
+ middlewares: [],
13
+ host: "http://localhost",
14
+ port: process.env.PORT || 3000,
15
+ logger: false,
16
+ });
17
+
18
+ app.run();
package/jsconfig.json ADDED
@@ -0,0 +1,15 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2022",
4
+ "module": "NodeNext",
5
+ "moduleResolution": "NodeNext",
6
+ "checkJs": false,
7
+ "allowJs": true
8
+ },
9
+ "include": [
10
+ "public/**/*",
11
+ "app/**/*",
12
+ "core/**/*",
13
+ "test/**/*"
14
+ ]
15
+ }
package/package.json CHANGED
@@ -1,6 +1,87 @@
1
1
  {
2
2
  "name": "@seip/bluebird-js",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.1",
4
+ "description": "Performance-first Node.js API and web framework with built-in JWT auth, HTML rendering, validation, BaseModel, and multi-level caching",
5
+ "type": "module",
6
+ "main": "core/app.js",
7
+ "types": "core/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./core/index.d.ts",
11
+ "default": "./core/app.js"
12
+ },
13
+ "./core/*.js": {
14
+ "types": "./core/*.d.ts",
15
+ "default": "./core/*.js"
16
+ },
17
+ "./*": "./*"
18
+ },
19
+ "bin": {
20
+ "bluebird-js": "core/cli/init.js",
21
+ "blue-bird": "core/cli/init.js"
22
+ },
23
+ "repository": {
24
+ "type": "git",
25
+ "url": "git+https://github.com/seip25/Blue-bird.git"
26
+ },
27
+ "keywords": [
28
+ "express",
29
+ "framework",
30
+ "html",
31
+ "api",
32
+ "jwt",
33
+ "render",
34
+ "seo",
35
+ "model"
36
+ ],
37
+ "author": "Seip25",
38
+ "license": "MIT",
39
+ "bugs": {
40
+ "url": "https://github.com/seip25/Blue-bird/issues"
41
+ },
42
+ "homepage": "https://seip25.github.io/Blue-bird/",
43
+ "engines": {
44
+ "node": ">=22.18.0"
45
+ },
46
+ "scripts": {
47
+ "dev": "node --watch --env-file=.env index.js",
48
+ "start": "node --env-file=.env index.js",
49
+ "init": "bluebird-js",
50
+ "doctor": "bluebird-js doctor",
51
+ "route": "bluebird-js make:route",
52
+ "view": "bluebird-js make:view",
53
+ "model": "bluebird-js make:model",
54
+ "migrate": "bluebird-js migrate",
55
+ "seed": "bluebird-js seed",
56
+ "ecosystem": "bluebird-js make:ecosystem",
57
+ "swagger-install": "bluebird-js swagger-install",
58
+ "test": "node test/test_suite.js"
59
+ },
60
+ "publishConfig": {
61
+ "access": "public"
62
+ },
63
+ "files": [
64
+ "core",
65
+ "app",
66
+ "public",
67
+ "index.js",
68
+ "AGENTS.md",
69
+ "production.md",
70
+ ".env_example",
71
+ "jsconfig.json",
72
+ ".vscode"
73
+ ],
74
+ "dependencies": {
75
+ "express": "^5.2.1"
76
+ },
77
+ "optionalDependencies": {
78
+ "ejs": "^3.1.10",
79
+ "helmet": "^8.1.0",
80
+ "multer": "^2.0.2",
81
+ "redis": "^6.1.0",
82
+ "swagger-jsdoc": "^6.2.8",
83
+ "swagger-ui-express": "^5.0.1",
84
+ "ws": "^8.18.0"
85
+ },
86
+ "devDependencies": {}
6
87
  }
package/production.md ADDED
@@ -0,0 +1,273 @@
1
+ # Bluebird.js - Production Deployment Guide
2
+
3
+ This guide covers recommended strategies for deploying a `@seip/bluebird-js` application in production environments. Bluebird is designed to be lightweight, native-first, and unopinionated about infrastructure, allowing you to choose the deployment pattern that best fits your workflow.
4
+
5
+ ---
6
+
7
+ ## 1. Quick Start: Standard Node.js (`npm start`)
8
+
9
+ For single-instance VPS hosts, developer previews, or container runtimes, you can start the application directly using Node.js:
10
+
11
+ ```bash
12
+ npm run start
13
+ ```
14
+
15
+ This runs:
16
+ ```bash
17
+ node --env-file=.env index.js
18
+ ```
19
+
20
+ ### Production Checklist Before Starting
21
+ - Set `DEBUG=false` in `.env`.
22
+ - Ensure `JWT_SECRET` is set to a secure, random string (minimum 32 characters).
23
+ - Ensure your database path or connection credentials in `.env` are secure and isolated.
24
+
25
+ ---
26
+
27
+ ## 2. Recommended: PM2 Process Manager
28
+
29
+ PM2 provides automatic restarts on crashes, cluster mode across multi-core CPUs, log management, and system boot persistence.
30
+
31
+ ### Step 1: Generate Ecosystem Configuration
32
+
33
+ Bluebird provides a built-in CLI command to generate a production-ready `ecosystem.config.cjs`:
34
+
35
+ ```bash
36
+ npx bluebird-js make:ecosystem
37
+ ```
38
+
39
+ This command inspects your `.env` file for settings such as `TITLE`, `PM2_APP_NAME`, `PM2_INSTANCES`, and `PM2_MAX_MEMORY`, automatically configuring clustering and worker jobs found in `app/jobs/`.
40
+
41
+ ### Step 2: Start and Save Immediately
42
+
43
+ You can generate the configuration, start the application, and save the PM2 state in a single step:
44
+
45
+ ```bash
46
+ npx bluebird-js make:ecosystem --start
47
+ ```
48
+
49
+ Or execute the steps manually:
50
+
51
+ ```bash
52
+ pm2 start ecosystem.config.cjs
53
+ pm2 save
54
+ ```
55
+
56
+ ### Step 3: Configure Startup on Server Reboot
57
+
58
+ Generate and execute the systemd startup script:
59
+
60
+ ```bash
61
+ pm2 startup
62
+ ```
63
+
64
+ Follow the instruction printed by PM2 to register the startup hook with your system daemon.
65
+
66
+ ### Useful PM2 Management Commands
67
+
68
+ ```bash
69
+ pm2 status # View status of running processes
70
+ pm2 logs # Stream consolidated logs
71
+ pm2 reload all --update-env # Zero-downtime rolling reload with updated .env
72
+ pm2 restart all # Restart all instances
73
+ pm2 stop all # Stop all instances
74
+ pm2 delete all # Remove all processes from PM2
75
+ ```
76
+
77
+ ---
78
+
79
+ ## 3. Systemd Service (Alternative to PM2)
80
+
81
+ If you prefer native Linux systemd services instead of PM2:
82
+
83
+ Create `/etc/systemd/system/bluebird.service`:
84
+
85
+ ```ini
86
+ [Unit]
87
+ Description=Bluebird Application Service
88
+ After=network.target
89
+
90
+ [Service]
91
+ Type=simple
92
+ User=www-data
93
+ WorkingDirectory=/var/www/bluebird-app
94
+ ExecStart=/usr/bin/node --env-file=.env index.js
95
+ Restart=always
96
+ RestartSec=5
97
+ Environment=NODE_ENV=production
98
+ LimitNOFILE=65535
99
+
100
+ [Install]
101
+ WantedBy=multi-user.target
102
+ ```
103
+
104
+ Enable and start the service:
105
+
106
+ ```bash
107
+ sudo systemctl daemon-reload
108
+ sudo systemctl enable bluebird
109
+ sudo systemctl start bluebird
110
+ sudo systemctl status bluebird
111
+ ```
112
+
113
+ ---
114
+
115
+ ## 4. Nginx Reverse Proxy & SSL
116
+
117
+ Expose your application securely on port 80/443 using Nginx as a reverse proxy.
118
+
119
+ ### Step 1: Generate Nginx Configuration
120
+
121
+ Run the Bluebird CLI helper to generate an optimized Nginx block (defaults to your current working directory or accepts a custom project path):
122
+
123
+ ```bash
124
+ npx bluebird-js nginx:conf yourdomain.com 3000 /var/www/my-project
125
+ ```
126
+
127
+ ### Step 2: Install Configuration on VPS
128
+
129
+ Create the site configuration file:
130
+
131
+ ```bash
132
+ sudo nano /etc/nginx/sites-available/yourdomain.com
133
+ ```
134
+
135
+ Paste the generated snippet (featuring `upstream` keepalive connections, `5M` body limit, direct static delivery via `try_files`, and `@bluebird` Express fallback):
136
+
137
+ ```nginx
138
+ upstream bluebird_yourdomain_com {
139
+ server 127.0.0.1:3000;
140
+ keepalive 64;
141
+ }
142
+
143
+ server {
144
+ listen 80;
145
+ listen [::]:80;
146
+ server_name yourdomain.com;
147
+
148
+ root /var/www/my-project/public;
149
+ client_max_body_size 5M;
150
+
151
+ gzip on;
152
+ gzip_vary on;
153
+ gzip_proxied any;
154
+ gzip_comp_level 6;
155
+ gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;
156
+
157
+ location ~* /\.(env|git|svn|htaccess|DS_Store) {
158
+ deny all;
159
+ return 404;
160
+ }
161
+
162
+ location /dist/ {
163
+ try_files $uri =404;
164
+ expires 1y;
165
+ add_header Cache-Control "public, max-age=31536000, immutable";
166
+ access_log off;
167
+ }
168
+
169
+ location ~* \.(?:css|js|mjs|jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc|woff|woff2|ttf|eot|webp|avif)$ {
170
+ try_files $uri =404;
171
+ expires 30d;
172
+ add_header Cache-Control "public, max-age=2592000, immutable";
173
+ access_log off;
174
+ }
175
+
176
+ location / {
177
+ try_files $uri @bluebird;
178
+ }
179
+
180
+ location @bluebird {
181
+ proxy_pass http://bluebird_yourdomain_com;
182
+ proxy_http_version 1.1;
183
+
184
+ proxy_set_header Upgrade $http_upgrade;
185
+ proxy_set_header Connection $http_connection;
186
+
187
+ proxy_set_header Host $host;
188
+ proxy_set_header X-Real-IP $remote_addr;
189
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
190
+ proxy_set_header X-Forwarded-Proto $scheme;
191
+ proxy_set_header X-Forwarded-Host $host;
192
+ proxy_set_header X-Forwarded-Port $server_port;
193
+
194
+ proxy_connect_timeout 60s;
195
+ proxy_send_timeout 60s;
196
+ proxy_read_timeout 60s;
197
+ }
198
+ }
199
+ ```
200
+
201
+ Enable and reload Nginx:
202
+
203
+ ```bash
204
+ sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
205
+ sudo nginx -t
206
+ sudo systemctl reload nginx
207
+ ```
208
+
209
+ ### Step 3: Enable Free SSL with Let's Encrypt
210
+
211
+ ```bash
212
+ sudo certbot --nginx -d yourdomain.com
213
+ ```
214
+
215
+ ---
216
+
217
+ ## 5. Optional: Standalone Docker Deployment
218
+
219
+ If you prefer containerizing your application independently, here are minimal, production-ready standalone files you can add to your project:
220
+
221
+ ### `Dockerfile`
222
+
223
+ ```dockerfile
224
+ FROM node:22-alpine
225
+
226
+ WORKDIR /app
227
+
228
+ ENV NODE_ENV=production
229
+
230
+ COPY package*.json ./
231
+
232
+ RUN npm ci --only=production
233
+
234
+ COPY . .
235
+
236
+ EXPOSE 3000
237
+
238
+ CMD ["node", "--env-file=.env", "index.js"]
239
+ ```
240
+
241
+ ### `docker-compose.yml`
242
+
243
+ ```yaml
244
+ services:
245
+ app:
246
+ build: .
247
+ restart: unless-stopped
248
+ ports:
249
+ - "127.0.0.1:3000:3000"
250
+ env_file:
251
+ - .env
252
+ volumes:
253
+ - ./database:/app/database
254
+ - ./app/cache:/app/app/cache
255
+ - ./logs:/app/logs
256
+ ```
257
+
258
+ Run containers:
259
+
260
+ ```bash
261
+ docker compose up -d --build
262
+ ```
263
+
264
+ ---
265
+
266
+ ## 6. Cache and Scaling Recommendations
267
+
268
+ | Deployment Profile | Recommended Cache | Database Recommendation |
269
+ |---|---|---|
270
+ | **Desktop App (Electron/Tauri)** | `CACHE_MODE=memory` | SQLite (`DB_TYPE=sqlite`) |
271
+ | **Single VPS (`PM2_INSTANCES=1`)** | `CACHE_MODE=memory` or `CACHE_MODE=file` | SQLite or PostgreSQL/MySQL |
272
+ | **Multi-Core Cluster (`PM2_INSTANCES=max`)** | `CACHE_MODE=memory` (per worker) or `CACHE_MODE=redis` | PostgreSQL or MySQL |
273
+ | **Multi-Server Distributed Cluster** | `CACHE_MODE=redis` | PostgreSQL or MySQL |