Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-02-04 00:18:01 +01:00
Code Issues Projects Releases Wiki Activity

Fixed typos and broken links in the documentation

Browse Source
This commit is contained in:
Denis Dzyubenko 2018-07-12 16:15:02 +02:00 committed by Ivar Conradi Østhus
parent cd4414099a
commit 7f07d77d44
12 changed files with 50 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/activation-strategies.md
View File

@ -1,22 +1,22 @@
# Activation Strategies
It is powerful to be able to turn a feature on and off instantaneously, without redeploying the application. The next level of control comes when you are able to enable a feature for specific users or enable it for a small subset of the users. We achieve this level of control with the help of activation strategies. The simplest strategy is the “default” strategy, which basically means that the feature should be enabled to everyone.
It is powerful to be able to turn a feature on and off instantaneously, without redeploying the application. The next level of control comes when you are able to enable a feature for specific users or enable it for a small subset of the users. We achieve this level of control with the help of activation strategies. The most simple strategy is the “default” strategy, which basically means that the feature should be enabled to everyone.
The definition of an activation strategy lives in the Unleash API and can be created via the Unleash UI. The implementation of activation strategies lives in the various client implementations.
Unleash comes with a few common activation strategies. Some of them requires the client to provide the [unleash-context](./unleash-context.md), which gives necessary context for unleash.
Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](./unleash-context.md), which gives necessary context for unleash.
## default
Is the simples activation strategies and basically means "active for everyone".
It is the simplest activation strategy and basically means "active for everyone".
## userWithId
Active for users with a userId defined in the userIds-list. Typically I want to enable a new feature only for myself in production, before I enable it of everyone else. To achieve this we can use the “UserWithIdStrategy”. This strategy allows you to specify a list of specific user ids that you want to expose the new feature for. (A user id may of course be an email if that is more appropriate in your system.)
Active for users with a userId defined in the userIds-list. Typically I want to enable a new feature only for myself in production, before I enable it for everyone else. To achieve this we can use the “UserWithIdStrategy”. This strategy allows you to specify a list of user ids that you want to expose the new feature for. (A user id may of course be an email if that is more appropriate in your system.)
**Parameters**
- userIds - *List of user ids you want the feature toggle should be enabled for*
- userIds - *List of user ids you want the feature toggle be enabled for*
## gradualRolloutUserId
Gradually activate feature toggle for logged in users. Stickiness based on user id.
Gradually activates feature toggle for logged in users. Stickiness based on the user id.
This strategy guarantees that the same user gets the same experience every time,
across devices. It also guarantees that a user which is among the first 10% will
also be among the first 20% of the users. Thus we ensure that users get the same
@ -26,30 +26,30 @@ value to a number between 1 and 100 with a simple modulo operator.
![hash_and_normalise](assets/hash_and_normalise.png)
Starting from v3.x all clients should use the 32bit Murmur-hash algorithm to normalize values.
Starting from v3.x all clients should use the 32-bit [MurmurHash3](https://en.wikipedia.org/wiki/MurmurHash) algorithm to normalize values.
([issue 247](https://github.com/Unleash/unleash/issues/247))
**Parameters**
- percentage - *The percentage (0-100) you want to enable to feature toggle for.*
- groupId - *Used to define a activation groups, which allows you to correlate across feature toggles.*
- percentage - *The percentage (0-100) you want to enable the feature toggle for.*
- groupId - *Used to define an activation group, which allows you to correlate rollout across feature toggles.*
## gradualRolloutSessionId
Gradually activate feature toggle. Stickiness based on session id. It is almost
Gradually activates feature toggle. Stickiness based on session id. It is almost
identical to the `gradualRolloutUserId` strategy, with the exception that it works
on session ids. This makes it possible to target all users (not just logged in
users), guaranteeing that a user will get the same experience within a session.
**Parameters**
- percentage - *The percentage (0-100) you want to enable to feature toggle for.*
- groupId - *Used to define a activation groups, which allows you to correlate across feature toggles.*
- percentage - *The percentage (0-100) you want to enable the feature toggle for.*
- groupId - *Used to define an activation group, which allows you to correlate rollout across feature toggles.*
## gradualRolloutRandom
Randomly activate the feature toggle. No stickiness. We have found this rollout strategy
very useful in some scenarios, especially when we are enabling a feature which is not
Randomly activates the feature toggle. No stickiness. We have found this rollout strategy
very useful in some scenarios, especially when we enable a feature which is not
visible to the user. It is also the strategy we use to sample metrics and error reports.
**Parameters**
- percentage - *The percentage (0-100) you want to enable to feature toggle for.*
- percentage - *The percentage (0-100) you want to enable the feature toggle for.*
## remoteAddress
Active for remote addresses defined in the IPs list. We sometimes use this strategy to

8
docs/api/client/feature-toggles-api.md
View File

@ -12,12 +12,12 @@ from the _unleash-server_. The response returns all active feature toggles and t
current strategy configuration. A feature toggle will have _at least_ one configured strategy.
A strategy will have a `name` and `parameters` map.
> _Note:_ Clients should perfer the `strategies` property.
> _Note:_ Clients should prefer the `strategies` property.
> Legacy properties (`strategy` & `parameters`) will be kept until **version 2** of the format.
This endpoint should never return anything besides a valid *20X or 304-response*. It will also
include a `Etag`-header. The value of this header can be used by clients as the value of
the `If-None-Match`-header in the request to prevent a data transfer if the clients already
include an `Etag`-header. The value of this header can be used by clients as the value of
the `If-None-Match`-header in the request to prevent a data transfer if the client already
has the latest response locally.
**Example response:**
@ -67,7 +67,7 @@ has the latest response locally.
`GET: http://unleash.host.com/api/client/features/:featureName`
Used to fetch details about a specific featureToggle. This is mostly provded to make it easy to
Used to fetch details about a specific feature toggle. This is mainly provided to make it easy to
debug the API and should not be used by the client implementations.
> _Notice_: You will not get a version property when fetching a specific feature toggle by name.

6
docs/api/client/register-api.md
View File

@ -4,7 +4,7 @@
`POST: http://unleash.host.com/api/client/register`
Register a client instance with the unleash server. The client should send all fields specified.
Registers a client instance with the unleash server. The client should send all fields specified.
```json
{
@ -24,5 +24,5 @@ Register a client instance with the unleash server. The client should send all f
* **instanceId** - Instance id for this application (typically hostname, podId or similar)
* **sdkVersion** - Optional field that describes the sdk version (name:version)
* **strategies** - List of strategies implemented by this application
* **started** - When this client started. Should be reported as UTC time.
* **interval** - At wich interval, in milliseconds, will this client be expected to send metrics
* **started** - When this client started. Should be reported as [ISO8610](https://en.wikipedia.org/wiki/ISO_8601) time.
* **interval** - At which interval, in milliseconds, will this client be expected to send metrics

6
docs/api/index.md
View File

@ -4,11 +4,11 @@
This describes the API provided to unleash-clients.
* [Feature Toggles API](client/feature-toggles-api.md)
* [Register API](client/register-api.md)
* [Metrics API](client/metrics-api.md)
## Admin API (internal)
The interal API used by the Admin UI (unleash-frontend):
The internal API used by the Admin UI (unleash-frontend):
* [Feature Toggles API](admin/feature-toggles-api.md)
* [Strategies API](admin/strategies-api.md)
@ -16,4 +16,4 @@ The interal API used by the Admin UI (unleash-frontend):
* [Metrics API](admin/metrics-api.md)
## System API's
* [Internal Backstage API](internal-backstage-api.ms)
* [Internal Backstage API](internal-backstage-api.md)

6
docs/client-specification.md
View File

@ -102,7 +102,7 @@ strategies to work as expected the client should also allow the user to define a
the `isEnabled` call.
### Extension points
Client implementation should also provide a defined interface to make it easier for
Client implementation should also provide a defined interface to make it easier for
the user to implement their own activation strategies, and register those in the unleash client.
@ -114,14 +114,14 @@ The default poll interval should be **15 seconds**, and it should be configurabl
## Client registration
Client implementation should at initialization register with the unleash-server.
The should send a registration as specified in the [api documentation](api/metrics-api.md#client-registration).
The should send a registration as specified in the [api documentation](api/client/register-api.md).
The registration must include all fields specified.
## Metrics
Clients are expected to send metrics back to Unleash API at regular intervals. The metrics is a list
of used toggles and how many times they evaluated to *yes* or *no* in the current period.
Read more about how to send the metrics in the [metrics-api](api/metrics-api.md) documentation.
Read more about how to send the metrics in the [metrics-api](api/client/metrics-api.md) documentation.
## Backup Feature Toggles

4
docs/database-backup.md
View File

@ -1,5 +1,5 @@
# Datbase backups
When upgrading to new major version of Unleash it is advised to do a
# Database backups
When upgrading to a new major version of Unleash it is advised to do a
full database backup to ease rollback in case of failures.
1. Create a database backup:

2
docs/database-schema.md
View File

@ -1,6 +1,6 @@
# Schema
This document describes our current database schama used in PostgreSQL.
This document describes our current database schema used in PostgreSQL.
We use db-migrate to migrate (create tables, add columns etc) the database.
## Table: _migrations_

6
docs/developer-guide.md
View File

@ -1,7 +1,7 @@
# Developer Guide
## PostgreSQL
To run and develop unleash you need to have PostgreSQL databse (PostgreSQL v.9.5.x or newer) locally.
To run and develop unleash you need to have PostgreSQL database (PostgreSQL v.9.5.x or newer) locally.
### Create a local unleash databases in postgres
@ -18,7 +18,7 @@ SQL
Then set env vars:
(Optional as unleash will asume these as default values).
(Optional as unleash will assume these as default values).
```
export DATABASE_URL=postgres://unleash_user:passord@localhost:5432/unleash
@ -64,7 +64,7 @@ Use db-migrate to create new migrations file.
> npm run db-migrate -- create YOUR-MIGRATION-NAME
```
All migrations requires on `up` and one `down` method.
All migrations require one `up` and one `down` method.
Example of a typical migration:

14
docs/getting-started.md
View File

@ -2,12 +2,12 @@
## Requirements
You will need Node.js >= 8.0.0 and a __PostreSQL__ 9.3+ database instance to be able to run Unleash.
You will need Node.js >= 8.0.0 and a __PostreSQL__ 9.5+ database instance to be able to run Unleash.
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.
which includes a username and password, that have rights to migrate the database.
_Unleash_ will, at startup, check whether database migration is needed, and perform necessary migrations.
On startup _Unleash_ will perform necessary migrations if needed.
## Start Unleash
### 1. The simplest way to get started:
@ -38,18 +38,18 @@ Available unleash options includes:
- **databaseUrl** - the postgress database url to connect to. Should include username/password.
- **port** - Which port should the unleash-server bind to?
- **enableLegacyRoutes** (boolean) - allows you to turn on/off support for legacy routes to support older clients. Enabled by default.
- **serverMetrics** (boolean) - Use this option to turn of prometheus metrics.
- **serverMetrics** (boolean) - Use this option to turn 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 arguement.
- **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.
- **secret** (string) - Set this when you want to secure unleash. Used to encrypt the user session.
- **adminAuthentication** (string) - Use this when implementing cusotm admin authentication [securing-unleash](./securing-unleash.md). Legal values are:
- `none` - Will disable autentication all together
- **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.
## 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 programatically). This enables filtering of log levels and easy redirection of output streams.
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). This enables filtering of log levels and easy redirection of output streams.
### What is a logger provider?

2
docs/migration-guide.md
View File

@ -13,7 +13,7 @@ After upgrading all your clients you should consider turning off legacy routes,
### Caveat 1: Not used db-migrate to migrate the unleash database?
In FINN we used, for internal reasons, liquebase to migrate our database.
Because unleash from version 2.0 migrates the datbase internally, with db-migrate,
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 exists, so unleash
does not try to create tables that already exists.

10
docs/securing-unleash.md
View File

@ -36,11 +36,11 @@ Examples on custom authentication hooks:
- [google-auth-hook.js](https://github.com/Unleash/unleash/blob/master/examples/google-auth-hook.js)
- [basic-auth-hook.js](https://github.com/Unleash/unleash/blob/master/examples/basic-auth-hook.js)
We also have a version of Unleash deployed on heroku which uses Google Oauth 2.0:
We also have a version of Unleash deployed on Heroku which uses Google OAuth 2.0:
https://secure-unleash.herokuapp.com
## Securing the Client API
A common way to support client access is to use pre shared secrets. This can be solved by having clients send a shared key in a http header with every client requests to the Unleash API. All official Unleash clients should support this.
A common way to support client access is to use pre shared secrets. This can be solved by having clients send a shared key in a http header with every client request to the Unleash API. All official Unleash clients should support this.
In the [Java client](https://github.com/Unleash/unleash-client-java#custom-http-headers) this looks like:
@ -62,12 +62,12 @@ const sharedSecret = '12312Random';
unleash.start({
databaseUrl: 'postgres://unleash_user:passord@localhost:5432/unleash',
enableLegacyRoutes: false,
preRouterHook: (app) => {
preRouterHook: app => {
app.use('/api/client', (req, res, next) => {
if(req.headers.authorization !== sharedSecret) {
if (req.header('authorization') !== sharedSecret) {
res.sendStatus(401);
} else {
next()
next();
}
});
}

6
examples/client-auth-unleash.js
View File

@ -12,10 +12,10 @@ unleash
enableLegacyRoutes: false,
preRouterHook: app => {
app.use('/api/client', (req, res, next) => {
if (req.headers.authorization === sharedSecret) {
next();
} else {
if (req.header('authorization') !== sharedSecret) {
res.sendStatus(401);
} else {
next();
}
});
},