mirror of
https://github.com/Unleash/unleash.git
synced 2025-01-25 00:07:47 +01:00
Docs fixes (#7050)
- Fixed a typo - Updated the docs to remove a mention of v4 - Removed old v3 page
This commit is contained in:
Alvin Bryan
GitHub
parent
b2b8d94617
commit
5b8c63f748
@ -103,7 +103,7 @@ unleash.on('ready', () => {
|
|||||||
});
|
});
|
||||||
|
|
||||||
unleash.on('impression', (event) => {
|
unleash.on('impression', (event) => {
|
||||||
// Capture the event here and pass it internal data lake or analytics provider
|
// Capture the event here and pass it to internal data lake or analytics provider
|
||||||
console.log(event);
|
console.log(event);
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|||||||
@ -1,114 +0,0 @@
|
|||||||
---
|
|
||||||
title: Configuring Unleash v3
|
|
||||||
---
|
|
||||||
|
|
||||||
> This is the guide on how to configure **Unleash v3 self-hosted**. If you are using Unleash v4 you should checkout [configuring Unleash](./configuring-unleash.md)
|
|
||||||
|
|
||||||
In order to customize "anything" in Unleash you need to use [Unleash from Node.js](./getting-started.md#option-two---from-nodejs):
|
|
||||||
|
|
||||||
```js
|
|
||||||
const unleash = require('unleash-server');
|
|
||||||
|
|
||||||
const unleashOptions = {
|
|
||||||
db: {
|
|
||||||
user: 'unleash_user',
|
|
||||||
password: 'passord',
|
|
||||||
host: 'localhost',
|
|
||||||
port: 5432,
|
|
||||||
database: 'unleash',
|
|
||||||
ssl: false,
|
|
||||||
pool: {
|
|
||||||
min: 0,
|
|
||||||
max: 4,
|
|
||||||
idleTimeoutMillis: 30000,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
enableRequestLogger: true,
|
|
||||||
};
|
|
||||||
|
|
||||||
unleash.start(unleashOptions);
|
|
||||||
```
|
|
||||||
|
|
||||||
**Available Unleash options include:**
|
|
||||||
|
|
||||||
- **db** - The database configuration object taking the following properties:
|
|
||||||
- _user_ - the database username (`DATABASE_USERNAME`)
|
|
||||||
- _password_ - the database password (`DATABASE_PASSWORD`)
|
|
||||||
- _host_ - the database hostname (`DATABASE_HOST`)
|
|
||||||
- _port_ - the database port defaults to 5432 (`DATABASE_PORT`)
|
|
||||||
- _database_ - the database name to be used (`DATABASE_NAME`)
|
|
||||||
- _ssl_ - an object describing ssl options, see https://node-postgres.com/features/ssl (`DATABASE_SSL`, as a stringified json object)
|
|
||||||
- _version_ - the postgres database version. Used to connect a non-standard database. Defaults to `undefined`, which let the underlying adapter to detect the version automatically. (`DATABASE_VERSION`)
|
|
||||||
- _pool_ - an object describing pool options, see https://knexjs.org/guide/#pool. We support the following four fields:
|
|
||||||
- _min_ - minimum connections in connections pool (defaults to 0) (`DATABASE_POOL_MIN`)
|
|
||||||
- _max_ - maximum connections in connections pool (defaults to 4) (`DATABASE_POOL_MAX`)
|
|
||||||
- _idleTimeoutMillis_ - time in milliseconds a connection must be idle before being marked as a candidate for eviction (defaults to 30000) (`DATABASE_POOL_IDLE_TIMEOUT_MS`)
|
|
||||||
- _afterCreate_ - a callback for for configuring active connections, see https://knexjs.org/guide/#aftercreate. This is incompatible with the `ALLOW_NON_STANDARD_DB_DATES` environment variable, which will override this property to support non-standard Postgres date formats. If you've set your Postgres instance to use a date style other than `ISO, DMY` then you'll need to set the `ALLOW_NON_STANDARD_DB_DATES` environment variable to `true`. Setting the environment variable should be preferred over writing your own callback.
|
|
||||||
- **databaseUrl** - (_deprecated_) the postgres database url to connect to. Only used if _db_ object is not specified, and overrides the _db_ object and any environment variables that change parts of it (like `DATABASE_SSL`). Should include username/password. This value may also be set via the `DATABASE_URL` environment variable. Alternatively, if you would like to read the database url from a file, you may set the `DATABASE_URL_FILE` environment variable with the full file path. The contents of the file must be the database url exactly.
|
|
||||||
- **databaseSchema** - the postgres database schema to use. Defaults to 'public'. (`DATABASE_SCHEMA`)
|
|
||||||
- **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. This value may also be set via the `HTTP_PORT` environment variable
|
|
||||||
- **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. This value may also be set via the `HTTP_HOST` environment variable
|
|
||||||
- **pipe** - parameter to identify IPC endpoints. See https://nodejs.org/api/net.html#net_identifying_paths_for_ipc_connections for more details
|
|
||||||
- **enableLegacyRoutes** (boolean) - allows you to turn on/off support for legacy routes to support older clients. Disabled by default. Will be removed in 4.x.
|
|
||||||
- **serverMetrics** (boolean) - use this option to turn on/off prometheus metrics.
|
|
||||||
- **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.
|
|
||||||
- **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.
|
|
||||||
- **adminAuthentication** (string) - use this when implementing custom admin authentication [securing-unleash](./securing-unleash.md). Possible values are:
|
|
||||||
- `none` - will disable authentication altogether
|
|
||||||
- `unsecure` - (default) will use simple cookie based authentication. UI will require the user to specify an email in order to use unleash.
|
|
||||||
- `custom` - use this when you implement your own custom authentication logic.
|
|
||||||
- **ui** (object) - Set of UI specific overrides. You may set the following keys: `headerBackground`, `environment`, `slogan`.
|
|
||||||
- **getLogger** (function) - Used to register a [custom log provider](#how-do-i-configure-the-log-output).
|
|
||||||
- **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 [this schema defined in the source code](https://github.com/Unleash/unleash/blob/a06d2c04bb0d83d9c8c5bf2a90e9dace50f0b10a/lib/routes/admin-api/feature-schema.js#L38-L59). See an [api here](/reference/api/legacy/unleash/admin/events).
|
|
||||||
- **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`.
|
|
||||||
- **unleashUrl** (string) - Used to specify the official URL this instance of Unleash can be accessed at for an end user. Can also be configured through the environment variable `UNLEASH_URL`.
|
|
||||||
- **secureHeaders** (boolean) - use this to enable security headers (HSTS, CSP, etc) when serving Unleash from HTTPS. Can also be configured through the environment variable `SECURE_HEADERS`.
|
|
||||||
- **checkVersion** - the checkVersion object deciding where to check for latest version
|
|
||||||
- `url` - The url to check version (Defaults to `https://version.unleash.run`) - Overridable with (`UNLEASH_VERSION_URL`)
|
|
||||||
- `enable` - Whether version checking is enabled (defaults to true) - Overridable with (`CHECK_VERSION`) (if anything other than `true`, does not check)
|
|
||||||
|
|
||||||
### Disabling Auto-Start {#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 `server.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`);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Securing Unleash {#securing-unleash}
|
|
||||||
|
|
||||||
You can integrate Unleash with your authentication provider (OAuth 2.0). Read more about [securing unleash](./securing-unleash.md).
|
|
||||||
|
|
||||||
## How do I configure the log output? {#how-do-i-configure-the-log-output}
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
function getLogger(name) {
|
|
||||||
// do something with the name
|
|
||||||
return {
|
|
||||||
debug: console.log,
|
|
||||||
info: console.log,
|
|
||||||
warn: console.log,
|
|
||||||
error: console.error,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
## Database pooling connection timeouts {#database-pooling-connection-timeouts}
|
|
||||||
|
|
||||||
- Please be aware of the default values of connection pool about idle session handling.
|
|
||||||
- If you have a network component which closes idle sessions on tcp layer, please ensure, that the connection pool idleTimeoutMillis setting is lower than the timespan as the network component will close the idle connection.
|
|
||||||
@ -4,8 +4,7 @@ title: Configuring Unleash
|
|||||||
|
|
||||||
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
|
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
|
||||||
|
|
||||||
> This is the guide on how to configure **Unleash v4 self-hosted**. If you are still using Unleash v3 you should
|
> This is the guide on how to configure **Unleash v5 self-hosted**.
|
||||||
> checkout [configuring Unleash v3](./configuring-unleash-v3.md)
|
|
||||||
|
|
||||||
## Must configure
|
## Must configure
|
||||||
|
|
||||||
|
|||||||
@ -137,29 +137,3 @@ In v2 you could query feature toggles on `/api/features`. This was deprecated in
|
|||||||
Unleash no longer ships with a binary that allows you to start Unleash directly from the command line. From v4 you need to either use Unleash via docker or programmatically.
|
Unleash no longer ships with a binary that allows you to start Unleash directly from the command line. From v4 you need to either use Unleash via docker or programmatically.
|
||||||
|
|
||||||
Read more in our [getting started documentation](./getting-started.md)
|
Read more in our [getting started documentation](./getting-started.md)
|
||||||
|
|
||||||
## Upgrading from v2.x to v3.x {#upgrading-from-v2x-to-v3x}
|
|
||||||
|
|
||||||
The notable change introduced in Unleash v3.x is a strict separation of API paths for client requests and admin requests. This makes it easier to implement different authentication mechanisms for the admin UI and all unleash-clients. You can read more about [securing unleash](./securing-unleash.md).
|
|
||||||
|
|
||||||
The recommended approach is to first upgrade the `unleash-server` to v3 (which still supports v2 clients). After this is done, you should upgrade all your clients to v3.
|
|
||||||
|
|
||||||
After upgrading all your clients, you should consider turning off legacy routes, used by v2 clients. To do this, set the configuration option `enableLegacyRoutes` to `false` as described in the [page on configuring Unleash v3](./configuring-unleash-v3.md).
|
|
||||||
|
|
||||||
## Upgrading from v1.0 to v2.0 {#upgrading-from-v10-to-v20}
|
|
||||||
|
|
||||||
### Caveat 1: Not used db-migrate to migrate the Unleash database? {#caveat-1-not-used-db-migrate-to-migrate-the-unleash-database}
|
|
||||||
|
|
||||||
In FINN we used liquibase, for internal reasons, to migrate our database. Because unleash from version 2.0 migrates the database internally, with db-migrate, you need to make sure that all previous migrations for version 1 exist, so that Unleash does not try to create already existing tables.
|
|
||||||
|
|
||||||
#### How to check? {#how-to-check}
|
|
||||||
|
|
||||||
If you don't have a "migrations" table with _7 unique migrations_ you are affected by this.
|
|
||||||
|
|
||||||
#### How to fix? {#how-to-fix}
|
|
||||||
|
|
||||||
Before starting unleash version 2 you have to run the SQL located under `scripts/fix-migrations-version-1.sql`
|
|
||||||
|
|
||||||
### Caveat 2: databaseUrl (not database*Uri*) {#caveat-2-databaseurl-not-databaseuri}
|
|
||||||
|
|
||||||
Using Unleash as a library and injecting your own config? Then you should know that we changed the `databaseUri` config param name to **databaseUrl**. This is to make sure the param is aligned with the environment variable `DATABASE_URL` and avoid multiple names for the same config param.
|
|
||||||
|
|||||||
@ -759,13 +759,6 @@ module.exports = {
|
|||||||
],
|
],
|
||||||
to: '/using-unleash/deploy/configuring-unleash',
|
to: '/using-unleash/deploy/configuring-unleash',
|
||||||
},
|
},
|
||||||
{
|
|
||||||
from: [
|
|
||||||
'/reference/deploy/configuring-unleash-v3',
|
|
||||||
'/deploy/configuring_unleash_v3',
|
|
||||||
],
|
|
||||||
to: '/using-unleash/deploy/configuring-unleash-v3',
|
|
||||||
},
|
|
||||||
{
|
{
|
||||||
from: [
|
from: [
|
||||||
'/reference/deploy/database-setup',
|
'/reference/deploy/database-setup',
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user