1 | ---
|
2 | id: getting_started
|
3 | title: Getting Started
|
4 | ---
|
5 |
|
6 | ## Requirements
|
7 |
|
8 | You will need Node.js >= 8.0.0 and a **PostgreSQL** 9.5+ database instance to be able to run Unleash.
|
9 |
|
10 | When starting Unleash you must specify a database URI (can be set as environment variable DATABASE_URL) which includes a username and password, that have rights to migrate the database.
|
11 |
|
12 | On startup _Unleash_ will perform necessary migrations if needed.
|
13 |
|
14 | ## Start Unleash
|
15 |
|
16 | ### 1. The simplest way to get started:
|
17 |
|
18 | ```bash
|
19 | $ npm install unleash-server -g
|
20 | $ unleash -d postgres://unleash_user:passord@localhost:5432/unleash -p 4242
|
21 |
|
22 | Unleash started on http://localhost:4242
|
23 | ```
|
24 |
|
25 | ### 2. Or programmatically:
|
26 |
|
27 | You can also depend on unleash
|
28 |
|
29 | ```js
|
30 | const unleash = require('unleash-server');
|
31 |
|
32 | unleash
|
33 | .start({
|
34 | databaseUrl: 'postgres://unleash_user:passord@localhost:5432/unleash',
|
35 | port: 4242,
|
36 | })
|
37 | .then(unleash => {
|
38 | console.log(
|
39 | `Unleash started on http://localhost:${unleash.app.get('port')}`,
|
40 | );
|
41 | });
|
42 | ```
|
43 |
|
44 | Available unleash options include:
|
45 |
|
46 | - **databaseUrl** - the postgres database url to connect to. Should include username/password.
|
47 | - **databaseSchema** - the postgres database schema to use. Defaults to 'public'.
|
48 | - **port** - which port the unleash-server should bind to. If port is omitted or is 0, the operating system will assign an arbitrary unused port. Will be ignored if pipe is specified.
|
49 | - **host** - which host the unleash-server should bind to. If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise.
|
50 | - **pipe** - parameter to identify IPC endpoints. See https://nodejs.org/api/net.html#net_identifying_paths_for_ipc_connections for more details
|
51 | - **enableLegacyRoutes** (boolean) - allows you to turn on/off support for legacy routes to support older clients. Enabled by default.
|
52 | - **serverMetrics** (boolean) - use this option to turn on/off prometheus metrics.
|
53 | - **preHook** (function) - this is a hook if you need to provide any middlewares to express before `unleash` adds any. Express app instance is injected as first argument.
|
54 | - **preRouterHook** (function) - use this to register custom express middlewares before the `unleash` specific routers are added. This is typically how you would register custom middlewares to handle authentication.
|
55 | - **secret** (string) - set this when you want to secure unleash. Used to encrypt the user session.
|
56 | - **adminAuthentication** (string) - use this when implementing custom admin authentication [securing-unleash](./securing-unleash.md). Possible values are:
|
57 | - `none` - will disable authentication altogether
|
58 | - `unsecure` - (default) will use simple cookie based authentication. UI will require the user to specify an email in order to use unleash.
|
59 | - `custom` - use this when you implement your own custom authentication logic.
|
60 | - **ui** (object) - Set of UI specific overrides. You may set the following keys: `headerBackground`, `environment`, `slogan`.
|
61 | - **getLogger** (function) - Used to register a [custom log provider](#How do I configure the log output).
|
62 |
|
63 | ### 3. Docker
|
64 |
|
65 | You can also use the [hosted docker image](https://hub.docker.com/r/unleashorg/unleash-server/) to start the Unleash server
|
66 |
|
67 | ```sh
|
68 | docker run -d -e DATABASE_URL=postgres://user:pass@10.200.221.11:5432/unleash unleashorg/unleash-server
|
69 | ```
|
70 |
|
71 | ## Securing Unleash
|
72 |
|
73 | Unleash also have extension points where you can integrate Unleash with your authentication provider (OAuth 2.0). Read more about [securing unleash](./securing-unleash.md).
|
74 |
|
75 | ## How do I configure the log output?
|
76 |
|
77 | By default, `unleash` uses [log4js](https://github.com/nomiddlename/log4js-node) to log important information. It is possible to swap out the logger provider (only when using Unleash programmatically). You do this by providing an implementation of the **getLogger** function as This enables filtering of log levels and easy redirection of output streams.
|
78 |
|
79 | ```javascript
|
80 | function getLogger(name) {
|
81 | // do something with the name
|
82 | return {
|
83 | debug: console.log,
|
84 | info: console.log,
|
85 | warn: console.log,
|
86 | error: console.error,
|
87 | };
|
88 | }
|
89 | ```
|
90 |
|
91 | The logger interface with its `debug`, `info`, `warn` and `error` methods expects format string support as seen in `debug` or the JavaScript `console` object. Many commonly used logging implementations cover this API, e.g., bunyan, pino or winston.
|