diff --git a/docs/advanced/api_access.md b/docs/advanced/api_access.md new file mode 100644 index 0000000000..cdfbf2808c --- /dev/null +++ b/docs/advanced/api_access.md @@ -0,0 +1,39 @@ +--- +id: api_access +title: API Access +--- + +> **Enterprise feature** +> +> Programmatic access to the Unleash API s only available with the Unleash Enterprise offering and is not part of Unleash Open-Source. + +It is possible to integrate directly with the Admin API. In this guide we will explain all the steps to set it up. + +## Step 1: Create API token + +You will need access tokens with admin privileges to be allowed to connect to the Admin Unleash-API. You can create these tokens in the “Instance Admin” as part of the “API secrets” section. + +Please note that it may take up to 60 seconds for the new key to propagate to all Unleash-hosted instances. + +> If you need an API token to use in a client SDK you should create a "client token" as these have less access. + +![Create token](../assets/create_token.png) + +## Step 2: Use Admin API + +Now that you have an access token with admin privileges we can use that to perform changes in our Unleash-hosted instance. + +In the example below we will use the [Unleash Admin API](../api/admin/features) to enable the “Demo” feature toggle sing curl. + +```sh +curl -X POST -H "Authorization: admintoken" +https://app.unleash-hosted.com/demo/api/admin/features/Demo/toggle/on +``` + +**Great success!** We have now enabled the feature toggle. We can also verify that it was actually changed by the API user by navigating to the history (audit log) for this feature toggle. + +![Create token](../assets/api_access_history.png) + +## API overview + +You can find the full documentation on everything the Unleash API supports in the [Unleash API documentation](../api/admin/features). diff --git a/docs/advanced/archived-toggles.md b/docs/advanced/archived-toggles.md new file mode 100644 index 0000000000..181f07be29 --- /dev/null +++ b/docs/advanced/archived-toggles.md @@ -0,0 +1,6 @@ +--- +id: archived_toggles +title: Archived toggles +--- + +Archived toggles diff --git a/docs/advanced/audit-log.md b/docs/advanced/audit-log.md new file mode 100644 index 0000000000..cb8d03aa37 --- /dev/null +++ b/docs/advanced/audit-log.md @@ -0,0 +1,18 @@ +--- +id: audit_log +title: The audit log +--- + +When something is not working as expected it is important to be able to track what changed when, and who performed the change. + +## Audit log per feature toggle + +Unleash comes with a audit log, available on a feature toggle level. You access the audit log via the “history” tab in the feature toggle view. + +![Audit log](../assets/unleash-toggle-history.png) + +## Global Audit Log + +Unleash also keeps an audit log across all toggles and activation strategies, tracking all changes. You access the global audit log via the “Event history”, which you can find in the drawer menu. + +![Global audit log](../assets/global_audit_log.png) \ No newline at end of file diff --git a/docs/guides/custom-activation-strategy.md b/docs/advanced/custom-activation-strategy.md similarity index 100% rename from docs/guides/custom-activation-strategy.md rename to docs/advanced/custom-activation-strategy.md diff --git a/docs/feature-toggle-types.md b/docs/advanced/feature-toggle-types.md similarity index 100% rename from docs/feature-toggle-types.md rename to docs/advanced/feature-toggle-types.md diff --git a/docs/feature-toggle-variants.md b/docs/advanced/feature-toggle-variants.md similarity index 100% rename from docs/feature-toggle-variants.md rename to docs/advanced/feature-toggle-variants.md diff --git a/docs/advanced/strategy-constraints.md b/docs/advanced/strategy-constraints.md new file mode 100644 index 0000000000..d0c42e0e96 --- /dev/null +++ b/docs/advanced/strategy-constraints.md @@ -0,0 +1,52 @@ +--- +id: strategy_constraints +title: Strategy Constraints +--- + +> **Enterprise feature** +> +> Strategy constraints is only available with the Unleash-hosted offering and is not part of Unleash Open-Source. + +Strategy constraints allow you to set pre-conditions on activation strategies that needs to be satisfied for the activation strategies to take effect. + +## Constrain on a specific environment + +The most common use case for strategy constraints is that you want an activation strategy to only take effect in a specific environment. For example you could enable the feature for everyone in development, while you only expose the new feature to a few percentage of users in production. + +![Strategy constraints](../assets/strategy-constraints.png) + +## Constrain on custom context fields + +It is also possible to constrain a activation strategy configuration on custom context fields. A common use case is a multi-tenant service where you want to control roll-out on a tenant identifier. This allows you to decide which customer should get access to your new feature. + +![Custom constraints](../assets/custom-constraints.png) + +## Define your own custom fields + +> Starting with Unleash-enterprise version 3.2.28 customers can define their custom context fields via the user interface. + +You can also define your own custom context fields that you can use together with strategy constraints. We have seen customers use multiple variants of custom context fields to control their feature roll-out: + +- region +- country +- customerType +- tenantId + +Combining strategy constraints with the “flexibleRollout” allows you to do gradual roll-out to a specific segment of your user base. + +### Step 1: Navigate to “Context Fields“ +Locate “context fields in the menu + +![Context fields](../assets/context-fields.png) + +### Step 2: Define new context field + +Next you can define your new context field. The minimum requirement is to give it a unique *name*. In addition you can give it a description and define the legal values. + +![New context fields](../assets/new_context_field.png) + +#### What is “legal values”? + +Legal values defines all possible values for the context field. this will be used in Unleash Admin UI to guide users when working with context fields to make sure they only use legal values. + +![New context fields](../assets/constraints_legal_values.png) diff --git a/docs/tags.md b/docs/advanced/tags.md similarity index 96% rename from docs/tags.md rename to docs/advanced/tags.md index c547288e2b..0ab67372da 100644 --- a/docs/tags.md +++ b/docs/advanced/tags.md @@ -3,7 +3,7 @@ id: tags title: Tagging Features --- -> This feature was introduced in Unleash vx.y.z +> This feature was introduced in Unleash 3.11.0 Do you want to filter your features to avoid having to see all features belonging to other teams than your own? Do you want to write a plugin that only gets notified about changes to features that your plugin knows how to handle? diff --git a/docs/assets/The-unleash-proxy.png b/docs/assets/The-unleash-proxy.png new file mode 100644 index 0000000000..1fbb02d09f Binary files /dev/null and b/docs/assets/The-unleash-proxy.png differ diff --git a/docs/assets/api_access_history.png b/docs/assets/api_access_history.png new file mode 100644 index 0000000000..84c7ec5ebf Binary files /dev/null and b/docs/assets/api_access_history.png differ diff --git a/docs/assets/constraints_legal_values.png b/docs/assets/constraints_legal_values.png new file mode 100644 index 0000000000..75a10f5448 Binary files /dev/null and b/docs/assets/constraints_legal_values.png differ diff --git a/docs/assets/context-fields.png b/docs/assets/context-fields.png new file mode 100644 index 0000000000..63cae45b1f Binary files /dev/null and b/docs/assets/context-fields.png differ diff --git a/docs/assets/create_project1.png b/docs/assets/create_project1.png new file mode 100644 index 0000000000..cd90998456 Binary files /dev/null and b/docs/assets/create_project1.png differ diff --git a/docs/assets/create_project2.png b/docs/assets/create_project2.png new file mode 100644 index 0000000000..c18f70399a Binary files /dev/null and b/docs/assets/create_project2.png differ diff --git a/docs/assets/create_project3.png b/docs/assets/create_project3.png new file mode 100644 index 0000000000..405f3f6fb9 Binary files /dev/null and b/docs/assets/create_project3.png differ diff --git a/docs/assets/create_project4.png b/docs/assets/create_project4.png new file mode 100644 index 0000000000..17c28e1753 Binary files /dev/null and b/docs/assets/create_project4.png differ diff --git a/docs/assets/create_toggle_1.png b/docs/assets/create_toggle_1.png new file mode 100644 index 0000000000..2e39b5096c Binary files /dev/null and b/docs/assets/create_toggle_1.png differ diff --git a/docs/assets/create_toggle_2.png b/docs/assets/create_toggle_2.png new file mode 100644 index 0000000000..b492fb86b0 Binary files /dev/null and b/docs/assets/create_toggle_2.png differ diff --git a/docs/assets/create_toggle_3.png b/docs/assets/create_toggle_3.png new file mode 100644 index 0000000000..8d7d14a11e Binary files /dev/null and b/docs/assets/create_toggle_3.png differ diff --git a/docs/assets/create_token.png b/docs/assets/create_token.png new file mode 100644 index 0000000000..dbb4fc22a4 Binary files /dev/null and b/docs/assets/create_token.png differ diff --git a/docs/assets/custom-constraints.png b/docs/assets/custom-constraints.png new file mode 100644 index 0000000000..edcac6f34a Binary files /dev/null and b/docs/assets/custom-constraints.png differ diff --git a/docs/assets/default_activation_strategy.png b/docs/assets/default_activation_strategy.png new file mode 100644 index 0000000000..7b536bedc5 Binary files /dev/null and b/docs/assets/default_activation_strategy.png differ diff --git a/docs/assets/feature_toggles_menu.png b/docs/assets/feature_toggles_menu.png new file mode 100644 index 0000000000..a20619d0fb Binary files /dev/null and b/docs/assets/feature_toggles_menu.png differ diff --git a/docs/assets/ft_create_assign_project.png b/docs/assets/ft_create_assign_project.png new file mode 100644 index 0000000000..054be9b760 Binary files /dev/null and b/docs/assets/ft_create_assign_project.png differ diff --git a/docs/assets/ft_create_chose_project.png b/docs/assets/ft_create_chose_project.png new file mode 100644 index 0000000000..bc55a07812 Binary files /dev/null and b/docs/assets/ft_create_chose_project.png differ diff --git a/docs/assets/ft_filter_on_project.png b/docs/assets/ft_filter_on_project.png new file mode 100644 index 0000000000..52079ed649 Binary files /dev/null and b/docs/assets/ft_filter_on_project.png differ diff --git a/docs/assets/ft_project_filter.png b/docs/assets/ft_project_filter.png new file mode 100644 index 0000000000..57355ae2d3 Binary files /dev/null and b/docs/assets/ft_project_filter.png differ diff --git a/docs/assets/global_audit_log.png b/docs/assets/global_audit_log.png new file mode 100644 index 0000000000..312d6303e2 Binary files /dev/null and b/docs/assets/global_audit_log.png differ diff --git a/docs/assets/instance_admin_sdk.png b/docs/assets/instance_admin_sdk.png new file mode 100644 index 0000000000..6b77260870 Binary files /dev/null and b/docs/assets/instance_admin_sdk.png differ diff --git a/docs/assets/multiple_activation_strategies.png b/docs/assets/multiple_activation_strategies.png new file mode 100644 index 0000000000..3663b70df3 Binary files /dev/null and b/docs/assets/multiple_activation_strategies.png differ diff --git a/docs/assets/new_context_field.png b/docs/assets/new_context_field.png new file mode 100644 index 0000000000..392d4a9ae7 Binary files /dev/null and b/docs/assets/new_context_field.png differ diff --git a/docs/assets/project_add.png b/docs/assets/project_add.png new file mode 100644 index 0000000000..c8514a8e78 Binary files /dev/null and b/docs/assets/project_add.png differ diff --git a/docs/assets/project_concept.png b/docs/assets/project_concept.png new file mode 100644 index 0000000000..e70f0406ae Binary files /dev/null and b/docs/assets/project_concept.png differ diff --git a/docs/assets/project_configure.png b/docs/assets/project_configure.png new file mode 100644 index 0000000000..8c496d2562 Binary files /dev/null and b/docs/assets/project_configure.png differ diff --git a/docs/assets/project_delete.png b/docs/assets/project_delete.png new file mode 100644 index 0000000000..d2ab3bd785 Binary files /dev/null and b/docs/assets/project_delete.png differ diff --git a/docs/assets/project_main_menu.png b/docs/assets/project_main_menu.png new file mode 100644 index 0000000000..81471fb16e Binary files /dev/null and b/docs/assets/project_main_menu.png differ diff --git a/docs/assets/project_menu_item.png b/docs/assets/project_menu_item.png new file mode 100644 index 0000000000..38a0df1c99 Binary files /dev/null and b/docs/assets/project_menu_item.png differ diff --git a/docs/assets/strategy-constraints.png b/docs/assets/strategy-constraints.png new file mode 100644 index 0000000000..654e498162 Binary files /dev/null and b/docs/assets/strategy-constraints.png differ diff --git a/docs/assets/unleash-toggle-history.png b/docs/assets/unleash-toggle-history.png new file mode 100644 index 0000000000..8409100b22 Binary files /dev/null and b/docs/assets/unleash-toggle-history.png differ diff --git a/docs/assets/userWithId.png b/docs/assets/userWithId.png new file mode 100644 index 0000000000..33e4ef08d3 Binary files /dev/null and b/docs/assets/userWithId.png differ diff --git a/docs/assets/userWithId_activation_strategy.png b/docs/assets/userWithId_activation_strategy.png new file mode 100644 index 0000000000..2b1627b9fb Binary files /dev/null and b/docs/assets/userWithId_activation_strategy.png differ diff --git a/docs/client_sdk.md b/docs/client_sdk.md new file mode 100644 index 0000000000..085f12b902 --- /dev/null +++ b/docs/client_sdk.md @@ -0,0 +1,3 @@ +Please see /docs/user_guide/client_sdk + + diff --git a/docs/configuring-unleash.md b/docs/deploy/configuring-unleash.md similarity index 98% rename from docs/configuring-unleash.md rename to docs/deploy/configuring-unleash.md index 0402375818..1d6db4ee56 100644 --- a/docs/configuring-unleash.md +++ b/docs/deploy/configuring-unleash.md @@ -57,7 +57,7 @@ unleash.start(unleashOptions); - `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 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/feature-updates-to-slack.md). +- **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 [api here](/docs/api/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`. diff --git a/docs/database-backup.md b/docs/deploy/database-backup.md similarity index 100% rename from docs/database-backup.md rename to docs/deploy/database-backup.md diff --git a/docs/deploy/getting-started.md b/docs/deploy/getting-started.md new file mode 100644 index 0000000000..3b2b79e3e1 --- /dev/null +++ b/docs/deploy/getting-started.md @@ -0,0 +1,110 @@ +--- +id: getting_started +title: Getting Started +--- + +## Requirements + +You will need: + +- [Node.js](https://nodejs.org/en/download/) (version 12 or later) +- [PostgreSQL](https://www.postgresql.org/download/) (version 10 or later) +- [Create an unleash user and database](/docs/developer_guide). + +## Start Unleash server + +Whichever option you choose to start Unleash, you must specify a database URI (it can be set in the environment variable DATABASE_URL). + +Once the server has started, you will see the message: + +```sh +Unleash started on http://localhost:4242 +``` + +### Option one - from a terminal/bash shell + +```sh +npm install unleash-server -g +unleash -d postgres://unleash_user:password@localhost:5432/unleash -p 4242 +``` + +### Option two - from Node.js + +1. Create a new folder/directory on your development computer. +2. From a terminal/bash shell, install the dependencies: + + ```sh + npm init + npm install unleash-server --save + ``` + +3. Create a file called _server.js_, paste the following into it and save. + + ```js + const unleash = require('unleash-server'); + + unleash + .start({ + databaseUrl: 'postgres://unleash_user:password@localhost:5432/unleash', + port: 4242, + }) + .then(unleash => { + console.log( + `Unleash started on http://localhost:${unleash.app.get('port')}`, + ); + }); + ``` + +4. Run _server.js_: + ```sh + node server.js + ``` + +### Option three - use Docker + +[View the image on dockerhub](https://hub.docker.com/r/unleashorg/unleash-server/) + +#### Docker-compose + +1. Clone the [unleash-docker](https://github.com/Unleash/unleash-docker) repository. +2. Run `docker-compose build` in repository root folder. +3. Run `docker-compose up` in repository root folder. + +#### Manually + +1. Create a network by running `docker create network unleash` +2. Run + +```sh +docker run -e POSTGRES_PASSWORD={INSERT_PASSWORD} -e POSTGRES_USER={INSERT_USER} -e POSTGRES_DB=unleash --network unleash postgres + +docker run -p 4242:4242 --network unleash -e DATABASE_URL=postgres://{INSERT_USER}:{INSERT_PASSWORD}@postgres:5432/unleash unleashorg/unleash-server +``` + +## Test your server and create a sample API call + +Once the Unleash server has started, go to [localhost:4242](http://localhost:4242) in your browser. If you see a list of example feature toggles, try modifying one of them with [curl](https://curl.se/) from a terminal/bash shell: + +``` +curl --location --request PUT 'http://localhost:4242/api/admin/features/Feature.A' --header 'Content-Type: application/json' --data-raw '{\ + "name": "Feature.A",\ + "description": "Dolor sit amet.",\ + "type": "release",\ + "enabled": false,\ + "stale": false,\ + "strategies": [\ + {\ + "name": "default",\ + "parameters": {}\ + }\ + ]\ +}'\ +``` + +## Version check + +- Unleash checks that it uses the latest version by making a call to https://version.unleash.run. + - This is a cloud function storing instance id to our database for statistics. +- This request includes a unique instance id for your server. +- If you do not wish to check for upgrades define the environment variable `CHECK_VERSION` to anything else other than `true` before starting, and Unleash won't make any calls + - `export CHECK_VERSION=false` diff --git a/docs/guides/google-auth-hook.md b/docs/deploy/google-auth-hook.md similarity index 100% rename from docs/guides/google-auth-hook.md rename to docs/deploy/google-auth-hook.md diff --git a/docs/import-export.md b/docs/deploy/import-export.md similarity index 100% rename from docs/import-export.md rename to docs/deploy/import-export.md diff --git a/docs/migration-guide.md b/docs/deploy/migration-guide.md similarity index 100% rename from docs/migration-guide.md rename to docs/deploy/migration-guide.md diff --git a/docs/securing-unleash.md b/docs/deploy/securing-unleash.md similarity index 100% rename from docs/securing-unleash.md rename to docs/deploy/securing-unleash.md diff --git a/docs/dev/version-4.md b/docs/dev/version-4.md deleted file mode 100644 index 4608bda1c1..0000000000 --- a/docs/dev/version-4.md +++ /dev/null @@ -1,10 +0,0 @@ -# Version 4 specifications - -Here we document features planned for Unleash version 4 and progress for each client SDK. Client SDKs should be able to introduce all features as a minor rev 3. release, and should switch to a version 4.x revision when all features are supported. This makes it easier for the Users to navigate supported features in respecitve clients. - -| Feature | Node.js | Java | Python | Ruby | Go | .Net | Client Specifications | -| --- | --- | --- | --- | --- | --- | --- | --- | -| Static context fields (#442) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | | | -| Strategy constraints (#442) | :fire: | :fire: | | | | | | -| Flexible rollout strategy (#442) | :fire: | :fire: | | | | | | -| Variant support ([docs](../feature-toggle-variants.md)) | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | | | :heavy_check_mark: | diff --git a/docs/integrations/integrations.md b/docs/integrations/integrations.md new file mode 100644 index 0000000000..16ea28fc61 --- /dev/null +++ b/docs/integrations/integrations.md @@ -0,0 +1,9 @@ +--- +id: integrations +title: Integrations and plugins +--- + +Available integrations with Unleash + +- [Vue plugin](https://github.com/crishellco/vue-unleash) +- [Quarkus](https://github.com/quarkiverse/quarkus-unleash) diff --git a/docs/sdks/dot_net.md b/docs/sdks/dot_net.md new file mode 100644 index 0000000000..57bda5d82b --- /dev/null +++ b/docs/sdks/dot_net.md @@ -0,0 +1,87 @@ +--- +id: dot_net_sdk +title: .net SDK +--- + +In this guide we explain how to use feature toggles in a .NET application using Unleash-hosted. We will be using the open source Unleash [.net Client SDK](https://github.com/Unleash/unleash-client-dotnet). + +> **Important details** +> +>Make sure you have the following details available: +> +>- **API URL** – Where you should connect your client SDK +>- **API Secret** – Your API secret required to connect to your instance. +>You can find this information in your “Instance admin” available in your Unleash management UI. + +## Step 1: Install client SDK + +First we must add Unleash Client SDK as a dependency to your project. Below is an example of how you would add it via the .Net cli. Please see [NuGet](https://www.nuget.org/packages/Unleash.Client/) for other alternatives. + +```sh +dotnet add package unleash.client +``` + +## Step 2: Create a new Unleash Instance + +Next we must initialize a new instance of the Unleash Client. + +```csharp +var settings = new UnleashSettings() +{ + AppName = "dot-net-client", + Environment = "local", + UnleashApi = new Uri("API URL"), + CustomHttpHeaders = new Dictionary() + { + {"Authorization","API secret" } + } +}; + +IUnleash unleash = new DefaultUnleash(settings); +``` + +In your app you typically just want one instance of Unleash, and inject that where you need it. + +You should change the URL and the Authorization header (API secret) with the correct values for your instance, which you may locate under “Instance admin” in the menu. + +## Step 3: Use the feature toggle + +Now that we have initialized the client SDK we can start using feature toggles defined in Unleash in our application. To achieve this we have the “isEnabled” method available, which will allow us to check the value of a feature toggle. This method will return true or false based on whether the feature should be enabled or disabled for the current request. + +```csharp +if (unleash.IsEnabled("Demo")) +{ + //do some magic +} +else +{ + //do old boring stuff +} +``` + +Pleas note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the *SynchronousInitialization* option to block the client until it has successfully synced with the server. + +Read more about the [Unleash architecture](https://www.unleash-hosted.com/articles/our-unique-architecture) to learn how it works in more details + +## Step 4: Provide Unleash Context + +It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the activation strategies, which are implemented in the client SDK. + +The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context. + +**a) As argument to the isEnabled call** + +The simplest way to provide the Unleash Context is as part of the “isEnabled” call: + +```csharp +var context = new UnleashContext +{ + UserId = "61" +}; + +unleash.IsEnabled("someToggle", context); +``` + +b) Via a UnleashContextProvider + +This is a bit more advanced approach, where you configure a unleash-context provider. By doing this you do not have rebuild or pass the unleash-context object to every place you are calling unleash.IsEnabled. You can read more, and get [examples about this option on GitHub](https://github.com/Unleash/unleash-client-dotnet#unleashcontextprovider). diff --git a/docs/sdks/go.md b/docs/sdks/go.md new file mode 100644 index 0000000000..7f9f3a38ff --- /dev/null +++ b/docs/sdks/go.md @@ -0,0 +1,20 @@ +--- +id: go_sdk +title: GO SDK +--- + + +```golang +import ( + "github.com/Unleash/unleash-client-go/v3" +) + +func init() { + unleash.Initialize( + unleash.WithAppName("my-node-app"), + unleash.WithUrl(""), + unleash.WithCustomHeaders(http.Header{"Authorization": {""}}), + ) +} +``` +Read more at [github.com/Unleash/unleash-client-go](https://github.com/Unleash/unleash-client-go) diff --git a/docs/sdks/java.md b/docs/sdks/java.md new file mode 100644 index 0000000000..09735b4c4e --- /dev/null +++ b/docs/sdks/java.md @@ -0,0 +1,104 @@ +--- +id: java_sdk +title: Java SDK +--- + +In this guide we explain how to use feature toggles in a Java application using Unleash-hosted. We will be using the open source Unleash [Java Client SDK](https://github.com/Unleash/unleash-client-java). + +> **Important details** +> +>Make sure you have the following details available: +> +>- **API URL** – Where you should connect your client SDK +>- **API Secret** – Your API secret required to connect to your instance. +>You can find this information in your “Instance admin” available in your Unleash management UI. + + +## Step 1: Install client SDK + +First we must add Unleash Client SDK as a dependency to your project. Below is an example of how you would add it to your pom.xml in Java: + +```xml + + no.finn.unleash + unleash-client-java + Latest version here + +``` + +## Step 2: Create a new Unleash Instance + +Next must must initialize a new instance of the Unleash Client. + +```java +UnleashConfig unleashConfig = UnleashConfig.builder() + .appName("my.java-app") + .instanceId("your-instance-1") + .environment(System.getenv("APP_ENV")) + .unleashAPI("API URL") + .customHttpHeader("Authorization", "API Secret") + .build(); + +Unleash unleash = new DefaultUnleash(config); +``` + +In your app you typically just want one instance of Unleash, and inject that where you need it. You will typically use a dependency injection frameworks such as Spring or Guice to manage this. + +You should change the URL and the Authorization header (API secret) with the correct values for your instance, which you may locate under “Instance admin” in the menu. + + + +## Step 3: Use the feature toggle + +Now that we have initialized the client SDK we can start using feature toggles defined in Unleash in our application. To achieve this we have the “isEnabled” method available, which will allow us to check the value of a feature toggle. This method will return **true** or **false** based on whether the feature should be enabled or disabled for the current request. + +```java +if(unleash.isEnabled("AwesomeFeature")) { + //do some magic +} else { + //do old boring stuff +} +``` + +Pleas note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the *synchronousFetchOnInitialisation* option to block the client until it has successfully synced with the server. + +Read more about the [Unleash architecture](https://www.unleash-hosted.com/articles/our-unique-architecture) to learn how it works in more details + +## Step 4: Provide Unleash Context + +It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/control_rollout), which are implemented in the client SDK. + +The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context. + +**a) As argument to the isEnabled call** + +The simplest way to provide the Unleash Context is as part of the “isEnabled” call: + +```java +UnleashContext context = UnleashContext.builder() + .userId("user@mail.com").build(); + +unleash.isEnabled("someToggle", context); +``` + +**b) Via a UnleashContextProvider** + +This is a bit more advanced approach, where you configure a unleash-context provider. By doing this you do not have rebuild or pass the unleash-context object to every place you are calling unleash.isEnabled. + +The provider typically binds the context to the same thread as the request. If you are using Spring the UnleashContextProvider will typically be a ‘request scoped’ bean. + +UnleashContextProvider contextProvider = new MyAwesomeContextProvider(); + +```java +UnleashConfig config = new UnleashConfig.Builder() + .appName("java-test") + .instanceId("instance x") + .unleashAPI("http://unleash.herokuapp.com/api/") + .unleashContextProvider(contextProvider) + .build(); + +Unleash unleash = new DefaultUnleash(config); + +// Anywhere in the code unleash will get the unleash context from your registered provider. +unleash.isEnabled("someToggle"); +``` diff --git a/docs/sdks/node.md b/docs/sdks/node.md new file mode 100644 index 0000000000..ee6881afb5 --- /dev/null +++ b/docs/sdks/node.md @@ -0,0 +1,78 @@ +--- +id: node_sdk +title: Node SDK +--- + +In this guide we explain how to use feature toggles in a Node application using Unleash-hosted. We will be using the open source Unleash [Node.js Client SDK](https://github.com/Unleash/unleash-client-node). + +> **Important details** +> +>Make sure your have the following details available: +> +>- **API URL** – Where you should connect your client SDK +>- **API Secret** – Your API secret required to connect to your instance. +>You can find this information in your “Instance admin” available in your Unleash management UI. + +## Step 1: Install client SDK + +First we must install Node.js dependency: + +```sh +npm install unleash-client --save +``` + +## Step 2: Initialize client SDK + +Next we must initialize the client SDK in the application: + +```js +const unleash = require('unleash-client'); + +unleash.initialize({ + url: 'https://YOUR-API-URL', + appName: 'my-node-name', + environment: process.env.APP_ENV, + customHeaders: {'Authorization': 'SOME-SECRET'} +}); +``` + +The example code above will initialize the client SDK, and connect to the Unleash-hosted demo instance. It also uses the API token for the demo instance. You should change the URL and the Authorization header (API token) with the correct values for your instance, which you may locate under “Instance admin” in the menu. + +Please also pay attention to the “environment” option. Setting this will allow you to use [strategy constraints](../user_guide/strategy-constraints) which enables different roll-out strategies per environment. + + + +## Step 3: Use the feature toggle + +Now that we have initialized the client SDK in our application we can start using feature toggles defined in Unleash in our application. To achieve this we have the “isEnabled” method available, which will allow us to check the value of a feature toggle. This method will return **true** or **false** based on whether the feature should be enabled or disabled for the current request. + +```js +setInterval(() => { + if(unleash.isEnabled('DemoToggle')) { + console.log('Toggle enabled'); + } else { + console.log('Toggle disabled'); + } +}, 1000); +``` + +Please note that in the above example we put the isEnabled-evaluation inside the setInterval method. This is required in the small example to make sure that the feature toggle is not evaluated, and application exits, before the client SDK have been able to synchronize with the Unleash-hosted API. State is kept in memory by the client SDK (and synchronizes with the Unleash-hosted API in the background). This is done to prefer performance over update speed. You can read more about the [Unleash architecture](https://www.unleash-hosted.com/articles/our-unique-architecture). + +It can also be nice to notice that if you use an undefined feature toggle the Unleash SDK will return false instead of crashing your application. The SDK will also report metrics back to Unleash-hosted on feature toggle usage, which makes it [possible to spot toggles not yet defined](../user_guide/discover-unknown-toggles). And this is a very neat way to help you debug if something does not work as expected. + +## Step 4: Provide the Unleash-context + +It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for a specific request. This is the job of the activation strategies, which are implemented in the client SDK. + +An activation strategy is an implementation of rules based on data, which you provide as part of the Unleash Context. + +You provide the Unleash context as part of the second argument to the isEnabled call: + +```sh + const context = { + userId: '123', + sessionId: '123123-123-123, + remoteAddress: '127.0.0.1', + }; + const enabled = isEnabled('app.demo', context); +``` diff --git a/docs/sdks/python.md b/docs/sdks/python.md new file mode 100644 index 0000000000..3bb6ceda79 --- /dev/null +++ b/docs/sdks/python.md @@ -0,0 +1,19 @@ +--- +id: python_sdk +title: Python SDK +--- + +```java +from UnleashClient import UnleashClient + + client = UnleashClient( + url="", + app_name="my-python-app", + custom_headers={'Authorization': ''}) + + client.initialize_client() + + client.is_enabled("unleash.beta.variants") +``` + +Read more at [github.com/Unleash/unleash-client-python](https://github.com/Unleash/unleash-client-python) \ No newline at end of file diff --git a/docs/sdks/ruby.md b/docs/sdks/ruby.md new file mode 100644 index 0000000000..f9ebf927c7 --- /dev/null +++ b/docs/sdks/ruby.md @@ -0,0 +1,16 @@ +--- +id: ruby_sdk +title: Ruby SDK +--- + +```sh + require 'unleash' + + @unleash = Unleash::Client.new( + url: '', + app_name: 'simple-test', + custom_http_headers = {'Authorization': ''}, + ) +``` + +Read more at [github.com/Unleash/unleash-client-ruby](https://github.com/Unleash/unleash-client-ruby) \ No newline at end of file diff --git a/docs/toggle_variants.md b/docs/toggle_variants.md new file mode 100644 index 0000000000..ae65994484 --- /dev/null +++ b/docs/toggle_variants.md @@ -0,0 +1,3 @@ +Please see /docs/advanced/toggle_variants + + diff --git a/docs/user_guide/activation-strategies.md b/docs/user_guide/activation-strategies.md new file mode 100644 index 0000000000..61d8f8c926 --- /dev/null +++ b/docs/user_guide/activation-strategies.md @@ -0,0 +1,89 @@ +--- +id: activation_strategy +title: 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 users. We achieve this level of control with the help of activation strategies. The most straightforward 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 various client implementations. + +Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](./unleash-context.md), which gives the necessary context for Unleash. + +## default + +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 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 to be enabled for_ + +## flexibleRollout + +A flexible rollout strategy which combines all gradual rollout strategies in to a single strategy (and will in time replace them). This strategy have different options for how you want to handle the stickiness, and have sane default mode. + +**Parameters** + +- **stickiness** is used to define how we guarantee consistency for gradual rollout. The same userId and the same rollout percentage should give predictable results. Configuration that should be supported: + - **default** - Unleash chooses the first value present on the context in defined order userId, sessionId, random. + - **userId** - guaranteed to be sticky on userId. If userId not present the behavior would be false + - **sessionId** - guaranteed to be sticky on sessionId. If sessionId not present the behavior would be false. + - **random** - no stickiness guaranteed. For every isEnabled call it will yield a random true/false based on the selected rollout percentage. +- **groupId** is used to ensure that different toggles will **hash differently** for the same user. The groupId defaults to _feature toggle name_, but the use can override it to _correlate rollout_ of multiple feature toggles. +- **rollout** The percentage (0-100) you want to enable the feature toggle for. + +### Customize stickiness (beta) + +By enabling the stickiness option on a custom context field you can use it together with the flexible rollout strategy. This will guarantee a consistent behavior for specific values of this context field. +NB! this feature is currently only supported by the following SDKs: + +- [unleash-client-node](https://github.com/Unleash/unleash-client-node) (from v3.6.0) + +## gradualRolloutUserId + +The `gradualRolloutUserId` strategy gradually activates a feature toggle for logged in users. Stickiness is based on the user ID. The strategy guarantees that the same user gets the same experience every time across devices. It also assures that a user which is among the first 10% will also be among the first 20% of the users. That way, we ensure the users get the same experience, even if we gradually increase the number of users exposed to a particular feature. To achieve this, we hash the user ID and normalize the hash 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 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 the feature toggle for._ +- groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._ + +## gradualRolloutSessionId + +Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a feature toggle, with the exception being that the stickiness is based on the 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 the feature toggle for._ +- groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._ + +## gradualRolloutRandom + +The `gradualRolloutRandom` strategy randomly activates a feature toggle and has 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 the feature toggle for._ + +## remoteAddress + +The remote address strategy activates a feature toggle for remote addresses defined in the IP list. We occasionally use this strategy to enable a feature only for IPs in our office network. + +**Parameters** + +- IPs - _List of IPs to enable the feature for._ + +## applicationHostname + +The application hostname strategy activates a feature toggle for client instances with a hostName in the `hostNames` list. + +**Parameters** + +- hostNames - _List of hostnames to enable the feature toggle for._ diff --git a/docs/client-sdk.md b/docs/user_guide/client-sdk.md similarity index 100% rename from docs/client-sdk.md rename to docs/user_guide/client-sdk.md diff --git a/docs/user_guide/connect-sdk.md b/docs/user_guide/connect-sdk.md new file mode 100644 index 0000000000..6250730d45 --- /dev/null +++ b/docs/user_guide/connect-sdk.md @@ -0,0 +1,132 @@ +--- +id: connect_sdk +title: Connect your SDK +--- + +In order to connect your application to Unleash you need to use a client SDK (software developer kit) for your programming language. The SDK will handle connecting to the unleash server instance and retrieve feature toggles based upon your configuration. Both open source and the unleash enterprise offering utilize the same set of client SDKs. + +If you are an Unleash customer, our hosted instances will always be a protected instance, you will therefore have to specify a client secret as the authorization header when you are connecting your client SDK, which you will receive from us when you sign up for one of our packages. In the open source version you must generate your own secret. + +On this page you will find examples for connecting your application to the demo instance. If you are connecting to your own private instance you will have to remember to replace the client secret and the API url given in the examples. + +We have examples for all official client SDKs: + +- [Java SDK](https://github.com/Unleash/unleash-client-java) +- [Node.js SDK](https://github.com/Unleash/unleash-client-node) +- [.NET SDK](https://github.com/Unleash/unleash-client-dotnet) +- [Go SDK](https://github.com/Unleash/unleash-client-go) +- [Ruby SDK](https://github.com/Unleash/unleash-client-ruby) +- [Python SDK](https://github.com/Unleash/unleash-client-python) + +When you get access to your instance – we will provide you with your Client secret and your API url for your instance. + +## Demo instance secrets +Our demo instance has the following settings – use these in case you would like to connect your test-app to our demo environment. + +### Client secret +```sh +56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d +``` + +### API url: +```sh +https://app.unleash-hosted.com/demo/api/ +``` + +### Test with curl: +```sh +curl https://app.unleash-hosted.com/demo/api/client/features \ +-H "Authorization: 56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d"; +``` + +## Java SDK +```java +UnleashConfig unleashConfig = UnleashConfig.builder() + .appName("my.java-app") + .instanceId("your-instance-1") + .unleashAPI("") + .customHttpHeader("Authorization", "") + .build(); + + Unleash unleash = new DefaultUnleash(config); +``` +Read more at [github.com/Unleash/unleash-client-java](https://github.com/Unleash/unleash-client-java) + +## Node.js SDK + +```js +const unleash = require('unleash-client'); + +unleash.initialize({ + url: '', + appName: 'my-node-name', + instanceId: 'my-unique-instance-id', + customHeaders: {'Authorization': ''} +}); +``` +Read more at [github.com/Unleash/unleash-client-node](https://github.com/Unleash/unleash-client-node) + +## Go SDK +```golang +import ( + "github.com/Unleash/unleash-client-go/v3" +) + +func init() { + unleash.Initialize( + unleash.WithAppName("my-node-app"), + unleash.WithUrl(""), + unleash.WithCustomHeaders(http.Header{"Authorization": {""}}), + ) +} +``` +Read more at [github.com/Unleash/unleash-client-go](https://github.com/Unleash/unleash-client-go) + +## Ruby SDK +```ruby + + + require 'unleash' + + @unleash = Unleash::Client.new( + url: '', + app_name: 'simple-test', + custom_http_headers = {'Authorization': ''}, + ) +``` +Read more at [github.com/Unleash/unleash-client-ruby](https://github.com/Unleash/unleash-client-ruby) + +## Python SDK +```python + + from UnleashClient import UnleashClient + + client = UnleashClient( + url="", + app_name="my-python-app", + custom_headers={'Authorization': ''}) + + client.initialize_client() + + client.is_enabled("unleash.beta.variants") +``` + +Read more at [github.com/Unleash/unleash-client-python](https://github.com/Unleash/unleash-client-python) + +## .NET SDK +```csharp + var settings = new UnleashSettings() + { + AppName = "dotnet-test", + InstanceTag = "instance z", + UnleashApi = new Uri(""), + SendMetricsInterval = TimeSpan.FromSeconds(20), + CustomHttpHeaders = new Dictionary() + { + {"Authorization","" } + } + }; + + var unleash = new DefaultUnleash(settings); +``` +Read more at [https://github.com/Unleash/unleash-client-dotnet](https://github.com/Unleash/unleash-client-dotnet) diff --git a/docs/user_guide/control-rollout.md b/docs/user_guide/control-rollout.md new file mode 100644 index 0000000000..56dfc2f0c5 --- /dev/null +++ b/docs/user_guide/control-rollout.md @@ -0,0 +1,49 @@ +--- +id: control_rollout +title: Control rollout +--- + +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 users. + +In this guide you will learn how to control the roll-out (expose it to real users) of a new feature with the help of activation strategies. + +## Built in activation strategies + +Unleash comes with a few common activation strategies. Some of them require the client to provide the unleash-context, which gives the necessary context for Unleash. + +The built in activation strategies: + +- default +- userWithId +- flexibleRollout +- remoteAddress +- applicationHostname + +## The default activation strategy + +When you create a new feature toggle you will get the default activation strategy, if you don’t configure any specific strategies. The default activation strategy will always evaluate to true, given that the feature toggle is enabled. + +![Default activation strategy](../assets/default_activation_strategy.png) + +## The userWithId strategy + +When we have deployed some new code to production it would be nice to enable the new feature for ourselves before we enable it to everyone else. To achieve this in Unleash you can use the **userWithId** activation strategy. This strategy allows you to specify a list of user IDs that you want to expose the new feature for. + +A userId is how you identify users in your system (email, UUID, etc) and is provided as part of the Unleash Context to the client SDK. + +![UserWithId activation strategy](../assets/userWithId_activation_strategy.png) + +## Multiple activation strategies + +In order to increase the exposure of the feature which is protected with the feature toggle you can configure multiple activation strategies on the same feature toggle. + +![Multiple activation strategy](../assets/multiple_activation_strategies.png) + +In the example above we have configure two activation strategies, **userWithId** and **flexibleRollout**. If one of them evaluates to true the feature toggle is considered enabled. In the example we have enabled the feature toggle for usersWithId (*me@mail.com and another@mail.com*) in addition to 10% of the traffic. + +## Summary + +You use activation strategies to control who the feature toggle will be enabled for. You can configure multiple strategies for a feature toggle, and they are considered in an OR fashion, meaning if one of them evaluates to true the toggle will be enabled. + +If you need to limit the exposure (AND) you should look in to [strategy constraints](strategy_constraints), which is the building block for that. + diff --git a/docs/user_guide/create-feature-toggle.md b/docs/user_guide/create-feature-toggle.md new file mode 100644 index 0000000000..2c98201f8e --- /dev/null +++ b/docs/user_guide/create-feature-toggle.md @@ -0,0 +1,41 @@ +--- +id: create_feature_toggle +title: Create a feature toggle +--- + +In this guide you will learn how to create your first feature toggle using Unleash. + +## Step 1: Click the “create feature toggle” button + +The first time you log-in to your Unleash instance you will see an empty list of feature toggles. In order to create a new feature toggle you have to click the “create feature toggle” button + +![Create a feature toggle](../assets/create_toggle_1.png) + +## Step 2: Create Feature toggle + +After clicking the “create feature toggle button you will be presented with a form for creating a new feature toggle. You will need to define a few fields before you can actually complete the new feature toggle. + +- **Name** – Must be unique across all your feature toggle. The name must also follow a URL friendly format. Can not be changed. +- **Description** – A good description makes it easier for other members on your team to understand why this feature toggle exists. +- **Enabled** – Whether the feature toggle should be enabled or disabled. If the feature toggle is disabled, activation strategy configurations will not be evaluated. +- **Activation** strategies – A list of one or more activation strategies. An activation strategy is used to enable the feature toggle to a subset, or all, of your users. + +In the example below we have chosen to configure the default activation strategy, which means that the feature will be enabled for everyone. + +![Create a feature toggle](../assets/create_toggle_2.png) + +## Step 3: Congratulations, you have now created your first feature toggle! + +The toggle is now created and ready to be used. The toggle does not have any metrics because it is not used by any applications, yet! + +![Create a feature toggle](../assets/create_toggle_3.png) + +## Step 4: Enable the feature toggle only for your boss! + +The next step is to change the activation strategy to only target your boss. You can use the “userWithId”-strategy for that. Using the configuration shown below will only enable the feature toggle for “boss@company.com” and “me@company.com”. Thus you can safely test your feature in production, without exposing it to your users. In [control roll-out](./control_rollout) with strategies we will go in to greater details on how to use activation strategies to gradually expose new features to your users. + +![Create a feature toggle](../assets/userWithId.png) + +## Summary + +In this guide you created your first feature toggle and enabled it for everyone. In later guides we will learn how we can reduce the risk by enabling the toggle for a controlled set of users first. diff --git a/docs/user_guide/discover-unknown-toggles.md b/docs/user_guide/discover-unknown-toggles.md new file mode 100644 index 0000000000..1266829506 --- /dev/null +++ b/docs/user_guide/discover-unknown-toggles.md @@ -0,0 +1,4 @@ +id: discover_unkonwn_toggles +title: Discover unknown toggles +--- +Discover unkonwn toggles diff --git a/docs/user_guide/native-apps.md b/docs/user_guide/native-apps.md new file mode 100644 index 0000000000..ff6a906ac7 --- /dev/null +++ b/docs/user_guide/native-apps.md @@ -0,0 +1,62 @@ +--- +id: native_apps +title: Working with native apps +--- + +> **Enterprise feature** +> +> Working with native apps, require the unleash proxy. The Unleash Proxy is only available with the Unleash-hosted offering and is not part of Unleash Open-Source. + +For a highlevel introduction to the Unleash-proxy, please read this short article [The Unleash-Proxy](https://www.unleash-hosted.com/articles/the-unleash-proxy) + +The Unleash-proxy consist of the proxy that exposes a simple API for the client. + +![Unleash Proxy](../assets/The-unleash-proxy.png) + +## The Proxy-client + +There is a js implentation of the proxy-client available. +Find it here: [https://github.com/unleash-hosted/unleash-proxy-client-js](https://github.com/unleash-hosted/unleash-proxy-client-js) + +## The Proxy-API + +When accessing the Proxy, [Unleash context fields](unleash_context) from the session context can be added as parameters to the request. The proxy will return only enabled feature toggles and their evaluated value for the given context. You may also use custom context fields in combination with [strategy constraints](strategy_constraints). + +```sh +https://hostname.com/api/proxy?appName=webapp&userId=123&country=NO +``` +The Proxy will return a list of all the active feature toggles, including variants, available. See an example below +```sh +{ + "toggles": [ + { + "enabled": true, + "name": "SimpleToggle", + "variant": { + "enabled": false, + "name": "disabled" + } + }, + { + "enabled": true, + "name": "ToggleWithVariant", + "variant": { + "enabled": true, + "name": "brown" + } + }, + { + "enabled": true, + "name": "ToggleWithVariantAndPayload", + "variant": { + "enabled": true, + "name": "default", + "payload": { + "type": "string", + "value": "Some custom value here!" + } + } + } + ] +} +``` diff --git a/docs/user_guide/projects.md b/docs/user_guide/projects.md new file mode 100644 index 0000000000..82baaac40e --- /dev/null +++ b/docs/user_guide/projects.md @@ -0,0 +1,86 @@ +--- +id: projects +title: Projects +--- + +> **Enterprise** +> +> Project support is only available in Unleash Enterprise + +## Overview +This topic explains how projects are supported in Unleash, how to create and maintain them. + +## Understanding purpose of projects +Projects are a way to organize your feature toggles within Unleash. Within a large organization, having multiple feature toggles, staying on top of the feature toggles might become a challenge. Every feature toggle will be part of a project. Projects can be linked to a development team or to functional modules within the software. + +A common pattern is to organize the feature toggles according to key areas of the application, e.g. “Basic user process” and “Advanced user process”. This is illustrated below. + +![Project concept](../assets/project_concept.png) + +## Creating a new project +When you log into Unleash for the first time, there is a Default project already created. All feature toggles are included in the Default project, unless explicitly set to a different one. + +From the top-line menu – click on the hamburger icon. + +![Project concept](../assets/project_main_menu.png) + +From the menu – choose “Projects” + +![Project concept](../assets/project_menu_item.png) + +The available projects will now be listed. +To create a new Project – choose the “+” + +![Project concept](../assets/project_add.png) + +The configuration of a new Project is now available. the following input is available to create the new Project. + +![Project concept](../assets/project_configure.png) + +| Item | Description | +| ----------- | ----------- | +| Project Id | Id for this Project | +| Project name | The name of the Project. | +| Description | A short description of the project | + +## Deleting an existing project +To keep your feature toggles clean, removing deprecated projects is important. From the overview of Projects – choose the Delete button for the project you want to delete. + +![Project concept](../assets/project_delete.png) + +## Filter feature toggles on projects +When browsing the feature toggles in Unleash, you might want to filter the view by looking only at the ones included in the project of interest. This is possible from the Feature toggle overview. + +From the top-line menu – choose the hamburger icon + +![Project concept](../assets/feature_toggles_menu.png) + +From the menu – choose “Feature toggles” + +![Project concept](../assets/feature_toggles_menu.png) + +The list of features toggles can be filtered on the project of your choice. By default, all feature toggles are listed in the view. + +![Project concept](../assets/ft_project_filter.png) + +From the drop-down, chose the project to filter on. + +![Project concept](../assets/ft_filter_on_project.png) + +The view will now be updated with the filtered feature toggles. + +## Assigning project to a new feature toggle +When creating a new feature toggle, the project where the feature toggle will be created may be chosen. The default project is “Default” + +![Project concept](../assets/ft_create_chose_project.png) + +All available projects are available from the drop-down menu. + +![Project concept](../assets/ft_create_assign_project.png) + +## Change project for an existing feature toggle +There might be a need to change the project a feature toggle belongs to. Changing the project is possible from the feature toggle configuration page. + +![Project concept](../assets/ft_create_assign_project.png) + +To change the project, simply change the project from the drop-down menu. diff --git a/docs/user_guide/single-page-apps.md b/docs/user_guide/single-page-apps.md new file mode 100644 index 0000000000..42b2aea22e --- /dev/null +++ b/docs/user_guide/single-page-apps.md @@ -0,0 +1,8 @@ +--- +id: single_page_apps +title: Working with single page apps +--- + +> This is an Enterprise feature. + +Working with single page apps \ No newline at end of file diff --git a/docs/user_guide/unleash-context.md b/docs/user_guide/unleash-context.md new file mode 100644 index 0000000000..fdaaae4aba --- /dev/null +++ b/docs/user_guide/unleash-context.md @@ -0,0 +1,21 @@ +--- +id: unleash_context +title: Unleash Context +--- + +To standardise a few activation strategies, we also needed to standardise the Unleash context, which contains fields that vary per request, required to implement the activation strategies. + +The unleash context is defined by these fields: + +- userId: String, +- sessionId: String, +- remoteAddress: String, +- properties: Map +- appName: String +- environment: String + +All fields are optional, but if they are not set you will not be able to use certain activation strategies. + +E.g., the `userWithId` strategy obviously depends on the `userId` field. + +The `properties` field is more generic and can be used to provide more abritary data to strategies. Typical usage is to add more metadata. For instance, the `betaUser` strategy may read a field from `properties` to check whether the current user is a beta user. diff --git a/website/i18n/en.json b/website/i18n/en.json index d2bac9eb47..96bd459bac 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -20,6 +20,30 @@ "addons/webhook": { "title": "Webhook" }, + "advanced/api_access": { + "title": "API Access" + }, + "advanced/archived_toggles": { + "title": "Archived toggles" + }, + "advanced/audit_log": { + "title": "The audit log" + }, + "advanced/custom_activation_strategy": { + "title": "Custom Activation Strategy" + }, + "advanced/feature_toggle_types": { + "title": "Feature Toggle Types" + }, + "advanced/toggle_variants": { + "title": "Feature Toggle Variants" + }, + "advanced/strategy_constraints": { + "title": "Strategy Constraints" + }, + "advanced/tags": { + "title": "Tagging Features" + }, "api/admin/addons": { "title": "/api/admin/addons" }, @@ -63,77 +87,125 @@ "title": "Open API Specification" }, "client_sdk": { - "title": "Client SDK" + "title": "client_sdk" }, "client_specification": { "title": "Client Specification" }, - "configuring_unleash": { - "title": "Configuring Unleash" - }, - "database_backup": { - "title": "Database Backup" - }, "database_schema": { "title": "Database Schema" }, - "dev/version-4": { - "title": "dev/version-4" + "deploy/configuring_unleash": { + "title": "Configuring Unleash" + }, + "deploy/database_backup": { + "title": "Database Backup" + }, + "deploy/getting_started": { + "title": "Getting Started" + }, + "deploy/google_auth": { + "title": "Google Auth Hook" + }, + "deploy/import_export": { + "title": "Import & Export" + }, + "deploy/migration_guide": { + "title": "Migration Guide" + }, + "deploy/securing_unleash": { + "title": "Securing Unleash" }, "developer_guide": { "title": "Developer guide" }, - "feature_toggle_types": { - "title": "Feature Toggle Types" - }, - "toggle_variants": { - "title": "Feature Toggle Variants" - }, "getting_started": { "title": "Getting Started" }, - "guides/custom_activation_strategy": { - "title": "Custom Activation Strategy" - }, "guides/feature_updates_to_slack": { "title": "Feature Updates To slack" }, - "guides/google_auth": { - "title": "Google Auth Hook" - }, - "import_export": { - "title": "Import & Export" - }, "index": { "title": "index" }, - "migration_guide": { - "title": "Migration Guide" + "integrations/integrations": { + "title": "Integrations and plugins" }, - "securing_unleash": { - "title": "Securing Unleash" + "sdks/dot_net_sdk": { + "title": ".net SDK" }, - "tags": { - "title": "Tagging Features" + "sdks/go_sdk": { + "title": "GO SDK" + }, + "sdks/java_sdk": { + "title": "Java SDK" + }, + "sdks/node_sdk": { + "title": "Node SDK" + }, + "sdks/python_sdk": { + "title": "Python SDK" + }, + "sdks/ruby_sdk": { + "title": "Ruby SDK" + }, + "toggle_variants": { + "title": "toggle_variants" }, "unleash_context": { "title": "Unleash Context" + }, + "user_guide/activation_strategy": { + "title": "Activation Strategies" + }, + "user_guide/client_sdk": { + "title": "Client SDK" + }, + "user_guide/connect_sdk": { + "title": "Connect your SDK" + }, + "user_guide/control_rollout": { + "title": "Control rollout" + }, + "user_guide/create_feature_toggle": { + "title": "Create a feature toggle" + }, + "user_guide/discover-unknown-toggles": { + "title": "user_guide/discover-unknown-toggles" + }, + "user_guide/native_apps": { + "title": "Working with native apps" + }, + "user_guide/projects": { + "title": "Projects" + }, + "user_guide/single_page_apps": { + "title": "Working with single page apps" + }, + "user_guide/unleash_context": { + "title": "Unleash Context" } }, "links": { "Documentation": "Documentation", "API": "API", + "Deploy and manage": "Deploy and manage", + "Integrations": "Integrations", + "Contribute": "Contribute", "Help": "Help" }, "categories": { - "User Documentation": "User Documentation", - "Addons": "Addons", - "Developer Guide": "Developer Guide", - "Guides": "Guides", + "Getting started": "Getting started", + "Working with your SDK": "Working with your SDK", + "Addons framework": "Addons framework", + "Advanced": "Advanced", "Client": "Client", "Admin": "Admin", "Internal": "Internal", - "Specification": "Specification" + "Specification": "Specification", + "Deploy & configure": "Deploy & configure", + "Integrations": "Integrations", + "Contribute to Unleash": "Contribute to Unleash" } }, "pages-strings": { diff --git a/website/sidebars.json b/website/sidebars.json index 181695243d..209386ccc2 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,33 +1,39 @@ { "documentation": { - "User Documentation": [ - "getting_started", - "configuring_unleash", - "client_sdk", - "feature_toggle_types", - "toggle_variants", - "securing_unleash", - "unleash_context", - "activation_strategy", - "client_specification", - "migration_guide" + "Getting started": [ + "user_guide/connect_sdk", + "user_guide/client_sdk", + "user_guide/create_feature_toggle", + "user_guide/activation_strategy", + "user_guide/control_rollout", + "user_guide/projects", + "user_guide/unleash_context", + "user_guide/native_apps", + "user_guide/single_page_apps" ], - "Addons": [ + "Working with your SDK": [ + "sdks/java_sdk", + "sdks/node_sdk", + "sdks/dot_net_sdk", + "sdks/go_sdk", + "sdks/python_sdk", + "sdks/ruby_sdk" + ], + "Addons framework": [ "addons/index", "addons/webhook", "addons/slack", "addons/jira-commenter" ], - "Developer Guide": [ - "developer_guide", - "database_schema", - "database_backup", - "import_export" - ], - "Guides": [ - "guides/google_auth", - "guides/custom_activation_strategy", - "guides/feature_updates_to_slack" + "Advanced": [ + "user_guide/strategy_constraints", + "advanced/custom_activation_strategy", + "advanced/feature_toggle_types", + "advanced/toggle_variants", + "advanced/archived_toggles", + "advanced/audit_log", + "advanced/api_access", + "advanced/tags" ] }, "api": { @@ -47,5 +53,29 @@ ], "Internal": ["api/internal"], "Specification": ["api/open_api"] + }, + "Deploy and manage": { + "Deploy & configure": [ + "deploy/getting_started", + "deploy/configuring_unleash", + "deploy/securing_unleash", + "deploy/google_auth", + "deploy/database_backup", + "deploy/migration_guide", + "deploy/import_export" + ] + }, + "Integrations": { + "Integrations": [ + "integrations/integrations" + ] + }, + "Contribute": { + "Contribute to Unleash": [ + "developer_guide", + "client_specification", + "database_schema" + ] } } + diff --git a/website/siteConfig.js b/website/siteConfig.js index c3fa06b7b7..44d911a529 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -66,8 +66,11 @@ const siteConfig = { // For no header links in the top nav bar -> headerLinks: [], headerLinks: [ - { doc: 'getting_started', label: 'Documentation' }, + { doc: 'user_guide/connect_sdk', label: 'Documentation' }, { doc: 'api/client/features', label: 'API' }, + { doc: 'deploy/getting_started', label: 'Deploy and manage' }, + { doc: 'integrations/integrations', label: 'Integrations' }, + { doc: 'developer_guide', label: 'Contribute' }, { page: 'help', label: 'Help' }, // {blog: true, label: 'Blog'}, ],