1 | cloudcms-server
|
2 | ===============
|
3 |
|
4 | A Node.js module that provides a framework and server-side functionality for Cloud CMS deployed Node.js applications. This module provides the backbone capabilities for the application server tier of Cloud CMS as hosted at cloudcms.net.
|
5 |
|
6 | For more information on Cloud CMS, please visit https://www.cloudcms.com.
|
7 |
|
8 | ## Configuration
|
9 |
|
10 | The start method takes a configuration object that enables, disables and provides settings for any underlying services.
|
11 |
|
12 | This looks like:
|
13 |
|
14 | ````
|
15 | {
|
16 | "setup": "single", // single, cluster, sticky-cluster
|
17 | "name": "Cloud CMS Application Server",
|
18 | "socketFunctions": [],
|
19 | "routeFunctions": [],
|
20 | "errorFunctions": [],
|
21 | "configureFunctions": {},
|
22 | "beforeFunctions": [],
|
23 | "afterFunctions": [],
|
24 | "reportFunctions": [],
|
25 | "dustFunctions": [],
|
26 | "initFunctions": [],
|
27 | "viewEngine": "handlebars",
|
28 | "storeEngines": {
|
29 | "app": {
|
30 | "type": "fs",
|
31 | "config": {
|
32 | "basePath": "{appBasePath}"
|
33 | }
|
34 | },
|
35 | "tmp": {
|
36 | "type": "fs",
|
37 | "config": {
|
38 | "basePath": "{tmpdirPath}/hosts/{host}",
|
39 | "hostsPath": "{tmpdirPath}/hosts"
|
40 | }
|
41 | },
|
42 | "hosts_fs": {
|
43 | "type": "fs",
|
44 | "config": {
|
45 | "basePath": "/hosts/{host}",
|
46 | "hostsPath": "/hosts"
|
47 | }
|
48 | },
|
49 | "hosts_s3": {
|
50 | "type": "s3",
|
51 | "config": {
|
52 | "accessKey": "",
|
53 | "secretKey": "",
|
54 | "bucket": "",
|
55 | "basePath": "/hosts/{host}",
|
56 | "hostsPath": "/hosts"
|
57 | }
|
58 | },
|
59 | "hosts_s3fs": {
|
60 | "type": "s3fs",
|
61 | "config": {
|
62 | "accessKey": "",
|
63 | "secretKey": "",
|
64 | "bucket": "",
|
65 | "basePath": "/hosts/{host}",
|
66 | "hostsPath": "/hosts"
|
67 | }
|
68 | }
|
69 | },
|
70 | "storeConfigurations": {
|
71 | "default": {
|
72 | "root": "app",
|
73 | "config": "app",
|
74 | "web": "app",
|
75 | "content": "tmp",
|
76 | "templates": "app",
|
77 | "modules": "app"
|
78 | },
|
79 | "oneteam": {
|
80 | "root": "hosts_fs",
|
81 | "config": "app",
|
82 | "web": "app",
|
83 | "content": "hosts_fs",
|
84 | "templates": "app",
|
85 | "modules": "hosts_fs"
|
86 | },
|
87 | "net-development": {
|
88 | "root": "hosts_fs",
|
89 | "config": "hosts_fs",
|
90 | "web": "hosts_fs",
|
91 | "content": "hosts_fs",
|
92 | "templates": "hosts_fs",
|
93 | "modules": "hosts_fs"
|
94 | },
|
95 | "net-production": {
|
96 | "root": "hosts_s3fs",
|
97 | "config": "hosts_s3fs",
|
98 | "web": "hosts_s3fs",
|
99 | "content": "hosts_s3fs",
|
100 | "templates": "hosts_s3fs",
|
101 | "modules": "hosts_s3fs"
|
102 | },
|
103 | "net-development-s3": {
|
104 | "root": "hosts_s3",
|
105 | "config": "hosts_s3",
|
106 | "web": "hosts_s3",
|
107 | "content": "hosts_s3",
|
108 | "templates": "hosts_s3"
|
109 | },
|
110 | "net-development-s3fs": {
|
111 | "root": "hosts_s3fs",
|
112 | "config": "hosts_s3fs",
|
113 | "web": "hosts_s3fs",
|
114 | "content": "hosts_s3fs",
|
115 | "templates": "hosts_s3fs",
|
116 | "modules": "hosts_s3fs"
|
117 | }
|
118 | },
|
119 | "duster": {
|
120 | "fragments": {
|
121 | "cache": true
|
122 | }
|
123 | },
|
124 | "virtualHost": {
|
125 | "enabled": false
|
126 | },
|
127 | "wcm": {
|
128 | "enabled": false,
|
129 | "cache": false
|
130 | },
|
131 | "serverTags": {
|
132 | "enabled": false
|
133 | },
|
134 | "insight": {
|
135 | "enabled": false
|
136 | },
|
137 | "perf": {
|
138 | "enabled": true
|
139 | },
|
140 | "driverConfig": {
|
141 | "enabled": true
|
142 | },
|
143 | "virtualDriver": {
|
144 | "enabled": false
|
145 | },
|
146 | "virtualContent": {
|
147 | "enabled": true
|
148 | },
|
149 | "flow": {
|
150 | "enabled": false
|
151 | },
|
152 | "form": {
|
153 | "enabled": true
|
154 | },
|
155 | "auth": {
|
156 | "enabled": true,
|
157 | "providers": {
|
158 | "facebook": {
|
159 | "enabled": false
|
160 | },
|
161 | "twitter": {
|
162 | "enabled": false
|
163 | },
|
164 | "linkedin": {
|
165 | "enabled": false
|
166 | }
|
167 | }
|
168 | },
|
169 | "notifications": {
|
170 | "enabled": false,
|
171 | "type": "sqs",
|
172 | "configuration": {
|
173 | "queue": "",
|
174 | "accessKey": "",
|
175 | "secretKey": "",
|
176 | "region": ""
|
177 | }
|
178 | },
|
179 | "broadcast": {
|
180 | "enabled": true
|
181 | },
|
182 | "local": {
|
183 | "enabled": true
|
184 | },
|
185 | "welcome": {
|
186 | "enabled": true,
|
187 | "file": "index.html"
|
188 | },
|
189 | "config": {
|
190 | "enabled": true
|
191 | },
|
192 | "cache": {
|
193 | "enabled": true
|
194 | },
|
195 | "templates": {
|
196 | "enabled": true
|
197 | },
|
198 | "modules": {
|
199 | "enabled": true
|
200 | },
|
201 | "debug": {
|
202 | "enabled": false,
|
203 | "logGlobalTimings": false
|
204 | },
|
205 | "cors": {
|
206 | "enabled": true,
|
207 | "origin": null,
|
208 | "methods": "GET, POST, PUT, DELETE, OPTIONS",
|
209 | "headers": "X-Forwarded-Host, X-Requested-With, Content-Type, Authorization, Origin, X-Requested-With, X-Prototype-Version, Cache-Control, Pragma, X-CSRF-TOKEN, X-XSRF-TOKEN",
|
210 | "credentials": false
|
211 | },
|
212 | "admin": {
|
213 | "enabled": true,
|
214 | "username": "admin",
|
215 | "password": "admin"
|
216 | },
|
217 | "bodyParsers": {
|
218 | "multipart": {
|
219 | },
|
220 | "json": {
|
221 | "limit": "100kb"
|
222 | },
|
223 | "urlencoded": {
|
224 | "extended": true
|
225 | }
|
226 | }
|
227 | }
|
228 | ````
|
229 |
|
230 | ## Environment Variables
|
231 |
|
232 | The following environment variables can be set to control the server's configuration from the container level:
|
233 |
|
234 | ### Virtual Driver Service
|
235 | The virtual driver configuration is used to connect to Cloud CMS and request gitana driver credentials based on
|
236 | the incoming domain name. These parameters override any settings provided for the <code>virtualDriver</code>
|
237 | service block:
|
238 |
|
239 | - CLOUDCMS_VIRTUAL_DRIVER_BASE_URL
|
240 | - CLOUDCMS_VIRTUAL_DRIVER_CLIENT_KEY
|
241 | - CLOUDCMS_VIRTUAL_DRIVER_CLIENT_SECRET
|
242 | - CLOUDCMS_VIRTUAL_DRIVER_AUTHGRANT_KEY
|
243 | - CLOUDCMS_VIRTUAL_DRIVER_AUTHGRANT_SECRET
|
244 |
|
245 | ### Broadcast Service
|
246 | The broadcast service provides a communication and notification facility between nodes in the application server cluster.
|
247 | The cluster is elastic and may grow and shrink in size as demand increases and decreases. The type can be either
|
248 | <code>noop</code> (disabled) or <code>redis</code>.
|
249 |
|
250 | - CLOUDCMS_BROADCAST_TYPE
|
251 | - CLOUDCMS_BROADCAST_REDIS_PORT
|
252 | - CLOUDCMS_BROADCAST_REDIS_ENDPOINT
|
253 |
|
254 | ### Cache Service
|
255 | The cache service provides a cluster-wide cache accessible from any node or process in the cluster. The type can be
|
256 | either <code>memory</code> or <code>redis</code>.
|
257 |
|
258 | - CLOUDCMS_CACHE_TYPE
|
259 | - CLOUDCMS_CACHE_REDIS_PORT
|
260 | - CLOUDCMS_CACHE_REDIS_ENDPOINT
|
261 |
|
262 | ### Hosting Modes
|
263 |
|
264 | The server supports three hosting modes: standalone, single virtual tenant, multiple virtual tenants
|
265 |
|
266 | #### Standalone
|
267 |
|
268 | By default, the server will start up in standalone hosting mode. This is intended for a standalone web application
|
269 | with a local gitana.json file. The incoming host name is considered to be irrelevant and all on-disk caching is done
|
270 | against a "local" virtual host. In essence, no matter what the host name is, the same virtual host is considered.
|
271 |
|
272 | In this mode, there is no support for virtual driver retrieval. You must supply the gitana.json locally.
|
273 |
|
274 | To change the name of the "local" virtual host name, set CLOUDCMS_STANDALONE_HOST environment variable.
|
275 | The default is "local".
|
276 |
|
277 | #### Single Virtual Tenant
|
278 |
|
279 | In single virtual tenant mode, all incoming request, no matter the host, are mapped to a single Cloud CMS tenant's
|
280 | application deployment.
|
281 |
|
282 | The virtual driver will retrieve the gitana.json for this tenant and maintain it over time. If the gitana.json
|
283 | API keys change on the server, they will be retrieved and used by the app server automatically.
|
284 |
|
285 | To use this mode, set the following:
|
286 |
|
287 | CLOUDCMS_VIRTUAL_HOST
|
288 |
|
289 | This should be set to the host of the Cloud CMS application deployment.
|
290 |
|
291 | #### Multiple Virtual Tenants
|
292 |
|
293 | In multiple virtual tenants mode, all incoming requests have their incoming hosts considered. Each host may describe
|
294 | a different Cloud CMS application deployment. For N hosts, there will be N Cloud CMS application instances. This mode
|
295 | is intended for cases where you wish to have a single application support N customers.
|
296 |
|
297 | To use this mode, set the following
|
298 |
|
299 | CLOUDCMS_VIRTUAL_HOST_DOMAIN
|
300 |
|
301 | This should be set to a suffix domain that is wildcarded against. For example, if you set it to "company.com", then
|
302 | any incoming requests for "<subdomain>.company.com" will be served. Each request will check with Cloud CMS to make
|
303 | sure it has the proper gitana.json pulled down for the Cloud CMS application deployment with that host. Each host
|
304 | maintains it's own location on disk and is served back via virtual hosting.
|
305 |
|
306 | ### Stores
|
307 | For every request, underlying persistence stores are applied that automatically configure to read and write objects
|
308 | to the correct place, either a file system or S3. Performance caching and directory paths are figured out ahead of
|
309 | time so that each virtual host works against the correct storage location.
|
310 |
|
311 | - CLOUDCMS_STORE_CONFIGURATION
|
312 | - CLOUDCMS_STORE_S3_ACCESS_KEY
|
313 | - CLOUDCMS_STORE_S3_SECRET_KEY
|
314 | - CLOUDCMS_STORE_S3_BUCKET
|
315 |
|
316 | ### GitHub
|
317 | The module supports dynamic application deployment from GitHub or BitBucket. Application code is deployed into the
|
318 | virtual hosting directories and served from there.
|
319 |
|
320 | - CLOUDCMS_NET_GITHUB_USERNAME
|
321 | - CLOUDCMS_NET_GITHUB_PASSWORD
|
322 | - CLOUDCMS_NET_BITBUCKET_USERNAME
|
323 | - CLOUDCMS_NET_BITBUCKET_PASSWORD
|
324 |
|
325 | ### Proxy
|
326 | These settings configured where the /proxy endpoint points to be default.
|
327 |
|
328 | GITANA_PROXY_HOST
|
329 | GITANA_PROXY_PORT
|
330 | GITANA_PROXY_SCHEME
|
331 |
|
332 |
|
333 | ### Runtime
|
334 |
|
335 | The module supports dynamic switching of the branch being served from. It also allows for the runtime cache buster
|
336 | value to be migrated at any time to allow for cache regeneration.
|
337 |
|
338 | The following environment variables can be used to set up the initial state:
|
339 |
|
340 | CLOUDCMS_RUNTIME_CB
|
341 | CLOUDCMS_RUNTIME_RELEASE_ID
|
342 | CLOUDCMS_RUNTIME_BRANCH_ID
|
343 |
|
344 | A runtime.json file is written into each virtual host's content directory. It can be adjusted at runtime via a
|
345 | POST call to:
|
346 |
|
347 | /_runtime/migrate
|
348 |
|
349 | And the JSON payload should be:
|
350 |
|
351 | {
|
352 | "branchId": "<newBranchId>",
|
353 | "releaseId": "<newReleaseId>",
|
354 | "cb": "<newCacheBusterValue>"
|
355 | }
|
356 |
|
357 | Only `branchId` is truly required. If `cb` is specified, it will be used, otherwise a new ID will be auto-generated.
|
358 |
|
359 |
|
360 | ### Other Environment Variables
|
361 |
|
362 | The following environments are computed automatically and available to services:
|
363 |
|
364 | - CLOUDCMS_APPSERVER_MODE: either 'development' or 'production', if not specified, derives from NODE_ENV
|
365 | - CLOUDCMS_APPSERVER_BASE_PATH: the startup location of the node process, applicable when running locally
|
366 | - CLOUDCMS_APPSERVER_PACKAGE_NAME: the name of the module currently beingrun (from package.json)
|
367 | - CLOUDCMS_APPSERVER_PACKAGE_VERSION: the version of the module currently being run (from package.json)
|
368 | - CLOUDCMS_APPSERVER_TIMESTAMP: the timestamp of server startup
|
369 |
|
370 |
|
371 |
|
372 |
|
373 | # node switches
|
374 | Examples of Node switches:
|
375 |
|
376 | node --max_old_space_size=3000 --prof nodemem.js --trace_incremental_marking=true --incremental_marking_steps=false
|
377 |
|
378 | node --max_old_space_size=3000 --max_new_space_size=3000 --max_executable_size=1000 --gc_global --prof nodemem.js --noincremental_marking --nolazy_sweeping --never_compact --gc_global --gc_interval=100000000
|
379 |
|
380 |
|
381 | # admin mode
|
382 | Administration API functions are available under /_admin.
|
383 | These can be enabled or disabled via the "admin" config block.
|
384 |
|
385 | If a "username" and "password" is provided in this config block, it will be asserted via basic configuration ahead of
|
386 | permitted access to the admin functions.
|
387 |
|
388 | Admin functions include
|
389 |
|
390 | /_admin/cache/invalidate
|
391 |
|
392 | This invalidates the full cache. Or you can invalidate individual nodes:
|
393 |
|
394 | /_admin/cache/invalidate?ref=node://{platformId}/{repositoryId}/{branchId}/{nodeId}
|
395 |
|
396 | Where "ref" is a standard node reference.
|
397 |
|
398 |
|
399 |
|
\ | No newline at end of file |