Skip to content

Commit 87159d5

Browse files
author
Gabriel Monroy
committed
docs(developer): flesh out developer docs
1 parent 3d5d243 commit 87159d5

11 files changed

Lines changed: 445 additions & 278 deletions

‎controller/web/static/css/main.css‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/developer/buildpack.rst‎

Lines changed: 0 additions & 68 deletions
This file was deleted.

‎docs/developer/config-application.rst‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
:title: Configure an Application on Deis
2+
:description: Instructions for developers using Deis to configure applications.
3+
4+
.. _config-application:
5+
6+
Configure an Application
7+
========================
8+
A Deis application `stores config in environment variables`_.
9+
10+
Configure the Application
11+
-------------------------
12+
Use ``deis config`` to modify environment variables for a deployed application.
13+
14+
.. code-block:: console
15+
16+
$ deis help config
17+
Valid commands for config:
18+
19+
config:list list environment variables for an app
20+
config:set set environment variables for an app
21+
config:unset unset environment variables for an app
22+
23+
Use `deis help [command]` to learn more
24+
25+
When config is changed, a new release is created and deployed automatically.
26+
27+
Attach to Backing Services
28+
--------------------------
29+
Deis treats backing services like databases, caches and queues as `attached resources`_.
30+
Attachments are performed using environment variables.
31+
32+
For example, use ``deis config`` to set a `DATABASE_URL` that attaches
33+
the application to an external PostgreSQL database.
34+
35+
.. code-block:: console
36+
37+
$ deis config:set DATABASE_URL=postgres://user:pass@example.com:5432/db
38+
=== peachy-waxworks
39+
DATABASE_URL: postgres://user:pass@example.com:5432/db
40+
41+
Detachments can be performed with ``deis config:unset``.
42+
43+
Track Changes
44+
-------------
45+
Each time a build or config change is made to your application, a new :ref:`release` is created.
46+
Track changes to your application using ``deis releases``.
47+
48+
.. code-block:: console
49+
50+
$ deis releases
51+
=== peachy-waxworks Releases
52+
v4 3 minutes ago gabrtv deployed d3ccc05
53+
v3 1 hour 17 minutes ago gabrtv added DATABASE_URL
54+
v2 6 hours 2 minutes ago gabrtv deployed 7cb3321
55+
v1 6 hours 2 minutes ago gabrtv deployed deis/helloworld
56+
57+
Rollback the Application
58+
------------------------
59+
Use ``deis rollback`` to revert to a previous release.
60+
61+
.. code-block:: console
62+
63+
$ deis rollback v2
64+
Rolled back to v2
65+
66+
$ deis releases
67+
=== folksy-offshoot Releases
68+
v5 Just now gabrtv rolled back to v2
69+
v4 4 minutes ago gabrtv deployed d3ccc05
70+
v3 1 hour 18 minutes ago gabrtv added DATABASE_URL
71+
v2 6 hours 2 minutes ago gabrtv deployed 7cb3321
72+
v1 6 hours 3 minutes ago gabrtv deployed deis/helloworld
73+
74+
Note all releases (including rollbacks) append to the release ledger.
75+
76+
77+
.. _`stores config in environment variables`: http://12factor.net/config
78+
.. _`attached resources`: http://12factor.net/backing-services
79+

‎docs/developer/deploy-application.rst‎

Lines changed: 28 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,23 @@
11
:title: Deploy an Application on Deis
2-
:description: First steps for developers using Deis to deploy and scale applications.
2+
:description: First steps for developers using Deis to deploy and manage applications
3+
4+
.. _deploy-application:
35

46
Deploy an Application
57
=====================
8+
An :ref:`Application` is deployed to Deis using ``git push`` or the ``deis`` client.
9+
10+
Supported Applications
11+
----------------------
12+
Deis can deploy any application or service that can run inside a Docker container. In order to be scaled horizontally, applications must follow Heroku's `twelve-factor methodology`_ and store state in external backing services.
613

7-
An :ref:`Application` is typically deployed to Deis by pushing source code using the deis
8-
client or other clients that communicate with Deis' API endpoints. Deploying
9-
applications will be different depending on the source code and its requirements.
14+
For example, if your application persists state to the local filesystem -- common with content management systems like Wordpress and Drupal -- it cannot be scaled horizonally using ``deis scale``.
1015

11-
Authenticating with the API
12-
---------------------------
16+
Fortunately, most modern applications feature a stateless application tier that can scale horizontally inside Deis.
1317

14-
Before deploying an application, all users must first authenticate against the Deis
15-
:ref:`Controller`. For example:
18+
Login to the Controller
19+
-----------------------
20+
Before deploying an application, users must first authenticate against the Deis :ref:`Controller`.
1621

1722
.. code-block:: console
1823
@@ -21,113 +26,28 @@ Before deploying an application, all users must first authenticate against the D
2126
password:
2227
Logged in as deis
2328
24-
Create an Application
25-
---------------------
26-
27-
Change to the root directory of your project you'd like to deploy, then use the ``deis
28-
create`` command to create a remote repository for you to push your application to.
29-
30-
.. code-block:: console
29+
Select a Build Process
30+
----------------------
31+
Deis supports three different ways of building applications:
3132

32-
$ cd example-java-jetty # change into your application's git root
33-
$ deis create --cluster=dev
34-
Creating application... done, created peachy-waxworks
35-
Git remote deis added
33+
1. `Heroku Buildpacks`_
34+
2. `Dockerfiles`_
35+
3. `Docker Image`_ (coming soon)
3636

