Skip to content

Commit 5f72f22

Browse files
author
Gabriel Monroy
committed
Merge pull request #85 from opdemand/66-dev-setup
Fixed #66 -- developer setup docs done.
2 parents f6a46f1 + 594d68c commit 5f72f22

1 file changed

Lines changed: 140 additions & 11 deletions

File tree

‎docs/contributing/devsetup.rst‎

Lines changed: 140 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
:title: Developer Setup
2-
:description: Developer setup instructions for contributing to the Deis project.
1+
:description: Developer setup instructions for contributing to the Deis project.
32
:keywords: deis, documentation, contributing, developer, setup, chef, knife
43

54
.. _devsetup:
@@ -30,22 +29,41 @@ To contribute code back to Deis, you must also have a GitHub.com account
3029
in order to create a pull request.
3130

3231

32+
.. _first_things_first:
33+
3334
First Things First
3435
------------------
3536

36-
You should complete all the steps outlined in :ref:`installation` and
37-
ensure your CLI and controller are functional before moving on.
37+
To work on Deis itself, first `fork the Deis repository`_ at GitHub.com.
38+
Then clone *your* repository for local development:
3839

40+
.. code-block:: console
3941
40-
Clone the Deis Cookbook
41-
-----------------------
42+
$ git clone https://github.com/<username>/deis.git
43+
$ cd deis
4244
43-
If you want to modify Deis' Chef recipes, you should also clone its
44-
repository:
4545
46-
.. code-block:: console
46+
Don't clone the official repository, but **do** complete all the other steps
47+
outlined in :ref:`installation`. Ensure your CLI and controller are functional
48+
before moving on.
4749

48-
$ git clone -q https://github.com/opdemand/deis-cookbook.git
50+
Near the end of running the ``contrib/provision-ec2-controller.sh`` script,
51+
you will see output similar to this::
52+
53+
Instance ID: i-38ad000c
54+
Flavor: m1.large
55+
Image: ami-b55ac885
56+
Region: us-west-2
57+
SSH Key: deis-controller
58+
Public DNS Name: ec2-198-51-100-36.us-west-2.compute.amazonaws.com
59+
Public IP Address: 198.51.100.36
60+
Run List: recipe[deis], recipe[deis::server], recipe[deis::gitosis],
61+
...
62+
63+
Note the **Public DNS Name** value (**ec2-198-51-100-36.us-west-2.compute.amazonaws.com**
64+
in this example). This is the Amazon EC2 instance that runs
65+
your Deis controller software, and ultimately this is where you will test
66+
any changes you make to the Deis codebase.
4967

5068

5169
Make a Virtualenv
@@ -81,12 +99,123 @@ Modify Code and Test
8199
--------------------
82100

