diff --git a/docs/getting-started.md b/docs/getting-started.md index 424e36e78b..7c29573cca 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -61,6 +61,25 @@ Available unleash options include: - **eventHook** (`function(event, data)`) - If provided, this function will be invoked whenever a feature is mutated. The possible values for `event` are `'feature-created'`, `'feature-updated'`, `'feature-archived'`, `'feature-revived'`. The `data` argument contains information about the mutation. Its fields are `type` (string) - the event type (same as `event`); `createdBy` (string) - the user who performed the mutation; `data` - the contents of the change. The contents in `data` differs based on the event type; For `'feature-archived'` and `'feature-revived'`, the only field will be `name` - the name of the feature. For `'feature-created'` and `'feature-updated'` the data follows a schema defined in the code [here](https://github.com/Unleash/unleash/blob/master/lib/routes/admin-api/feature-schema.js#L38-L59). See an example [here](./guides/feautre-updates-to-slack.md). - **baseUriPath** (string) - use to register a base path for all routes on the application. For example `/my/unleash/base` (note the starting /). Defaults to `/`. Can also be configured through the environment variable `BASE_URI_PATH`. +#### Disabling Auto-Start + +If you're using unleash as part of a larger express app, you can disable the automatic server start by calling `server.create`. It takes the same options as `sevrer.start`, but will not begin listening for connections. + +```js +const unleash = require('unleash-server'); +// ... const app = express(); + +unleash + .create({ + databaseUrl: 'postgres://unleash_user:password@localhost:5432/unleash', + port: 4242, + }) + .then(result => { + app.use(result.app); + console.log(`Unleash app generated and attached to parent application`); + }); +``` + ### 3. Docker You can also use the [hosted docker image](https://hub.docker.com/r/unleashorg/unleash-server/) to start the Unleash server diff --git a/examples/express-parent-app.js b/examples/express-parent-app.js new file mode 100644 index 0000000000..bd637f1bff --- /dev/null +++ b/examples/express-parent-app.js @@ -0,0 +1,17 @@ +/* eslint-disable import/no-unresolved */ + +'use strict'; + +const express = require('express'); +const unleash = require('../lib/server-impl.js'); + +const app = express(); +unleash + .create({ + databaseUrl: 'postgres://unleash_user:passord@localhost:5432/unleash', + baseUriPath: '/unleash', + }) + .then(unl => { + app.use(unl.app); // automatically mounts to baseUriPath + app.listen(process.env.PORT); + }); diff --git a/lib/options.js b/lib/options.js index ce090e9089..f848829404 100644 --- a/lib/options.js +++ b/lib/options.js @@ -51,6 +51,7 @@ function defaultOptions() { getLogger: defaultLogProvider, customContextFields: [], disableDBMigration: false, + start: true, }; } diff --git a/lib/server-impl.js b/lib/server-impl.js index b4505469cf..f3965897f8 100644 --- a/lib/server-impl.js +++ b/lib/server-impl.js @@ -53,22 +53,26 @@ async function createApp(options) { }); } - const server = app.listen(options.listen, () => - logger.info('Unleash has started.', server.address()), - ); - return new Promise((resolve, reject) => { - server.on('listening', () => - resolve({ - app, - config, - stores, - server, - eventBus, - stateService, - }), - ); - server.on('error', reject); + const payload = { + app, + config, + stores, + eventBus, + stateService, + }; + + if (options.start) { + const server = app.listen(options.listen, () => + logger.info('Unleash has started.', server.address()), + ); + server.on('listening', () => { + resolve({ ...payload, server }); + }); + server.on('error', reject); + } else { + resolve({ ...payload }); + } }); } @@ -90,8 +94,13 @@ async function start(opts) { return createApp(options); } +async function create(opts) { + return start({ ...opts, start: false }); +} + module.exports = { start, + create, User, AuthenticationRequired, permissions, diff --git a/lib/server-impl.test.js b/lib/server-impl.test.js index 5f259f9965..98bc42a2f0 100644 --- a/lib/server-impl.test.js +++ b/lib/server-impl.test.js @@ -82,3 +82,20 @@ test('should call eventHook', async t => { eventStore.emit('feature-created', {}); t.true(called === 1); }); + +test('should auto-create server on start()', async t => { + const { server } = await serverImpl.start({ + port: 0, + getLogger, + start: true, + }); + t.false(typeof server === 'undefined'); +}); + +test('should not create a server using create()', async t => { + const { server } = await serverImpl.create({ + port: 0, + getLogger, + }); + t.true(typeof server === 'undefined'); +});