37-
Deploy the Application
38-
----------------------
37+
Buildpacks
38+
^^^^^^^^^^
39+
Heroku buildpacks are useful if you want to follow Heroku's best practices for building applications or if you are porting an application from Heroku.
3940

40-
With the application created and associated with the SSH :ref:`Key` on your account,
41-
deploy it with ``git push deis master``. If you don't have an application to test with,
42-
you can use `our Dockerfile example`_.
41+
Learn how to use deploy applications on Deis :ref:`using-buildpacks`.
4342

44-
.. code-block:: console
43+
Dockerfiles
44+
^^^^^^^^^^^
45+
Dockerfiles are a powerful way to define a portable execution environment built on a base OS of your choosing.
4546

46-
><> deis create --cluster=dev
47-
Creating application... done, created owlish-huntress
48-
Git remote deis added
49-
><> git push deis master
50-
Counting objects: 10, done.
51-
Delta compression using up to 8 threads.
52-
Compressing objects: 100% (9/9), done.
53-
Writing objects: 100% (10/10), 1.70 KiB | 0 bytes/s, done.
54-
Total 10 (delta 0), reused 0 (delta 0)
55-
-----> Building Docker image
56-
Uploading context 5.632 kB
57-
Uploading context
58-
Step 0 : FROM ubuntu:12.04
59-
---> 9cd978db300e
60-
Step 1 : MAINTAINER OpDemand <info@opdemand.com>
61-
---> Running in 9aefab8ad92c
62-
---> da93d76703b7
63-
Step 2 : ENV PORT 8000
64-
---> Running in 8ce25ddf4405
65-
---> b6046ec54bb3
66-
Step 3 : ADD . /app
67-
---> 5567f79d87fe
68-
Step 4 : WORKDIR /app
69-
---> Running in 0b2c7906381c
70-
---> 444006758e39
71-
Step 5 : CMD python -m SimpleHTTPServer $PORT
72-
---> Running in b33074f3c0ea
73-
---> 5a55b32b8da2
74-
Successfully built 5a55b32b8da2
75-
-----> Pushing image to private registry
76-
77-
Launching... done, v2
78-
79-
-----> owlish-huntress deployed to Deis
80-
http://owlish-huntress.example.com
81-
82-
To learn more, use `deis help` or visit http://deis.io
83-
84-
><> curl -s http://owlish-huntress.example.com
85-
<h1>Powered by Deis</h1>
47+
Learn how to use deploy applications on Deis :ref:`using-dockerfiles`.
8648

87-
Supported Applications
88-
----------------------
8949

90-
As a Heroku-inspired Platform-as-a-Service, Deis is designed to deploy and scale
91-
apps that adhere to `twelve-factor methodology`_.
92-
93-
For example, if your application persists state to the local filesystem
94-
-- common with content management systems like Wordpress and Drupal --
95-
it is not twelve-factor compatible and may not be suitable for Deis or other PaaSes.
96-
97-
Fortunately, most modern applications feature a stateless application tier that
98-
can scale horizontally behind a load balancer. These applications are a perfect
99-
fit for Deis. Deis currently suppports the following languages:
100-
101-
* `Clojure`_
102-
* `Dart`_
103-
* `Dockerfile`_
104-
* `Golang`_
105-
* `Java`_
106-
* `Nodejs`_
107-
* `Perl`_
108-
* `PHP`_
109-
* `Play`_
110-
* `Python`_
111-
* `Ruby`_
112-
* `Scala`_
113-
114-
Support for many other languages and frameworks is possible through
115-
use of custom `Heroku Buildpacks`_ and `Dockerfiles`_.
116-
117-
.. _`Clojure`: https://github.com/opdemand/example-clojure-ring
118-
.. _`Dart`: https://github.com/opdemand/example-dart
119-
.. _`Dockerfile`: https://github.com/opdemand/example-dockerfile-python
120-
.. _`Golang`: https://github.com/opdemand/example-go
121-
.. _`Java`: https://github.com/opdemand/example-java-jetty
122-
.. _`Nodejs`: https://github.com/opdemand/example-nodejs-express
123-
.. _`Perl`: https://github.com/opdemand/example-perl
124-
.. _`PHP`: https://github.com/opdemand/example-php
125-
.. _`Play`: https://github.com/opdemand/example-play
126-
.. _`Python`: https://github.com/opdemand/example-python-flask
127-
.. _`Ruby`: https://github.com/opdemand/example-ruby-sinatra
128-
.. _`Scala`: https://github.com/opdemand/example-scala
129-
.. _`Linux container engine`: http://docker.io/
13050
.. _`twelve-factor methodology`: http://12factor.net/
13151
.. _`Heroku Buildpacks`: https://devcenter.heroku.com/articles/buildpacks
13252
.. _`Dockerfiles`: http://docs.docker.io/en/latest/use/builder/
133-
.. _`our Dockerfile example`: https://github.com/opdemand/example-dockerfile-python
53+
.. _`Docker Image`: http://docs.docker.io/introduction/understanding-docker/

‎docs/developer/dockerfile.rst‎

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎docs/developer/index.rst‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
:title: Developer Guide
2-
:description: Step-by-step guide for developers using Deis to deploy and scale applications.
2+
:description: Step-by-step guide for developers using Deis to deploy and manage applications.
33

44
.. _developer:
55

@@ -15,6 +15,7 @@ Developer Guide
1515
install-client
1616
register-user
1717
deploy-application
18-
buildpack
19-
dockerfile
18+
using-buildpacks
19+
using-dockerfiles
20+
config-application
2021
manage-application

0 commit comments

Comments
 (0)