| description: | Local development setup instructions for contributing to the Deis project. |
|---|
We try to make it simple to hack on Deis, but as an open PaaS, there are necessarily several moving pieces and some setup required. We welcome any suggestions for automating or simplifying this process.
We strongly recommend using Vagrant with VirtualBox so you can develop inside a set of isolated virtual machines. You will need:
- Vagrant 1.5.1+
- VirtualBox 4.2+
To get Deis running locally, first fork the Deis repository, then clone your fork of the repository for local development:
$ git clone git@github.com:<username>/deis.git
$ cd deis
$ export DEIS_DIR=`pwd` # to use in future commandsFirst bring up a virtual machine to host Deis. To share your local codebase into the CoreOS VM, Deis uses NFS mounts, so you will be prompted for an administrative password.
$ vagrant up
Bringing machine 'deis' up with 'virtualbox' provider...
==> deis: Importing base box 'coreos-alpha'...
...
==> deis: Exporting NFS shared folders...
==> deis: Preparing to edit /etc/exports. Administrator privileges will be required...
Password:
==> deis: Mounting NFS shared folders...
...
==> deis: Running provisioner: shell...
deis: Running: inline script
$Set environment variables to have the docker and fleetctl clients on your workstation connect to the VM:
export DOCKER_HOST=tcp://172.17.8.100:4243
export FLEETCTL_TUNNEL=172.17.8.100Next, run make pull && make build to SSH into the VM, pull Deis'
images from the Docker Index, then update those images with any local
changes.
$ make pull
vagrant ssh -c 'for c in registry logger database cache controller \
builder router; do docker pull deis/$c; done'
Pulling repository deis/registry
d2c347aa26dd: Pulling dependent layers
511136ea3c5a: Download complete
6170bb7b0ad1: Download complete
79fdb1362c84: Downloading [====>
...
e5efa1477310: Download complete
Connection to 127.0.0.1 closed.
$ make build
vagrant ssh -c 'cd share && for c in registry logger database \
cache controller builder router; \
do cd $c && docker build -t deis/$c . && cd ..; done'
Uploading context 22.53 kB
Uploading context
Step 0 : FROM deis/base:latest
Pulling repository deis/base
60024338bc63: Download complete
...
Step 12 : CMD ["/app/bin/boot"]
---> Running in ccdc3d283f4f
---> cf4b7a398500
Removing intermediate container ccdc3d283f4f
Successfully built cf4b7a398500
Connection to 127.0.0.1 closed.Finally, do make run to start all Deis containers and displays their
collected log output:
$ make run
vagrant ssh -c 'cd share && for c in registry logger database \
cache controller builder router; \
do cd $c && sudo systemctl enable $(pwd)/systemd/* && cd ..; done'
ln -s '/home/core/share/registry/systemd/deis-registry.service' \
'/etc/systemd/system/multi-user.target.wants/deis-registry.service'
...
Apr 15 18:53:23 deis sh[9101]: 2014-04-15 12:53:23 [149] [INFO] Booting worker with pid: 149
Apr 15 18:53:24 deis sh[9101]: [2014-04-15 12:53:24,842: INFO/MainProcess] mingle: all alone
Apr 15 18:53:24 deis sh[9101]: [2014-04-15 12:53:24,852: WARNING/MainProcess] celery@121f56ff9ae5 ready.In a development environment you'll want to use the latest version of the client. Install
its dependencies by using the Makefile and symlinking client/deis.py to deis on
your local workstation.
$ cd $DEIS_DIR/client
$ make install
$ ln -fs $DEIS_DIR/client/deis.py /usr/local/bin/deis
$ deis
Usage: deis <command> [<args>...]Use the Deis client to register a new user on the controller. As the first user, you will receive full admin permissions.
$ deis register http://local.deisapp.com:8000
username: myuser
password:
password (confirm):
email: myuser@example.com
Registered myuser
Logged in as myuserNote
As of v0.5.1, the proxy was removed for Deis platform services. It has yet to be added back in. See issue 535 for more details.
As a workaround, use the following:
deis register http://local.deisapp.com:8000
Once the user is registered, add your SSH key for git push
access using:
$ deis keys:add
Found the following SSH public keys:
1) id_rsa.pub
Which would you like to use with Deis? 1
Uploading /Users/myuser/.ssh/id_rsa.pub to Deis... doneYour local development environment is running! Follow the rest of the :ref:`Developer Guide <developer>` to deploy your first application.
Once your controller is running, here are some helpful commands.
$ vagrant ssh -c 'sudo docker logs --follow=true deis-controller'$ vagrant ssh -c 'sudo restart deis-controller'$ vagrant ssh # SSH into the controller
$ sudo su deis -l # change to deis user
$ cd controller # change into the django project root
$ source venv/bin/activate # activate python virtualenv
$ ./manage.py shell # get a django shellHave commands other Deis developers might find useful? Send us a PR!
When changing Python code in the Deis project, keep in mind our :ref:`standards`.
Specifically, when you change local code, you must run
make flake8 && make coverage, then check the HTML report to see
that test coverage has improved as a result of your changes and new unit tests.
$ make flake8
flake8
./api/models.py:17:1: F401 'Group' imported but unused
./api/models.py:81:1: F841 local variable 'result' is assigned to but never used
make: *** [flake8] Error 1
$
$ make coverage
coverage run manage.py test api celerytasks client web
Creating test database for alias 'default'...
...................ss
----------------------------------------------------------------------
Ran 21 tests in 18.135s
OK (skipped=2)
Destroying test database for alias 'default'...
coverage html
$ head -n 25 htmlcov/index.html | grep pc_cov
<span class='pc_cov'>81%</span>Please create a GitHub pull request for any code changes that will benefit Deis users in general. This workflow helps changesets map well to discrete features.
Creating a pull request on the Deis repository also runs a Travis CI build to ensure the pull request doesn't break any tests or reduce code coverage.