Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create setup_bluemix.md #101

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Create setup_bluemix.md #101

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3914672
Create setup_bluemix.md
Dec 19, 2016
6217f57
Updated to include Bluemix structure and content
Jan 4, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 180 additions & 0 deletions 1-Demo/setup_bluemix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
---
layout: page
title: Setup Amalgam8 for Bluemix
permalink: /docs/demo-setup_bluemix.html
redirect_from:
category: Demo
order: 1
---

## Before you begin

Amalgam8 on Bluemix uses the IBM Bluemix Container Service, which requires the Cloud Foundry (cf) and Bluemix (bluemix) plugins. If these are not already installed, then follow these steps.

1. Install the Cloud Foundry (cf) plug-in.

a) Download the latest version of the plug-in from the following GitHub repo: http://github.com/cloudfoundry/cli/releases
b) Follow the instructions that are available in http://docs.cloudfoundry.org/cf-cli/install-go-cli.html#linux to install the CF plug-in.

2. Install the Bluemix (bluemix) plug-in.

a) Download the latest version of the plug-in from http://plugins.ng.bluemix.net/ui/home.html.
b) Extract the file.
c) Change to the directory `Bluemix_CLI` and install the plug-in. Run the following command as `root`: `./install_bluemix_cli`

For example, on Ubuntu, the following code installs the Bluemix plugin:

```
# Run the install command as root
root@bluemix:~# tar -xvf Bluemix_CLI_0.4.2_amd64.tar.gz
Bluemix_CLI/
Bluemix_CLI/bx/
Bluemix_CLI/bx/zsh_autocomplete
Bluemix_CLI/bx/bash_autocomplete
Bluemix_CLI/bin/
Bluemix_CLI/bin/bluemix
Bluemix_CLI/bin/NOTICE
Bluemix_CLI/bin/LICENSE
Bluemix_CLI/bin/bluemix-analytics
Bluemix_CLI/install_bluemix_cli

# Change directory
#root@bluemix:~# cd Bluemix_CLI

# Install the Bluemix CLI
root@bluemix:~/Bluemix_CLI# ./install_bluemix_cli
The Cloud Foundry CLI version 6.22 is already installed.
Copying files ...
The Bluemix Command Line Interface (Bluemix CLI) is installed successfully.
To get started, open a new Linux terminal and enter "bluemix help", or enter "bx help" as short name.
```


## Setting up the Control Plane

The Amalgam8 Control Plane consists of two components: the
[service registry](/docs/control-plane-registry.html) and the
[route controller](/docs/control-plane-controller.html). In addition to these two
components, for the purposes of this demo, a stock ELK stack is also
included as part of the control plane deployment scripts, to collect logs
from the microservices in the application.

The Amalgam8 Control Plane contains an ELK stack.
Elasticsearch 5.0 [requires increasing the max map count](https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html)
for certain linux environments such as Vagrant VMs, Docker Toolbox and Minikube.
If you are running any of these tools, run the following command on those VMs:

```
bash
sudo sysctl -w vm.max_map_count=262144
```

To deploy the control plane in the IBM Bluemix Container Service, complete the following steps.

1. Log in to the Bluemix org and space in which you want to deploy the Amalgam8 control plane, and add the IBM Bluemix Container Service plugin by running the following command:

```
bluemix login
bluemix plugin repo-add Bluemix https://plugins.ng.bluemix.net
bluemix plugin install IBM-Containers -r Bluemix
```

You can verify the installation by running ``bluemix plugin list``. The command return resembles the following output:

```
Listing installed plug-ins...
Plugin Name Version
IBM-Containers 1.0.0
```

2. Start the IBM Bluemix Container Service in the space in which you want to deploy the Amalgam8 control plane by running the following command:

```
bluemix ic init
```

If you are requested to enter a namespace value, be aware that this value is set once for an organization and after it is created it cannot be changed. You might want to check with your organization's administrator before you proceed. Refer to the [IBM Bluemix Container Service](https://console.bluemix.net/docs/containers/container_index.html) documentation for more information.

