Skip to content

Commit a62a315

Browse files
technosophostechnosophos
committed
docs(hacking, aws): Update to latest installation process.
As I went through the process of configuring my workstation, I updated the documentation accordingly.
1 parent daa4e69 commit a62a315

2 files changed

Lines changed: 278 additions & 40 deletions

File tree

‎docs/contributing/hacking.rst‎

Lines changed: 258 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,15 @@
55
Hacking on Deis
66
===============
77

8+
This document is for developers who are interested in working directly on the
9+
Deis codebase. In this guide, we walk you through the process of setting up
10+
a local development environment. While there are many ways to set up your
11+
Deis environment, this document covers a specific setup:
12+
13+
- Developing on **Mac OSX** or **Linux**
14+
- Managing virtualization with **Vagrant/Virtualbox**
15+
- Hosting a docker registry with **Boot2Docker** (Mac)
16+
817
We try to make it simple to hack on Deis. However, there are necessarily several moving
918
pieces and some setup required. We welcome any suggestions for automating or simplifying
1019
this process.
@@ -17,15 +26,39 @@ Prerequisites
1726
-------------
1827

1928
You can develop on any supported platform including your laptop, cloud providers or
20-
on bare metal. We strongly recommend a minimum 3-node cluster.
29+
on bare metal. We strongly recommend a minimum 3-node cluster. We strongly
30+
suggest using Vagrant and VirtualBox for your virtualization layer during
31+
development.
32+
33+
At a glance, you will need:
34+
35+
- Python 2.7 or later (with ``pip``)
36+
- virtualenv (``sudo pip install virtualenv``)
37+
- Go 1.4 or later, with support for compiling to ``linux/amd64``
38+
- Godep (https://github.com/tools/godep)
39+
- VirtualBox latest
40+
- Vagrant 1.5 or later
41+
- On Mac, you will also want
42+
- Boot2Docker
2143

22-
Deis is written in both python and Go, so you will need to install both Python 2.7 and
23-
the latest version of Go.
44+
In most cases, you should simply install according to the instructions. There
45+
are a few special cases, though. We cover these below.
46+
47+
Configuring Go
48+
``````````````
2449

2550
If your local workstation does not support the linux/amd64 target environment, you will
2651
have to install Go from source with cross-compile support for that environment. This is
2752
because some of the components are built on your local machine and then injected into a
28-
docker container. To do that, run
53+
docker container.
54+
55+
Homebrew users can just install with cross compiling support:
56+
57+
.. code-block:: console
58+
59+
$ brew install go --with-cc-common
60+
61+
It is also straightforward to build Go from source:
2962

3063
.. code-block:: console
3164
@@ -36,41 +69,127 @@ docker container. To do that, run
3669
$ ./make.bash --no-clean
3770
$ GOOS=linux GOARCH=amd64 ./make.bash --no-clean
3871
39-
After that, you should be able to compile Deis' components as normal.
72+
Once you can compile to ``linux/amd64``, you should be able to compile Deis'
73+
components as normal.
74+
75+
Configuring Boot2Docker (Mac)
76+
`````````````````````````````
77+
78+
Deis needs a Docker registry running independently of the Deis cluster. On
79+
OS X, you will need to run this docker registry inside of Boot2Docker (http://boot2docker.io).
80+
81+
Install Boot2Docker according to the normal installation instructions. When you
82+
run ``init``, we highly recommend allocating a large disk, since the Docker
83+
registry that will live there is fairly large.
84+
85+
.. code-block:: console
86+
87+
$ boot2docker init --disksize=100000
88+
89+
That will create virtual disk that can eventually take up a full 100,000MB of
90+
disk space. Then start up Boot2Docker.
91+
92+
Once you have run ``boot2docker up``, you should be able to connect to it. You
93+
need to make a minor editor to the boot2docker config:
94+
95+
.. code-block:: console
96+
97+
$ boot2docker ip
98+
192.168.59.103
99+
$ boot2docker ssh sudo vi /var/lib/boot2docker/profile
100+
101+
Inside of the profile, you need to add one line, making sure to set the IP
102+
address to whatever ``boot2docker ip`` printed.
103+
104+
.. code-block:: console
105+
106+
EXTRA_ARGS="--insecure-registry 192.168.59.103:5000"
107+
108+
Once that line has been added, you can either restart boot2docker's docker
109+
server, or you can restart boot2docker. We recommend the latter.
40110

41-
The development workflow requires a Docker Registry that is accessible to you
42-
(the developer) and to all of the hosts in your cluster.
111+
.. code-block:: console
112+
113+
$ boot2docker halt
114+
$ boot2docker up
43115
44-
You will also need a `deisctl`_ client to update images and restart components.
116+
At this point, Boot2Docker can now serve as a registry for Deis' Docker images.
117+
Later on we will return to this.
45118

46-
Fork the Repository
47-
-------------------
119+
Fork the Deis Repository
120+
------------------------
121+
Once the prerequisites have been met, we can begin to work with Deis.
48122

49123
To get Deis running for development, first `fork the Deis repository`_,
50-
then clone your fork of the repository:
124+
then clone your fork of the repository. Since Deis is predominantly written
125+
in Go, the best place to put it is in ``$GOPATH/src/github.com/deis/``
51126

52127
.. code-block:: console
53128
54-
$ git clone git@github.com:<username>/deis.git
55-
$ cd deis
129+
$ mkdir -p $GOPATH/src/github.com/deis
130+
$ cd $GOPATH/src/github.com/deis
131+
$ git clone git@github.com:<username>/deis.git
132+
$ cd deis
56133
57-
Install the Client
58-
------------------
134+
.. note::
59135

60-
Your Deis client should match your server's version. For developers, one way
61-
to ensure this is to use `Python 2.7`_ to install requirements and then run
62-
``client/deis.py`` in the Deis code repository. Then make a symlink or shell
63-
alias for ``deis`` to ensure it is found in your ``$PATH``:
136+
By checking out the forked copy into the namespace ``github.com/deis/deis``,
137+
we are tricking the Go toolchain into seeing our fork as the "official"
138+
Deis tree.
139+
140+
If you are going to be issuing pull requests and working with official Deis
141+
repository, we suggest configuring Git accordingly. There are various strategies
142+
for doing this, but the `most common`_ is to add an ``upstream`` remote:
64143

65144
.. code-block:: console
66145
67-
$ make -C client/ install
68-
$ sudo ln -fs $(pwd)/client/deis.py /usr/local/bin/deis
69-
$ deis
70-
Usage: deis <command> [<args>...]
146+
$ git remote add upstream https://github.com/deis/deis.git
71147
72-
Configure SSH Tunneling
73-
-----------------------
148+
For the sake of simplicity, you may want to point an environment variable to
149+
your Deis code:
150+
151+
.. code-block:: console
152+
153+
export DEIS=$GOPATH/src/github.com/deis/deis
154+
155+
Throughout the rest of this document, ``$DEIS`` refers to that location.
156+
157+
Alternative: Forking with a Pushurl
158+
```````````````````````````````````
159+
A number of Deis developers prefer to pull directly from ``deis/deis``, but
160+
push to ``<username>/deis``. If that workflow suits you better, you can set it
161+
up this way:
162+
163+
.. code-block:: console
164+
165+
$ git clone git@github.com:deis/deis.git
166+
$ cd deis
167+
$ git config remote.origin.pushurl git@github.com:<username>/deis.git
168+
169+
In this setup, fetching and pulling code will work directly with the upstream
170+
repository, while pushing code will send changes to your fork. This makes it
171+
easy to stay up to date, but also make changes and then issue pull requests.
172+
173+
Build Deisctl
174+
-------------
175+
176+
Deisctl is used for interacting with the Deis cluster. While you can use an
177+
existing ``deisctl`` build, we recommend that developers build it from source.
178+
179+
.. code-block:: console
180+
181+
$ cd $DEIS/deisctl
182+
$ make build
183+
$ make install # optionally
184+
185+
This will build just the ``deisctl`` portion of Deis. Running ``make install`` will
186+
install the ``deisctl`` command in ``$GOPATH/bin/deisctl``.
187+
188+
You can verify that ``deisctl`` is correctly built and installed by running
189+
``deisctl -h``. That should print the help text and exit.
190+
191+
Configure SSH Tunneling for Deisctl
192+
-----------------------------------
74193

75194
To connect to the cluster using ``deisctl``, you must add the private key to ``ssh-agent``.
76195
For example, when using Vagrant:
@@ -86,22 +205,98 @@ one of the hosts in your cluster:
86205
87206
$ export DEISCTL_TUNNEL=172.17.8.100
88207
89-
Test connectivity using ``deisctl list``:
208+
.. note::
209+
210+
A number of times during this setup, tools will suggest that you export various
211+
environment variables. You may find it convenient to store these in your shell's
212+
RC file (`~/.bashrc` or `~/.zshrc`).
213+
214+
Install the Deis Client
215+
-----------------------
216+
217+
Unlike ``deisctl``, the ``deis`` client is written in Python.
218+
219+
Your Deis client should match your server's version. For developers, one way
220+
to ensure this is to use `Python 2.7`_ to install requirements and then run
221+
``client/deis.py`` in the Deis code repository. Then make a symlink or shell
222+
alias for ``deis`` to ensure it is found in your ``$PATH``. The example
223+
below shows the simplest way to install ``deis.py`` as ``deis``.
224+
225+
.. note::
226+
227+
On OSX, you must have the XCode command line utilities installed. If you
228+
see errors about `ffi`, try installing or reinstalling the XCode command
229+
line tools.
230+
231+
From the root of the ``deis`` repository, run the appropriate ``make`` command:
90232

91233
.. code-block:: console
92234
93-
$ deisctl list
235+
$ cd $DEIS
236+
$ make -C client/ install
237+
$ sudo ln -fs $(pwd)/client/deis.py /usr/local/bin/deis
238+
$ deis
239+
Usage: deis <command> [<args>...]
240+
241+
This will fetch all of the dependencies. If one of your system Python libraries
242+
is out of date, you may prefer to ``cd`` into ``client`` and run
243+
``pip install --upgrade .`` to fetch the latest dependencies.
94244

95245
Start Up a Development Cluster
96246
------------------------------
97247

98-
To start up and configure a local vagrant cluster for development, you can use the ``dev-cluster`` target.
99-
This requires that ``deisctl`` and ``vagrant`` are installed.
248+
Our host system is now configured for controlling a Deis cluster. The next
249+
thing to do is begin standing up a development cluster.
250+
251+
When developing locally, we want deisctl to check our local unit files so that
252+
any changes are reflected in our Deis cluster. The easiest way to do this is
253+
to set an environment variable telling deisctl where to look. Assuming
254+
the variable ``$DEIS`` points to the location if the deis source code, we want
255+
something like this:
256+
257+
.. code-block:: console
258+
259+
export DEISCTL_UNITS=$DEIS/deisctl/units
260+
261+
To start up and configure a local vagrant cluster for development, you can use
262+
the ``dev-cluster`` target.
100263

101264
.. code-block:: console
102265
103266
$ make dev-cluster
104267
268+
This may take a while to run the first time. At the end of the process, you
269+
will be prompted to run ``deis start platform``. Hold off on that task for now.
270+
We will come back to it later.
271+
272+
To verify that the cluster is running, you should be able to connect
273+
to the nodes on your Deis cluster:
274+
275+
.. code-block:: console
276+
277+
$ vagrant status
278+
Current machine states:
279+
280+
deis-01 running (virtualbox)
281+
deis-02 running (virtualbox)
282+
deis-03 running (virtualbox)
283+
284+
$ vagrant ssh deis-01
285+
Last login: Tue Jun 2 18:26:30 2015 from 10.0.2.2
286+
* * * ***** ddddd eeeeeee iiiiiii ssss
287+
* * * * * * d d e e i s s
288+
* * ***** ***** d d e i s
289+
***** * * * d d e i s
290+
* * * * * * d d eee i sss
291+
***** * * ***** d d e i s
292+
* ***** * * d d e i s
293+
* * * * * * d d e e i s s
294+
***** ***** * * ddddd eeeeeee iiiiiii ssss
295+
296+
Welcome to Deis Powered by CoreOS
297+
298+
With a dev cluster now running, we are ready to set up a local Docker registry.
299+
105300
Configure a Docker Registry
106301
---------------------------
107302

@@ -118,14 +313,12 @@ otherwise, use your host's IP address as returned by ``ifconfig`` with port 5000
118313
To configure the registry for local Deis development:
119314
export DEV_REGISTRY=192.168.59.103:5000
120315
121-
.. note::
316+
It is important that you export the ``DEV_REGISTRY`` variable as instructed.
122317

123-
For Docker 1.3.1 and later, ``docker push`` to this development registry may fail
124-
without SSL certificate support. Restart docker with an ``--insecure-registry`` flag.
318+
.. note::
125319

126-
For ``boot2docker`` 1.3.1 for example, add
127-
``EXTRA_ARGS="--insecure-registry 192.168.59.103:5000"`` to
128-
/var/lib/boot2docker/profile and restart docker with ``sudo /etc/init.d/docker restart``.
320+
If you are using Boot2Docker, make sure you set the ``EXTRA_ARGS`` as
321+
explained in the prerequisites. Otherwise your registry will not work.
129322

130323
If you are developing elsewhere, you must set up a registry yourself.
131324
Make sure it meets the following requirements:
@@ -139,10 +332,39 @@ Make sure it meets the following requirements:
139332
``172.16.0.0/12``, or ``192.168.0.0/16``, you'll have to modify ``contrib/coreos/user-data.example``
140333
and whitelist your development registry so the daemons can pull your custom components.
141334

335+
Initial Platform Build
336+
----------------------
337+
338+
The full environment is prepared. You can now build Deis from source code and
339+
then run the platform.
340+
341+
We'll do three steps together:
342+
343+
- Build the source (``make build``)
344+
- Update our local cluster with a dev release (``make dev-release``)
345+
- Start the platform (``deisctl start platform``)
346+
347+
Conveniently, we can accomplish all three in one step:
348+
349+
.. code-block:: console
350+
351+
$ make deploy
352+
353+
354+
Running ``deisctl list`` should display all of the services that your Deis
355+
cluster is currently running.
356+
357+
You can now use your Deis cluster in all of the usual ways.
358+
359+
At this point, you are running Deis from the code in your Git clone. But since
360+
rebuilding like this is time consuming, Deis has a simplified developer
361+
workflow more suited to daily development.
362+
142363
Development Workflow
143364
--------------------
144365

145366
Deis includes ``Makefile`` targets designed to simplify the development workflow.
367+
146368
This workflow is typically:
147369

148370
#. Update source code and commit your changes using ``git``
@@ -222,3 +444,4 @@ when proposing a change to Deis.
222444
.. _`Python 2.7`: https://www.python.org/downloads/release/python-279/
223445
.. _`running the tests`: https://github.com/deis/deis/tree/master/tests#readme
224446
.. _`pull request`: https://github.com/deis/deis/pulls
447+
.. _`most common`: https://help.github.com/articles/fork-a-repo/

0 commit comments

Comments
 (0)