From abb4829cb9edf91562f4257f7a9e91f5b6bdf7ec Mon Sep 17 00:00:00 2001 From: Fredrik Oseberg Date: Fri, 13 Aug 2021 10:56:53 +0200 Subject: [PATCH] feat: add more sections to quickstart --- websitev2/docs/user_guide/quickstart.md | 155 ++++++++++++++++++++++-- websitev2/docs/user_guide/token.md | 2 +- 2 files changed, 143 insertions(+), 14 deletions(-) diff --git a/websitev2/docs/user_guide/quickstart.md b/websitev2/docs/user_guide/quickstart.md index 6eb4052240..ac686a4d65 100644 --- a/websitev2/docs/user_guide/quickstart.md +++ b/websitev2/docs/user_guide/quickstart.md @@ -7,10 +7,58 @@ In this section we will attempt to guide you in order to get started with Unleas ## I just want to get started creating toggles without much setup -Usually, you'll need to set up an unleash instance in order to work with unleash. However, for testing purposes we have set up a demo instance that you can use in order to test out different use-cases before setting up your own instance. You can find the demo instance admin panel here: https://unleash.herokuapp.com/ +Usually, you'll need to set up an unleash instance in order to work with unleash. However, for testing purposes we have set up a demo instance that you can use in order to test out different use-cases before setting up your own instance. You can find the demo instance admin panel here: https://app.unleash-hosted.com/demo/ + +NOTE: This is a demo instance set up with the enterprise version. Some of the functionality may be enterprise specific, but everything we cover here is also available in open source. ### I want to test toggles in a client side environment +In order to use feature toggles on the client side you need to connect through [the unleash proxy](../sdks/unleash_proxy). The unleash proxy will provide a security and performance layer between your client application and the unleash instance. For now, you can use the proxy we have set up on the demo instance. + +#### Create your first toggle + +In order to create a toggle through the UI, [you can follow this guide](./create_feature_toggle). Once you have created your feature toggle, you are ready to connect your application using an SDK. + +#### Connecting to the unleash proxy from your app + +Connection details: + +``` +Api URL: https://app.unleash-hosted.com/demo/proxy +Secret key: proxy-123 (edited) +``` + +Now you can open your application code and connect through one of the proxy SDKs: + +- [Javascript Proxy SDK](../sdks/proxy-javascript) +- [iOS Proxy SDK](../sdks/proxy-ios) +- [Android Proxy SDK](../sdks/android_proxy_sdk) +- React + +Here is a connection example using the javascript proxy SDK: + +```javascript +import { UnleashClient } from 'unleash-proxy-client'; + +const unleash = new UnleashClient({ + url: 'https://app.unleash-hosted.com/demo/proxy', + clientKey: 'proxy-123', + appName: 'my-webapp', +}); + +// Used to set the context fields, shared with the Unleash Proxy +unleash.updateContext({ userId: '1233' }); + +// Start the background polling +unleash.start(); + +if (unleash.isEnabled('proxy.demo')) { + // do something +} +``` + +Now you are ready to use the feature toggle you created in your client side application, using the appropriate proxy SDK. + ### I want to test toggles in a backend environment #### Create your first toggle @@ -19,23 +67,23 @@ In order to create a toggle through the UI, [you can follow this guide](./create #### Connecting to the unleash instance from your app -You'll need the following information in order to connect with an SDK: +Connection details: ``` -Api URL: https://unleash.herokuapp.com/api/ -Secret key: 3bd74da5b341d868443134377ba5d802ea1e6fa2d2a948276ade1f092bec8d92 +Api URL: https://app.unleash-hosted.com/demo/api/ +Secret key: 56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d ``` Now you can open up your application code and create a connection to unleash using one of our [SDKs](../sdks). Here's an example using the NodeJS SDK: -``` +```javascript const { initialize } = require('unleash-client'); const unleash = initialize({ - url: 'http://unleash.herokuapp.com/api/', + url: 'https://app.unleash-hosted.com/demo/api/', appName: 'my-app-name', instanceId: 'my-unique-instance-id', customHeaders: { - Authorization: '3bd74da5b341d868443134377ba5d802ea1e6fa2d2a948276ade1f092bec8d92', + Authorization: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d', }, }); @@ -50,15 +98,96 @@ unleash.on('synchronized', () => { }); ``` +Now you can fetch the feature toggle you created and try turning it on / off in your code. + ## I want to setup my own instance for testing purposes -With Role-Based Access Control you can now assign groups to users in order to control access. You can control access to root resources in addition to controlling access to [projects](./projects). _Please be aware that all existing users will become "Owner" of all existing projects as part of the migration from v3 to v4._ +If you want to set up your own instance for testing purposes you can easily do so by using one of our premade setup kits for heroku or digitalocean. -[Read more](./rbac) +> The heroku instance setup is FREE, and includes a DB to save your state but it will eventually go to sleep when not used. The digitalocean setup utilises droplets and will cost you around 10$/month to run, but in turn it will not go to sleep. NOTE: If you use the DigitalOcean link below and are a new user, you will receive 100$ in FREE credits. + +### Deploy a free version of unleash to Heroku + +[![Deploy to Heroku](https://www.herokucdn.com/deploy/button.png)](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash) + +### Deploy a paid version of unleash to DigitalOcean + +> You'll receive 100\$ in free credits if you are a new DigitalOcean user using this link. + +[![Deploy to DigitalOcean](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/Unleash/unleash/tree/master&refcode=0e1d75187044) + +### Accessing your new instance + +Once you have set up the new instance, click the URL provided by either Heroku or DigitalOcean and you'll be taken to the application login screen. + +Input the following credentials to log in: + +``` +username: admin +password: unleash4all +``` + +### Create your first toggle + +In order to create a toggle through the UI, [you can follow this guide](./create_feature_toggle). Once you have created your feature toggle, you are ready to connect your application using an SDK. + +### Connect your SDK + +Now you're logged in as an admin. Next, find the navigation, open up the Admin panel and find the API Access tab. Click "Add new api key" and create a client key. This key can be used to connect to the instance with our [SDKs](../sdks). + +You can find more [information about API keys here.](./api-token). + +Now that you have your API key created, you have what you need to connect to the SDK (NodeJS example): + +```javascript +const { initialize } = require('unleash-client'); +const unleash = initialize({ + url: 'https://your.heroku.instance.com/api/', + appName: 'my-app-name', + instanceId: 'my-unique-instance-id', + customHeaders: { + Authorization: 'YOUR_API_KEY_HERE', + }, +}); + +unleash.on('synchronized', () => { + // Unleash is ready to serve updated feature toggles. + + // Check a feature flag + const isEnabled = unleash.isEnabled('some-toggle'); + + // Check the variant + const variant = unleash.getVariant('app.ToggleY'); +}); +``` + +## I want to run unleash locally + +### Run Unleash with docker-compose + +The easiest way to run unleash locally is using [docker](https://www.docker.com/) and [docker-compose](https://docs.docker.com/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. + +Unleash should now be available on `http://localhost:4242` + +[Click here to see all options to get started locally.](../deploy/getting_started) + +### Accessing your new instance + +Once you have the local instance running on localhost, input the following credentials to log in: + +``` +username: admin +password: unleash4all +``` + +### Create your first toggle + +In order to create a toggle through the UI, [you can follow this guide](./create_feature_toggle). Once you have created your feature toggle, you are ready to connect your application using an SDK. ## I want to set up a production ready instance -Addons make it easy to integrate Unleash with other systems. In version 4 we bring two new integrations to Unleash: - -- [Microsoft Teams](../addons/teams) -- [Datadog](../addons/datadog) +Coming soon. diff --git a/websitev2/docs/user_guide/token.md b/websitev2/docs/user_guide/token.md index 28bf85386f..be3ab9ece2 100644 --- a/websitev2/docs/user_guide/token.md +++ b/websitev2/docs/user_guide/token.md @@ -25,7 +25,7 @@ All users are able to see tokens with CLIENT level access, but only instance adm ![Tab Menu](/img/admin_tab_menu.png) -**3. Click `Add new API key` at the bottom of the page** +**3. Click `Add new API key` at the top right of the page** **Client keys**