83101
When changing Python code in the Deis project, keep in mind our :ref:`standards`.
102+
Specifically, when you change local code, you must run
103+
``make flake8 && make coverage``, then check the HTML report to see
104+
that test coverage has improved as a result of your changes and new unit tests.
105+
106+
.. code-block:: console
107+
108+
$ make flake8
109+
flake8
110+
./api/models.py:17:1: F401 'Group' imported but unused
111+
./api/models.py:81:1: F841 local variable 'result' is assigned to but never used
112+
make: *** [flake8] Error 1
113+
$
114+
$ make coverage
115+
coverage run manage.py test api celerytasks client web
116+
Creating test database for alias 'default'...
117+
...................ss
118+
----------------------------------------------------------------------
119+
Ran 21 tests in 18.135s
120+
121+
OK (skipped=2)
122+
Destroying test database for alias 'default'...
123+
coverage html
124+
$ head -n 25 htmlcov/index.html | grep pc_cov
125+
<span class='pc_cov'>81%</span>
126+
127+
128+
Test on Your Controller
129+
-----------------------
130+
131+
Since you completed the steps outlined in :ref:`first_things_first`, you have
132+
a working Deis controller. Start a remote shell on the controller as the
133+
"ubuntu" user:
134+
135+
.. code-block:: console
136+
137+
$ ssh -i $HOME/.ssh/deis-controller ubuntu@ec2-198-51-100-36.us-west-2.compute.amazonaws.com
138+
Welcome to Ubuntu 12.04.2 LTS (GNU/Linux 3.8.0-26-generic x86_64)
139+
140+
ubuntu@ip-198-51-100-36:~$
141+
$ status deis-server
142+
deis-server start/running, process 12040
143+
$ cd /opt/deis
144+
$ sudo -u deis mv controller controller.opdemand
145+
$ # clone my fork of the official Deis repo
146+
$ sudo -u deis git clone https://github.com/<username>/deis.git controller
147+
Cloning into 'controller'...
148+
remote: Counting objects: 2067, done.
149+
remote: Compressing objects: 100% (1007/1007), done.
150+
remote: Total 2067 (delta 951), reused 2064 (delta 948)
151+
Receiving objects: 100% (2067/2067), 1.01 MiB | 924 KiB/s, done.
152+
Resolving deltas: 100% (951/951), done.
153+
$ ls
154+
build controller controller.opdemand gitosis prevent-apt-update
155+
$ cd controller
156+
$ sudo -u deis cp controller.opdemand/deis/local_settings.py controller/deis/
157+
$ sudo -u deis cp controller.opdemand/.secret_key controller/
158+
$ sudo -u deis cp -r controller.opdemand/venv controller/
159+
$ sudo restart deis-server
160+
deis-server start/running, process 12901
161+
162+
You have now restarted the Deis controller from your fork of the codebase.
163+
164+
Testing now involves exercising the relevant code paths in full round-trip
165+
mode by using the ``deis`` client on your workstation. You can get detailed
166+
output by editing the deis/local_settings.py file and set DEBUG=True,
167+
restarting the server, and watching logs:
168+
169+
.. code-block:: console
170+
171+
$ sudo restart deis-server
172+
deis-server start/running, process 14074
173+
$ tail -f /var/log/deis/*.log
174+
==> /var/log/deis/access.log <==
175+
176+
==> /var/log/deis/celeryd.log <==
177+
[2013-08-13 16:59:33,426: WARNING/MainProcess] celery@ip-198-51-100-36 ready.
178+
[2013-08-13 16:59:33,451: INFO/MainProcess] consumer: Connected to amqp://guest@127.0.0.1:5672//.
179+
180+
==> /var/log/deis/server.log <==
181+
2013-08-13 23:29:09 [14019] [INFO] Handling signal: term
182+
2013-08-13 23:29:09 [14019] [INFO] Shutting down: Master
183+
2013-08-13 23:29:12 [14074] [INFO] Starting gunicorn 17.5
184+
2013-08-13 23:29:12 [14074] [DEBUG] Arbiter booted
185+
2013-08-13 23:29:12 [14074] [INFO] Listening at: http://0.0.0.0:8000 (14074)
186+
2013-08-13 23:29:12 [14074] [INFO] Using worker: gevent
187+
2013-08-13 23:29:12 [14079] [INFO] Booting worker with pid: 14079
188+
189+
190+
Make a Pull Request
191+
-------------------
192+
193+
Please create a GitHub `pull request`_ for any code changes that will benefit Deis users
194+
in general. This workflow helps changesets map well to discrete features.
195+
196+
Creating a pull request on the Deis repository also runs a `Travis CI`_ build to
197+
ensure the pull request doesn't break any tests or reduce code coverage.
198+
199+
200+
Clone the Deis Cookbook
201+
-----------------------
202+
203+
If you want to modify Deis' Chef recipes, you should also clone the `deis-cookbook`_
204+
repository:
205+
206+
.. code-block:: console
207+
208+
$ git clone -q https://github.com/opdemand/deis-cookbook.git
84209
85-
** More to come... **
210+
Please see `deis-cookbook`_ for information about contributing Chef code to Deis.
86211

87212

88213
.. _`virtualenv documentation`: http://www.virtualenv.org/en/latest/
89214
.. _`Python`: http://python.org/
90215
.. _`Ruby`: http://ruby-lang.org/
91216
.. _`Amazon EC2 API Tools`: http://aws.amazon.com/developertools/Amazon-EC2/351
92217
.. _`Knife EC2 plugin`: https://github.com/opscode/knife-ec2
218+
.. _`fork the Deis repository`: https://github.com/opdemand/deis/fork
219+
.. _`deis-cookbook`: https://github.com/opdemand/deis-cookbook
220+
.. _`pull request`: https://github.com/opdemand/deis/pulls
221+
.. _`Travis CI`: https://travis-ci.org/

0 commit comments

Comments
 (0)