@seip/bluebird-js 0.0.0-stage → 0.1.0
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.
- package/.env_example +54 -0
- package/AGENTS.md +426 -0
- package/LICENSE +21 -0
- package/README.md +292 -3
- package/app/routes/api.js +50 -0
- package/app/routes/web.js +55 -0
- package/app/views/about.js +63 -0
- package/app/views/dashboard.js +147 -0
- package/app/views/index.js +80 -0
- package/app/views/layouts/main/view.js +81 -0
- package/app/views/legal/terms.html +19 -0
- package/app/views/login.js +80 -0
- package/core/app.d.ts +18 -0
- package/core/app.js +684 -0
- package/core/auth.d.ts +13 -0
- package/core/auth.js +326 -0
- package/core/cache.d.ts +17 -0
- package/core/cache.js +475 -0
- package/core/cli/doctor.js +287 -0
- package/core/cli/ecosystem.js +162 -0
- package/core/cli/init.js +779 -0
- package/core/cli/migrate.js +541 -0
- package/core/cli/model.js +66 -0
- package/core/cli/nginx.js +199 -0
- package/core/cli/route.js +121 -0
- package/core/cli/swagger.js +45 -0
- package/core/cli/view.js +96 -0
- package/core/config.d.ts +3 -0
- package/core/config.js +111 -0
- package/core/csrf.d.ts +3 -0
- package/core/csrf.js +114 -0
- package/core/database.d.ts +15 -0
- package/core/database.js +636 -0
- package/core/debug.d.ts +3 -0
- package/core/debug.js +250 -0
- package/core/hash.d.ts +3 -0
- package/core/hash.js +194 -0
- package/core/html.d.ts +42 -0
- package/core/html.js +217 -0
- package/core/index.d.ts +1176 -0
- package/core/logger.d.ts +3 -0
- package/core/logger.js +127 -0
- package/core/middleware.d.ts +3 -0
- package/core/middleware.js +28 -0
- package/core/model.d.ts +19 -0
- package/core/model.js +600 -0
- package/core/queue.d.ts +13 -0
- package/core/queue.js +172 -0
- package/core/ratelimit.d.ts +3 -0
- package/core/ratelimit.js +145 -0
- package/core/redis.d.ts +21 -0
- package/core/redis.js +230 -0
- package/core/render-cache.js +212 -0
- package/core/render.d.ts +3 -0
- package/core/render.js +320 -0
- package/core/router.d.ts +3 -0
- package/core/router.js +171 -0
- package/core/seo.d.ts +3 -0
- package/core/seo.js +106 -0
- package/core/swagger.d.ts +3 -0
- package/core/swagger.js +60 -0
- package/core/upload.d.ts +13 -0
- package/core/upload.js +102 -0
- package/core/util/colors.js +82 -0
- package/core/validate.d.ts +15 -0
- package/core/validate.js +364 -0
- package/core/view-loader.js +162 -0
- package/core/vite.d.ts +3 -0
- package/core/vite.js +145 -0
- package/core/ws.d.ts +13 -0
- package/core/ws.js +245 -0
- package/index.js +18 -0
- package/jsconfig.json +15 -0
- package/package.json +85 -5
- package/production.md +273 -0
- package/public/css/bluebird.min.css +2 -0
- package/public/images/favicon.ico +0 -0
- package/public/js/bluebird-client.js +1781 -0
- 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
package/package.json
CHANGED
|
@@ -1,6 +1,86 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@seip/bluebird-js",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
1
|
+
{
|
|
2
|
+
"name": "@seip/bluebird-js",
|
|
3
|
+
"version": "0.1.0",
|
|
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/bluebird-js.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/bluebird-js/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
|
+
],
|
|
73
|
+
"dependencies": {
|
|
74
|
+
"express": "^5.2.1"
|
|
75
|
+
},
|
|
76
|
+
"optionalDependencies": {
|
|
77
|
+
"ejs": "^3.1.10",
|
|
78
|
+
"helmet": "^8.1.0",
|
|
79
|
+
"multer": "^2.0.2",
|
|
80
|
+
"redis": "^6.1.0",
|
|
81
|
+
"swagger-jsdoc": "^6.2.8",
|
|
82
|
+
"swagger-ui-express": "^5.0.1",
|
|
83
|
+
"ws": "^8.18.0"
|
|
84
|
+
},
|
|
85
|
+
"devDependencies": {}
|
|
6
86
|
}
|
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 |
|