diff --git a/website/docs/deploy/getting-started.md b/website/docs/deploy/getting-started.md index f369b547b8..6a13a1e2ee 100644 --- a/website/docs/deploy/getting-started.md +++ b/website/docs/deploy/getting-started.md @@ -57,11 +57,13 @@ docker run -p 4242:4242 \ -e DATABASE_HOST=postgres -e DATABASE_NAME=unleash \ -e DATABASE_USERNAME=unleash_user -e DATABASE_PASSWORD=some_password \ -e DATABASE_SSL=false \ - --network unleash unleashorg/unleash-server + --network unleash --pull=always unleashorg/unleash-server ``` ### Option 2 - use Docker-compose {#option-two---use-docker-compose} + **Steps:** + 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. @@ -95,7 +97,7 @@ docker run -p 4242:4242 \ port: 4242, }, }) - .then(unleash => { + .then((unleash) => { console.log( `Unleash started on http://localhost:${unleash.app.get('port')}`, ); diff --git a/website/docs/user_guide/quickstart.md b/website/docs/user_guide/quickstart.md index 9fdab31479..7c7e8c432d 100644 --- a/website/docs/user_guide/quickstart.md +++ b/website/docs/user_guide/quickstart.md @@ -198,27 +198,42 @@ unleash.on('synchronized', () => { ## I want to run Unleash locally -### Run Unleash with Docker +### Run Unleash with Docker {#run-unleash-with-docker} The easiest way to run unleash locally is using [docker](https://www.docker.com/). +:::tip + +Each container that runs in your local Docker instance must have a unique name. If you've run these commands before, you can either start the containers again (`docker start ${CONTAINER_NAME}`) or remove them (`docker rm ${CONTAINER_NAME}`) and run the commands again. + +::: + 1. Create a network by running `docker network create unleash` 2. Start a postgres database: ```sh -docker run -e POSTGRES_PASSWORD=some_password \ - -e POSTGRES_USER=unleash_user -e POSTGRES_DB=unleash \ - --network unleash --name postgres postgres +docker run \ + -e POSTGRES_USER=unleash_user \ + -e POSTGRES_PASSWORD=some_password \ + -e POSTGRES_DB=unleash \ + --network unleash \ + --name postgres \ + postgres ``` 3. Start Unleash via docker: ```sh -docker run -p 4242:4242 \ - -e DATABASE_HOST=postgres -e DATABASE_NAME=unleash \ - -e DATABASE_USERNAME=unleash_user -e DATABASE_PASSWORD=some_password \ +docker run \ + -p 4242:4242 \ + -e DATABASE_HOST=postgres \ + -e DATABASE_NAME=unleash \ + -e DATABASE_USERNAME=unleash_user \ + -e DATABASE_PASSWORD=some_password \ -e DATABASE_SSL=false \ - --network unleash unleashorg/unleash-server + --network unleash \ + --name unleash \ + --pull=always unleashorg/unleash-server ``` [Click here to see all options to get started locally.](deploy/getting-started.md) @@ -232,6 +247,58 @@ username: admin password: unleash4all ``` +### Run Unleash and the Unleash proxy with Docker + +Follow steps outlined in the [Run Unleash with Docker](#run-unleash-with-docker) section to get the Unleash instance up and running. Once you have done that you need to first get an API key from your Unleash instance and then use that API key when starting the Unleash proxy. + +1. Get an API key. + + To get an API key, access your Unleash instance in a web browser. First, navigate to the API access screen. + + ![The Unleash UI showing a dropdown menu under the "Configure" menu +entry. The dropdown menu's "API Access" option is highlighted and +you're told to navigate there.](/img/api_access_navigation.png 'Navigate to the API access page.') + + Next, create an API key with these details + + - **name:** proxy-key (this can be whatever you want) + - **token type:** client + - **project:** all + - **environment:** select your preferred environment (this option is only available in Unleash 4.3 and later) + + Copy the API key to your clipboard. You'll need it in the next step. + + :::note + + Depending on whether you have the environments feature enabled or not, the API key will look a little different. If you don't have environments enabled, it'll just be a 64 character long hexadecimal string (for instance `be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178`). If you do have environments enabled, the key will be prefixed with the project and the environment that the key is valid for. It'll use the format `:.`, e.g. `demo-app:production.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178`. + + Regardless of which format your string uses, do not modify it. + + ::: + +2. Start the Unleash proxy + + Start a container with the Unleash proxy by running the following command. Replace `${API_KEY}` with the key you created in the following step. + + ```sh + docker run \ + -e UNLEASH_PROXY_SECRETS=some-secret \ + -e UNLEASH_URL='http://unleash:4242/api/' \ + -e UNLEASH_API_TOKEN='${API_KEY}' \ + -p 3000:3000 \ + --network unleash \ + --name unleash-proxy \ + --pull=always unleashorg/unleash-proxy + ``` + +3. Test the proxy + + To make sure the proxy is running successfully, you can test it by running the following command: + + ```curl + curl http://localhost:3000/proxy -H "Authorization: some-secret" + ``` + ### Create your first toggle In order to create a toggle through the UI, [you can follow this guide](create-feature-toggle.md). Once you have created your feature toggle, you are ready to connect your application using an SDK. diff --git a/website/static/img/api_access_navigation.png b/website/static/img/api_access_navigation.png new file mode 100644 index 0000000000..9f83317ebb Binary files /dev/null and b/website/static/img/api_access_navigation.png differ