For the purposes of running the Amalgam8 demos, you can customize the downloaded _examples/bluemix.cfg_ file to set your environment variables, and then run the a8-bluemix script. After you run the script, skip to [Setting up the Amalgam8 CLI](#a8cli). To learn how to set your environment variables by using the Bluemix CLI, continue following the steps.

3. Collect the information that is required to set values for the Amalgam8 environment variables:

| Command to set environment variable | What it is | Command to get the value |
|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|
| ``` export ROUTES_DOMAIN=example.bluemix.net ``` | An available domain in your Bluemix org. In the command, replace `example.bluemix.net` with your chosen Bluemix domain. | ``` bluemix cf domains ``` |
| ``` export BLUEMIX_SPACE=example ``` | The space in your org that you want to deploy Amalgam8 to. In the command, replace `example` with the name of the space. | ``` bluemix cf target ``` |
| ``` export BLUEMIX_REGISTRY_NAMESPACE= example ``` | The namespace for your org. In the command, replace `example` with the namespace. | ``` bluemix ic namespace-get ``` |
| ``` export BLUEMIX_REGISTRY_HOST=registry.ng.bluemix.net ``` | The IBM Bluemix Container Service registry. The BLUEMIX_REGISTRY_HOST defaults to the container image registry that is associated with the region and organization that your are working on in Bluemix. For example, in US South the value is `registry.ng.bluemix.net`. | ``` bluemix ic info ``` |



4. Run the following commands to create the other required environment variables:

```
export CONTROLLER_IMAGE=a8-controller:latest
export REGISTRY_IMAGE=a8-registry:latest
export DOCKERHUB_NAMESPACE=amalgam8
```

The Amalgam8 registry and controller components are deployed to the Bluemix space as container groups. Each container group must be assigned a route so that the components can be accessed. In the environment variables, the route defaults to the name of the Bluemix space that is appended with -a8-registry and -a8-controller. If you want to use different routes, change these environment variables:

```
export REGISTRY_HOSTNAME=$BLUEMIX_SPACE-a8-registry
export CONTROLLER_HOSTNAME=$BLUEMIX_SPACE-a8-controller
export REGISTRY_URL=http://$REGISTRY_HOSTNAME.$ROUTES_DOMAIN
export CONTROLLER_URL=http://$CONTROLLER_HOSTNAME.$ROUTES_DOMAIN
```

Your local system is set up for Amalgam8. Next, install the Amalgam8 CLI.



##<a name="a8cli">Setting up the Amalgam8 CLI</a>

The `a8ctl` command line utility provides a convenient way to setup and
manage routes across microservices as well as inspect the state of the
system. The CLI can be installed via the `pip` tool (available as part of
standard Python installation) directly from Python's package repository or
from `a8ctl` [github repository](https://github.com/amalgam8/a8ctl).


1. Run the following command to install the a8ctl into your home directory:

```
bash
pip install --user a8ctl
```

1. Add the location of the `a8ctl` command to the `PATH` environment variable.

* On OS X, run:

```
bash
export PATH=$PATH:${HOME}/Library/Python/2.7/bin
```

* On Linux, run:

```
bash
export PATH=$PATH:${HOME}/.local/bin
```

So that the a8ctl command can communicate with the Amalgam8 control plane, you must set the a8ctl command environment variables for the registry and controller components of the control plane.
You need to set up two environment variables: `A8_CONTROLLER_URL` and
`A8_REGISTRY_URL`. These variables should point to the publicly accessible
REST endpoints exposed by the Amalgam8 controller and registry respectively.

The value of these variables depends on the environment where you set up the
control plane.

1. Run the following commands:

```
bash
export A8_CONTROLLER_URL=$CONTROLLER_URL
export A8_REGISTRY_URL=$REGISTRY_URL
```

Now that you've configured Amalgam8 for IBM Bluemix, let's move onto running the demo.