Skip to content

Commit 816e718

Browse files
author
Matthew Fisher
committed
Merge pull request #2396 from bacongobbler/import-vagrant-docs
docs(installing_deis): import vagrant documentation
2 parents 319baa5 + 8434d05 commit 816e718

2 files changed

Lines changed: 68 additions & 182 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -12,186 +12,13 @@ Deis is pre-release software. The current release is [v0.15.1](https://github.co
1212

1313
# Deploying Deis
1414

15-
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. Want to see a particular platform supported? Please open an [issue](https://github.com/deis/deis/issues/new).
15+
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 [provider-specific documentation](http://docs.deis.io/en/latest/installing_deis/) for provisioning. Want to see a particular platform supported? Please open an [issue](https://github.com/deis/deis/issues/new).
1616

17-
Trying out Deis? Continue following these instructions for a local installation using Vagrant.
18-
19-
## Install prerequisites
20-
21-
* 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
22-
* The Deis "control plane" containers will consume approximately 2 GB of RAM across the cluster. Please be sure you have sufficient free memory before proceeding.
23-
* Install [Vagrant v1.6.5+](http://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
24-
* Deis requires CoreOS version 471.1.0 or more recent for Ceph FS support in the kernel. The Vagrantfile and cloud provider provision scripts will provision a recent CoreOS release, but manual installs need to ensure this version.
25-
26-
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 latest version of VirtualBox from Oracle's website.
27-
28-
## Configure Discovery
29-
30-
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 unique discovery URL allows hosts to find each other and perform leader election.
31-
32-
Create a user-data file with a new discovery URL this way:
33-
34-
```console
35-
$ make discovery-url
36-
```
37-
38-
Or copy [`contrib/coreos/user-data.example`](contrib/coreos/user-data.example) to `contrib/coreos/user-data` and follow the directions in the `etcd:` section to add a unique discovery URL.
39-
40-
## Boot CoreOS
41-
42-
Start the CoreOS cluster on VirtualBox. From a command prompt, `cd` to the root of the Deis project code and type:
43-
44-
```console
45-
$ export DEIS_NUM_INSTANCES=3
46-
$ vagrant up
47-
```
48-
49-
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):
50-
51-
```console
52-
$ ssh-add ~/.vagrant.d/insecure_private_key
53-
```
54-
55-
## Install deisctl
56-
57-
Install the [deisctl utility](deisctl#installation) used to provision and operate Deis.
58-
59-
```console
60-
$ curl -sSL http://deis.io/deisctl/install.sh | sh
61-
```
62-
63-
Export `DEISCTL_TUNNEL` so you can connect to one of the VMs using the `deisctl` client on your workstation.
64-
65-
```console
66-
$ export DEISCTL_TUNNEL=172.17.8.100
67-
```
68-
69-
## Configure Deis
70-
71-
Before Deis will start successfully, there are a few administrative settings we need to provide.
72-
73-
Set the default domain used to anchor your applications. For a Vagrant environment, use `local3.deisapp.com` as it will resolve to your local routers:
74-
75-
```console
76-
$ deisctl config platform set domain=local3.deisapp.com
77-
```
78-
79-
If you want to allow `deis run` for one-off admin commands, you must provide an SSH private key that allows Deis to gather container logs on CoreOS hosts:
80-
81-
```console
82-
$ deisctl config platform set sshPrivateKey=~/.vagrant.d/insecure_private_key
83-
```
84-
85-
## Provision Deis
86-
87-
Use `deisctl install platform` to install all Deis components across the cluster, then `deisctl start platform` to start them.
88-
89-
```console
90-
$ deisctl install platform
91-
$ deisctl start platform
92-
```
93-
94-
This can take some time - the **builder** must download and install the beefy Heroku cedar stack. Grab some more coffee!
95-
96-
Your Deis platform should be accessible at `deis.local3.deisapp.com`. For clusters on other platforms see our guide to [Configuring DNS](http://docs.deis.io/en/latest/managing_deis/configure-dns/#dns-records).
97-
98-
## Install the Deis Client
99-
100-
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).
101-
102-
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:
103-
104-
```console
105-
$ sudo ln -fs $(pwd)/client/deis.py /usr/local/bin/deis
106-
```
107-
or
108-
```console
109-
$ cd client && python setup.py install
110-
```
111-
112-
## Register a User
113-
114-
Use the Deis Client to register a new user.
115-
116-
```console
117-
$ deis register http://deis.local3.deisapp.com
118-
$ deis keys:add
119-
```
120-
121-
Use `deis keys:add` to add your SSH public key for `git push` access -- normally `$HOME/.ssh/id_rsa.pub`.
122-
123-
# Usage
124-
125-
Deis supports 3 deployment workflows:
126-
127-
* Heroku Buildpacks via `git push` -- Learn more about [Using Buildpacks](http://docs.deis.io/en/latest/using_deis/using-buildpacks/)
128-
* Dockerfiles via `git push` -- Learn more about [Using Dockerfiles](http://docs.deis.io/en/latest/using_deis/using-dockerfiles/)
129-
* Docker Images via `deis pull` -- Learn more about [Using Docker Images](http://docs.deis.io/en/latest/using_deis/using-docker-images/)
130-
131-
As an example, we will walk through deploying a Ruby application using the Heroku Buildpack workflow.
132-
133-
## Prepare an Application
134-
Clone an example Ruby application:
135-
136-
```console
137-
$ git clone https://github.com/deis/example-ruby-sinatra.git
138-
$ cd example-ruby-sinatra
139-
```
140-
141-
## Create an Application
142-
From within the application directory, create an application on Deis:
143-
144-
```console
145-
$ cd example-ruby-sinatra
146-
$ deis create
147-
```
148-
149-
Don't like our name-generator? Use `deis create myappname`.
150-
151-
## Deploy
152-
When you created the application, a git remote for Deis was added automatically. Deploy with `git push`.
153-
154-
```console
155-
$ git push deis master
156-
```
157-
This will use the Deis builder to package your application as a Docker Image and automatically deploy it to the platform.
158-
Each build creates a new release, which can be rolled back.
159-
160-
## Configure
161-
Configure your application with environment variables. Each config change also creates a new release.
162-
163-
```console
164-
$ deis config:set DATABASE_URL=postgres://
165-
```
166-
167-
## Test
168-
Test the application by running your test suite inside an ephemeral Docker container.
169-
170-
```console
171-
$ deis run make test
172-
```
173-
174-
Use the return code to integrate with a CI system.
175-
176-
## Scale
177-
Scale containers horizontally with ease.
178-
179-
```console
180-
$ deis scale web=8
181-
```
182-
183-
## Debug
184-
Access to aggregated logs makes it easy to troubleshoot problems with your application.
185-
186-
```console
187-
$ deis logs
188-
```
189-
190-
Use `deis run` to execute one-off commands and explore the deployed container.
17+
Trying out Deis? Please follow the documentation on [getting set up with Vagrant](http://docs.deis.io/en/latest/installing_deis/vagrant/).
19118

19219
## Testing the cluster
19320

194-
Integration tests and corresponding documentation can be found under the [`tests/`](tests/) folder.
21+
Please follow the documentation on [testing Deis](http://docs.deis.io/en/latest/contributing/testing/).
19522

19623
## Hacking on Deis
19724

‎docs/installing_deis/vagrant.rst‎

Lines changed: 65 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,72 @@
44
.. _deis_on_vagrant:
55

66
Vagrant
7-
-------
7+
=======
88

9-
The root of the Deis project includes documentation in README.md, a
10-
Makefile and a Vagrantfile to make it easy to provision a single- or
11-
multi-node Deis cluster on Vagrant_ virtual machines.
9+
`Vagrant`_ is a tool for building complete development environments with a focus on automation.
10+
This guide demonstrates how you can stand up a Deis cluster for development purposes using Vagrant.
11+
12+
13+
Install Prerequisites
14+
---------------------
15+
16+
Please install [Vagrant v1.6.5+](http://www.vagrantup.com/downloads.html) and
17+
[VirtualBox](https://www.virtualbox.org/wiki/Downloads).
18+
19+
.. note::
20+
21+
For Ubuntu users: the VirtualBox package in Ubuntu has some issues when running in RAM-constrained environments. Please install the latest version of VirtualBox from Oracle's website.
22+
23+
24+
Generate a New Discovery URL
25+
----------------------------
26+
27+
To get started with provisioning Deis, we will need to generate a new Discovery URL. Discovery URLs
28+
help connect `etcd`_ instances together by storing a list of peer addresses and metadata under a
29+
unique address. You can generate a new discovery URL for use in your platform by
30+
running the following from the root of the repository:
31+
32+
.. code-block:: console
33+
34+
$ make discovery-url
35+
36+
This will write a new discovery URL to the user-data file. Some convenience scripts are supplied in
37+
this user-data file, so it is mandatory for provisioning Deis.
38+
39+
40+
Boot CoreOS
41+
-----------
42+
43+
Start the CoreOS cluster on VirtualBox. From a command prompt, switch directories to the root of
44+
the Deis project and type:
45+
46+
.. code-block:: console
47+
48+
$ vagrant up
49+
50+
This instructs Vagrant to spin up 3 VMs. To be able to connect to the VMs, you must add your
51+
Vagrant-generated SSH key to the ssh-agent (``deisctl`` requires the agent to have this key):
52+
53+
.. code-block:: console
54+
55+
$ ssh-add ~/.vagrant.d/insecure_private_key
56+
57+
58+
Configure DNS
59+
-------------
60+
61+
For convenience, we have set up a few DNS records for users running on Vagrant.
62+
``local3.deisapp.com`` is set up for 3-node clusters and ``local5.deisapp.com`` is set up for
63+
5-node clusters. If you want to set up your own DNS records, see :ref:`configure-dns` for more
64+
information.
65+
66+
67+
Install Deis Platform
68+
---------------------
69+
70+
Now that you've finished provisioning a cluster, please refer to :ref:`install_deis_platform` to
71+
start installing the platform.
1272

13-
Please see README.md_ for details on using Deis with Vagrant.
1473

1574
.. _Vagrant: http://www.vagrantup.com/
16-
.. _README.md: https://github.com/deis/deis/tree/master/README.md
75+
.. _etcd: https://github.com/coreos/etcd

0 commit comments

Comments
 (0)