Skip to content

Commit f2e8117

Browse files
author
Gabriel Monroy
committed
docs(hacking): new docs for hacking on deis
1 parent 9267de1 commit f2e8117

3 files changed

Lines changed: 212 additions & 264 deletions

File tree

‎docs/contributing/hacking.rst‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
:description: How to hack on Deis including setup instructions
2+
3+
.. _hacking:
4+
5+
Hacking on Deis
6+
===============
7+
8+
We try to make it simple to hack on Deis. However, there are necessarily several moving
9+
pieces and some setup required. We welcome any suggestions for automating or simplifying
10+
this process.
11+
12+
If you're just getting into the Deis codebase, look for GitHub issues with the label
13+
`easy-fix`_. These are more straightforward or low-risk issues and are a great way to
14+
become more familiar with Deis.
15+
16+
Prerequisites
17+
-------------
18+
19+
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.
21+
22+
The development workflow requires a Docker Registry that is accessible to you
23+
(the developer) and to all of the hosts in your cluster.
24+
25+
You will also need a `deisctl`_ client to update images and restart components.
26+
27+
Fork the Repository
28+
-------------------
29+
30+
To get Deis running for development, first `fork the Deis repository`_,
31+
then clone your fork of the repository:
32+
33+
.. code-block:: console
34+
35+
$ git clone git@github.com:<username>/deis.git
36+
$ cd deis
37+
$ export DEIS_DIR=`pwd` # to use in future commands
38+
39+
Install the Client
40+
------------------
41+
42+
In a development environment you'll want to use the latest version of the client. Install
43+
its dependencies by using the Makefile and symlinking ``client/deis.py`` to ``deis`` on
44+
your local workstation.
45+
46+
.. code-block:: console
47+
48+
$ cd $DEIS_DIR/client
49+
$ make install
50+
$ sudo ln -fs $DEIS_DIR/client/deis.py /usr/local/bin/deis
51+
$ deis
52+
Usage: deis <command> [<args>...]
53+
54+
Configure SSH Tunneling
55+
-----------------------
56+
57+
To connect to the cluster using ``deisctl``, you must add the private key to ``ssh-agent``.
58+
For example, when using Vagrant:
59+
60+
.. code-block:: console
61+
62+
$ ssh-add ~/.vagrant.d/insecure_private_key
63+
64+
Set ``DEISCTL_TUNNEL`` so the ``deisctl`` client on your workstation can connect to
65+
one of the hosts in your cluster:
66+
67+
.. code-block:: console
68+
69+
$ export DEISCTL_TUNNEL=172.17.8.100
70+
71+
Test connectivity using ``deisctl list``:
72+
73+
.. code-block:: console
74+
75+
$ deisctl list
76+
77+
Configure a Docker Registry
78+
---------------------------
79+
80+
The development workflow requires Docker Registry set at the ``DEIS_REGISTRY``
81+
environment variable. If you're developing locally you can use the ``dev-registry``
82+
target to spin up a quick, disposable registry inside a Docker container.
83+
84+
.. code-block:: console
85+
86+
$ make dev-registry
87+
88+
To configure the registry for local Deis development:
89+
export DEIS_REGISTRY=192.168.59.103:5000
90+
91+
If you are developing elsewhere, you must setup the registry yourself.
92+
Make sure it meets the following requirements:
93+
94+
#. You can push Docker images from your workstation
95+
#. Hosts in the cluster can pull images with the same URL
96+
97+
Development Workflow
98+
--------------------
99+
100+
Deis includes ``Makefile`` targets designed to simplify the development workflow.
101+
This workflow is typically:
102+
103+
#. Update source code and commit your changes using ``git``
104+
#. Use ``make -C <component> build`` to build a new Docker Image
105+
#. Use ``make -C <component> push`` to push the image and start using it
106+
#. Use ``make -C <component> restart`` to restart the component
107+
108+
This can be shortened to a one-liner:
109+
110+
.. code-block:: console
111+
112+
$ make -C controller build push restart
113+
114+
You can also use the same tasks on the root ``Makefile`` to operate on all
115+
components at once. For example, ``make build push restart`` will build, push
116+
and restart all components on the cluster.
117+
118+
.. important::
119+
120+
In order to push a new image, you must commit changes using ``git`` to increment
121+
the SHA used when tagging Docker images
122+
123+
Test Your Changes
124+
-----------------
125+
126+
Deis ships with a comprehensive suite of automated tests, most written in Go.
127+
You can find instructions for `running the tests`_ under the ``tests/`` directory.
128+
129+
Useful Commands
130+
---------------
131+
132+
Once your controller is running, here are some helpful commands.
133+
134+
Tail Logs
135+
`````````
136+
137+
.. code-block:: console
138+
139+
$ deisctl journal controller
140+
141+
Rebuild Services from Source
142+
````````````````````````````
143+
144+
.. code-block:: console
145+
146+
$ make -C controller build push restart
147+
148+
Restart Services
149+
````````````````
150+
151+
.. code-block:: console
152+
153+
$ make -C controller restart
154+
155+
Django Shell
156+
````````````
157+
158+
.. code-block:: console
159+
160+
$ deisctl ssh controller # SSH into the controller
161+
$ nse deis-controller # inject yourself into the container
162+
$ cd /app # change into the django project root
163+
$ ./manage.py shell # get a django shell
164+
165+
Have commands other Deis developers might find useful? Send us a PR!
166+
167+
Standards & Test Coverage
168+
-------------------------
169+
170+
When changing Python code in the Deis project, keep in mind our :ref:`standards`.
171+
Specifically, when you change local code, you must run ``make flake8 && make coverage``,
172+
then check the HTML report to see that test coverage has improved as a result of your
173+
changes and new unit tests.
174+
175+
.. code-block:: console
176+
177+
$ make flake8
178+
flake8
179+
./api/models.py:17:1: F401 'Group' imported but unused
180+
./api/models.py:81:1: F841 local variable 'result' is assigned to but never used
181+
make: *** [flake8] Error 1
182+
$
183+
$ make coverage
184+
coverage run manage.py test --noinput api web
185+
WARNING Cannot synchronize with etcd cluster
186+
Creating test database for alias 'default'...
187+
...............................................
188+
----------------------------------------------------------------------
189+
Ran 47 tests in 47.768s
190+
191+
OK
192+
Destroying test database for alias 'default'...
193+
coverage html
194+
$ head -n 25 htmlcov/index.html | grep pc_cov
195+
<span class='pc_cov'>81%</span>
196+
197+
Pull Requests
198+
-------------
199+
200+
Please create a GitHub `pull request`_ for any code changes that will benefit Deis users
201+
in general. This workflow helps changesets map well to discrete features.
202+
203+
Creating a pull request on the Deis repository also runs an integration test on
204+
http://ci.deis.io to ensure the pull request doesn't break any tests or reduce code
205+
coverage.
206+
207+
.. _`easy-fix`: https://github.com/deis/deis/issues?labels=easy-fix&state=open
208+
.. _`deisctl`: https://github.com/deis/deisctl
209+
.. _`fork the Deis repository`: https://github.com/deis/deis/fork
210+
.. _`running the tests`: https://github.com/deis/deis/tree/master/tests#readme
211+
.. _`pull request`: https://github.com/deis/deis/pulls

‎docs/contributing/index.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,8 @@ Contributing
1111

1212

1313
overview
14-
localdev
14+
hacking
1515
standards
1616
community
1717
conduct
1818
releases
19-

0 commit comments

Comments
 (0)