Skip to content
This repository has been archived by the owner on Nov 30, 2021. It is now read-only.

Commit

Permalink
docs(readme): update root readme with new deisctl instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
Gabriel Monroy committed Sep 21, 2014
1 parent 8d08d43 commit 9267de1
Showing 1 changed file with 45 additions and 52 deletions.
97 changes: 45 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,89 +6,79 @@ Deis (pronounced DAY-iss) is an open source PaaS that makes it easy to deploy an

![Deis Graphic](https://s3-us-west-2.amazonaws.com/deis-images/deis-graphic.png)

# Deploying Deis

Deis is a set of Docker containers that can be deployed anywhere including public cloud, private cloud, bare metal or your workstation. Decide where you'd like to deploy Deis, then follow the deployment-specific documentation for [Rackspace](contrib/rackspace/README.md), [EC2](contrib/ec2/README.md), [DigitalOcean](contrib/digitalocean/README.md), [Google Compute Engine](contrib/gce/README.md) or [bare-metal](contrib/bare-metal/README.md) provisioning. Documentation for other platforms is forthcoming. Want to see a particular platform supported? Open an [issue](https://github.com/deis/deis/issues/new) and we'll investigate.

Trying out Deis? Continue following these instructions for a local cluster setup. This is also a great Deis testing/development environment.
Deis is pre-release software. The current release is [v0.11.0](https://github.com/deis/deis/tree/v0.11.0). Until there is a stable release, we recommend you check out the latest ["master" branch](https://github.com/deis/deis) code and refer to the [latest documentation](http://docs.deis.io/en/latest/). Upgrading from a previous Deis release? See [Upgrading Deis](http://docs.deis.io/en/latest/installing_deis/upgrading-deis/) for additional information.

# Upgrading Deis
# Deploying Deis

Upgrading from a previous Deis release? See [Upgrading Deis](http://docs.deis.io/en/latest/installing_deis/upgrading-deis/) for additional information.
Deis is a set of Docker containers that can be deployed anywhere including public cloud, private cloud, bare metal or your workstation. Decide where you'd like to deploy Deis, then follow the deployment-specific documentation for [Rackspace](contrib/rackspace/README.md), [EC2](contrib/ec2/README.md), [DigitalOcean](contrib/digitalocean/README.md), [Google Compute Engine](contrib/gce/README.md) or [bare-metal](contrib/bare-metal/README.md) provisioning. Documentation for other platforms is forthcoming. Want to see a particular platform supported? Please open an [issue](https://github.com/deis/deis/issues/new).

Deis is pre-release software. The current release is [v0.11.0](https://github.com/deis/deis/tree/v0.11.0).
Until there is a stable release, we recommend you check out the latest
["master" branch](https://github.com/deis/deis) code and refer
to the [latest documentation](http://docs.deis.io/en/latest/).
Trying out Deis? Continue following these instructions for a local installation using Vagrant.

## Install prerequisites
On your workstation:

* Due to its nature as a distributed system, we strongly recommend using Deis with a minimum of 3 nodes even for local development and testing
* The Deis containers will consume approxtimately 5 GB of RAM across the cluster. Please be sure you have sufficient free memory before proceeding.
* Install [Vagrant v1.6+](http://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
* Install the fleetctl client: Install v0.8.1 from the [fleet GitHub page](https://github.com/coreos/fleet/releases/tag/v0.8.1).

A single-node cluster launched with Vagrant will consume about 5 GB of RAM on
the host machine. Please be sure you have sufficient free memory before
proceeding.
Note for Ubuntu users: the VirtualBox package in Ubuntu (as of the last known release for 14.04) has some issues when running in RAM-constrained environments. Please install the lastest version of VirtualBox from Oracle's website.

Note for Ubuntu users: the VirtualBox package in Ubuntu (as of the last known
release for 14.04) has some issues when running in RAM-constrained
environments. Please install the lastest version of VirtualBox from Oracle's
website.
## Configure Discovery

## Additional setup for a multi-node cluster
If you'd like to spin up more than one VM to test an entire cluster, there are a few additional prerequisites:
* Edit [contrib/coreos/user-data](contrib/coreos/user-data) and add a unique discovery URL generated from `https://discovery.etcd.io/new`
* Set `DEIS_NUM_INSTANCES` to the desired size of your cluster (typically 3 or 5): ```$ export DEIS_NUM_INSTANCES=3```
* If you'd like to spin up more than one router, set `DEIS_NUM_ROUTERS`: ```$ export DEIS_NUM_ROUTERS=2```
* Instead of `local.deisapp.com`, use either `local3.deisapp.com` or `local5.deisapp.com` as your cluster domain
Each time you spin up a new CoreOS cluster, you **must** provide a new [discovery service URL](https://coreos.com/docs/cluster-management/setup/cluster-discovery/) in the [CoreOS user-data](https://coreos.com/docs/cluster-management/setup/cloudinit-cloud-config/) file. This URL allows hosts to find each other and perform initial leader election.

Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
Automatically generate a fresh discovery URL with:

Deis clusters of less than 3 nodes are unsupported for anything other than local development.
```console
$ sed -i -e "s,# discovery: https://discovery.etcd.io/12345693838asdfasfadf13939923,discovery: $(curl -q -w '\n' https://discovery.etcd.io/new)," contrib/coreos/user-data
```

...or manually edit [contrib/coreos/user-data](contrib/coreos/user-data) and add a unique discovery URL generated from `https://discovery.etcd.io/new`.

## Boot CoreOS

First, start the CoreOS cluster on VirtualBox. From a command prompt, `cd` to the root of the Deis project code and type:
Start the CoreOS cluster on VirtualBox. From a command prompt, `cd` to the root of the Deis project code and type:

```console
$ export DEIS_NUM_INSTANCES=3
$ vagrant up
```

This instructs Vagrant to spin up each VM. To be able to connect to the VMs, you must add your Vagrant-generated SSH key to the ssh-agent (fleetctl tunnel requires the agent to have this key):
This instructs Vagrant to spin up 3 VMs. To be able to connect to the VMs, you must add your Vagrant-generated SSH key to the ssh-agent (`deisctl` requires the agent to have this key):

```console
$ ssh-add ~/.vagrant.d/insecure_private_key
```

Export `FLEETCTL_TUNNEL` so you can connect to the VM using the `fleetctl` client on your workstation.
## Provision Deis

Install the [deisctl utility](https://github.com/deis/deisctl#installation) used to provision and operate Deis.

```console
$ export FLEETCTL_TUNNEL=172.17.8.100
$ curl -sSL http://deis.io/deisctl/install.sh | sudo sh
```

## Optional: Build Deis

If you'd like to build Deis from source instead of using the pre-built public Dockerfiles, use `make build` to build each component from its Dockerfile. Grab some coffee while it builds the images on each VM (it can take a while).
If you're not testing code changes for Deis, it's faster just to skip to the next step.
Export `DEISCTL_TUNNEL` so you can connect to one of the VMs using the `deisctl` client on your workstation.

```console
$ make build
$ export DEISCTL_TUNNEL=172.17.8.100
```

## Run Deis

Use `make run` to start all Deis components. This can take some time - the registry service will pull and prepare a large Docker image. Grab some more coffee!
Use `deisctl install platform` to start all Deis components across the cluster. This can take some time - the registry service will pull and prepare a large Docker image, the builder service will download the Heroku cedar stack. Grab some more coffee!

```console
$ make run
$ deisctl install platform
```

Your Vagrant VM is accessible at `local.deisapp.com` (or `local3.deisapp.com`/`local5.deisapp.com`). For clusters on other platforms (EC2, Rackspace, DigitalOcean, bare metal, etc.), see our guide to [Configuring DNS](http://docs.deis.io/en/latest/installing_deis/configure-dns/).
Your Deis installation should now be accessible at `deis.local3.deisapp.com`.

For clusters on other platforms (EC2, Rackspace, DigitalOcean, bare metal, etc.), see our guide to [Configuring DNS](http://docs.deis.io/en/latest/installing_deis/configure-dns/).

## Testing the cluster

Integration tests and corresponding documentation can be found under the `test/` folder.

## Install the Deis Client

If you're using the latest Deis release, use `pip install --upgrade deis` to install the latest [Deis Client](https://pypi.python.org/pypi/deis/) or download [pre-compiled binaries](https://github.com/deis/deis/tree/master/client#get-started).

If you're working off master, precompiled binaries are likely out of date. You should either symlink the python file directly or build a local copy of the client:
Expand All @@ -106,7 +96,7 @@ $ cd client && python setup.py install
Use the Deis Client to register a new user.

```console
$ deis register http://deis.local.deisapp.com
$ deis register http://deis.local3.deisapp.com
$ deis keys:add
```

Expand All @@ -117,12 +107,12 @@ Use `deis keys:add` to add your SSH public key for `git push` access.
Initialize a `dev` cluster with a list of CoreOS hosts and your CoreOS private key.

```console
$ deis clusters:create dev local.deisapp.com --hosts=172.17.8.100 --auth=~/.vagrant.d/insecure_private_key
$ deis clusters:create dev local3.deisapp.com --hosts=172.17.8.100 --auth=~/.vagrant.d/insecure_private_key
```

The parameters to `deis clusters:create` are:
* cluster name (`dev`) - the name used by Deis to reference the cluster
* cluster hostname (`local.deisapp.com`) - the hostname under which apps are created, like `balancing-giraffe.local.deisapp.com`
* cluster hostname (`local.3deisapp.com`) - the hostname under which apps are created, like `balancing-giraffe.local3.deisapp.com`
* cluster members (`--hosts`) - a comma-separated list of cluster members -- not necessarily all members, but at least one (for cloud providers, this is a list of the IPs like `--hosts=10.21.12.1,10.21.12.2,10.21.12.3`)
* auth SSH key (`--auth`) - the SSH private key used to provision servers -- cannot have a password (for cloud providers, this key is likely `~/.ssh/deis`)

Expand Down Expand Up @@ -192,17 +182,20 @@ Use `deis run` to execute one-off commands and explore the deployed container.

Common issues that users have run into when provisioning Deis are detailed below.

#### When running a `make` action - 'Failed initializing SSH client: ssh: handshake failed: ssh: unable to authenticate'
#### When running a `deisctl` command - 'Failed initializing SSH client: ssh: handshake failed: ssh: unable to authenticate'
Did you remember to add your SSH key to the ssh-agent? `ssh-add -L` should list the key you used to provision the servers. If it's not there, `ssh-add -K /path/to/your/key`.

#### When running a `make` action - 'All the given peers are not reachable (Tried to connect to each peer twice and failed)'
The most common cause of this issue is that a [new discovery URL](https://discovery.etcd.io/new) wasn't generated and updated in [contrib/coreos/user-data](contrib/coreos/user-data) before the cluster was launched. Each Deis cluster must have a unique discovery URL, else there will be entries for old hosts that etcd will try and fail to connect to. Destroy and relaunch the cluster, ensuring to use a fresh discovery URL.
#### When running a `deisctl` command - 'All the given peers are not reachable (Tried to connect to each peer twice and failed)'
The most common cause of this issue is that a [new discovery URL](https://discovery.etcd.io/new) wasn't generated and updated in [contrib/coreos/user-data](contrib/coreos/user-data) before the cluster was launched. Each Deis cluster must have a unique discovery URL, else there will be entries for old hosts that etcd will try and fail to connect to. Trying destroying and relaunching the cluster with a fresh discovery URL.

#### Scaling an app doesn't work, and/or the app shows 'Welcome to nginx!'
This means the controller failed to submit jobs for the app to fleet. `fleetctl status deis-controller` will show detailed error information, but the most common cause of this is that the cluster was created with the wrong SSH key for the `--auth` parameter. The key supplied with the `--auth` parameter must be the same key that was used to provision the Deis servers. If you suspect this to be the issue, you'll need to `clusters:destroy` the cluster and recreate it, along with the app.
This usually means the controller failed to submit jobs to the scheduler. `deisctl journal controller` will show detailed error information, but the most common cause of this is that the cluster was created with the wrong SSH key for the `--auth` parameter. The key supplied with the `--auth` parameter must be the same key that was used to provision the Deis servers. If you suspect this to be the issue, you'll need to `clusters:destroy` the cluster and recreate it, along with the app.

#### A Deis component fails to start
Use `fleetctl status deis-<component>.service` to get the output of the service. The most common cause of services failing to start are sporadic issues with the Docker index. The telltale sign of this is:

Use `deisctl status <component>` to view the status of the component. You can also use `deisctl journal <component>` to tail logs for a component, or `deisctl list` to list all components.

The most common cause of services failing to start are sporadic issues with DockerHub. The telltale sign of this is:

```console
May 12 18:24:37 deis-3 systemd[1]: Starting deis-controller...
Expand All @@ -214,7 +207,7 @@ May 12 18:29:47 deis-3 systemd[1]: Failed to start deis-controller.
May 12 18:29:47 deis-3 systemd[1]: Unit deis-controller.service entered failed state.
```

We are exploring workarounds and are working with the Docker team to improve their index. In the meantime, try starting the service again with `fleetctl start deis-<component>.service`.
We are exploring workarounds and are working with the Docker team to improve DockerHub reliability. In the meantime, try starting the service again with `deisctl restart <component>`.

### Any other issues
Running into something not detailed here? Please [open an issue](https://github.com/deis/deis/issues/new) or hop into #deis and we'll help!
Expand Down

0 comments on commit 9267de1

Please sign in to comment.