Skip to content

Commit cac60eb

Browse files
author
Gabriel Monroy
committed
first pass at technical overview, include terms in toctree #62 
1 parent 7fd6f14 commit cac60eb

18 files changed

Lines changed: 208 additions & 25 deletions

‎docs/gettingstarted/concepts.rst‎

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

‎docs/gettingstarted/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Getting Started
1111
.. toctree::
1212
:maxdepth: 1
1313

14-
concepts
14+
overview
1515
installation
1616
usage
1717
tutorial

‎docs/gettingstarted/installation.rst‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,8 @@
77
Installation
88
============
99

10-
**Coming soon...**
10+
A typical Deis deployment consists of a Deis `Controller`_ in charge of:
11+
12+
* Processing :ref:`Client API <client>` calls
13+
* Managing Chef :ref:`Nodes <node>`
14+
* Managing Docker :ref:`Containers <container>`

‎docs/gettingstarted/overview.rst‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
:title: Technical Overview
2+
:description: -- Technical Overview of the Deis platform
3+
:keywords: deis, documentation, technical, overview
4+
5+
.. _overview:
6+
7+
Overview
8+
========
9+
10+
Deis is an application platform that deploys and scales `Twelve Factor`_ apps
11+
using a formation of `Chef`_ Nodes, `Docker`_ containers and
12+
`Nginx`_ proxies.
13+
14+
Formations
15+
----------
16+
A :ref:`formation` is a set of infrastructure used to host a single application
17+
or service backed by a single git repository. Each formation includes
18+
:ref:`Layers <layer>` of :ref:`Nodes <node>` used to host services, a set of
19+
:ref:`Containers <container>` used to run isolated processes, and a
20+
:ref:`Release` that defines the current :ref:`Build` and :ref:`config`
21+
deployed by containers.
22+
23+
Layers
24+
------
25+
:ref:`Layers <layer>` are homogeneous groups of :ref:`Nodes <node>` that
26+
perform work on behalf of a formation. Each node in a layer has
27+
the same :ref:`Flavor` and Chef configuration, allowing them to be scaled
28+
with ease. Formations have two types of layers.
29+
30+
Runtime Layers
31+
^^^^^^^^^^^^^^
32+
Runtime layers service requests and run background tasks for the formation.
33+
Nodes in a runtime layer use a `Chef Databag`_ to deploy
34+
:ref:`Containers <container>` running a specific :ref:`Release`.
35+
36+
Proxy Layers
37+
^^^^^^^^^^^^
38+
Proxy layers expose the formation to the outside world.
39+
Nodes in a proxy layer use a `Chef Databag`_ to configure routing of
40+
inbound requests to :ref:`Containers <container>` hosted on runtime layers.
41+
42+
Build, Release, Run
43+
-------------------
44+
Deis enforces strict separation between Build, Release and Run stages
45+
following the `Twelve Factor model`_.
46+
47+
Build Stage
48+
^^^^^^^^^^^
49+
The Deis :ref:`Controller` includes a `Gitosis Server`_ that receives
50+
incoming git push requests over SSH and builds application
51+
inside an ephemeral Docker container. A tarball of the /app directory is
52+
extracted into a :ref:`slug` and exposed on an Nginx static file server.
53+
The slug is later downloaded by the the runtime layer and bind-mounted
54+
into a Docker container.
55+
56+
Release Stage
57+
^^^^^^^^^^^^^
58+
A :ref:`release` is a :ref:`build` combined with :ref:`config`.
59+
When a new build is created or config is changed,
60+
a new release is rolled automatically. Releases make it easy to
61+
rollback of code and configuration.
62+
63+
Run Stage
64+
^^^^^^^^^
65+
The run stage updates Chef databags and converges all nodes in the formation,
66+
deploying the latest release on containers and reconfiguring proxies.
67+
SSH is used to converge all of the nodes in the runtime layer followed
68+
by all of the nodes in the proxy layer.
69+
70+
Backing Services
71+
----------------
72+
In keeping with `Twelve Factor`_ app methodology `backing services`_ like
73+
databases, queues and storage are decoupled and attached via `environment
74+
variables`_. This allows formations to use backing services provided via
75+
different formations (via their proxy layer), or external/third-party
76+
services accessible over the network. The use of environment variables
77+
also allows formations to easily swap backing services when necessary.
78+
79+
.. _`Twelve Factor`: http://12factor.net/
80+
.. _`Chef`: http://www.opscode.com/chef/
81+
.. _`Docker`: http://docker.io/
82+
.. _`Nginx`: http://wiki.nginx.org/Main
83+
.. _`Chef Databag`: http://docs.opscode.com/essentials_data_bags.html
84+
.. _`Twelve Factor model`: http://12factor.net/build-release-run
85+
.. _`backing services`: http://12factor.net/backing-services
86+
.. _`environment variables`: http://12factor.net/config
87+
.. _`Gitosis Server`: https://github.com/opdemand/gitosis
88+
.. _`Buildstep`: https://github.com/opdemand/buildstep

‎docs/index.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
Welcome
66
=======
77

8-
Deis is an open source PaaS that makes it easy to deploy
9-
:ref:`LXC Containers <container>` and :ref:`Chef Nodes <node>` used to host applications,
10-
databases, middleware and other services. Deis leverages Chef, Docker and
11-
Heroku Buildpacks to provide a private PaaS that is lightweight and flexible.
8+
Deis is an open source PaaS that makes it easy to deploy LXC Containers and
9+
Chef Nodes used to host applications, databases, middleware and other services.
10+
Deis leverages Chef, Docker and Heroku Buildpacks to provide a private PaaS
11+
that is lightweight and flexible.
1212

1313
.. image:: _static/img/deis-graphic.png
1414

15-
If you are new to Deis, you should start with basic :ref:`concepts`.
15+
If you are new to Deis, you should start with the :ref:`Technical Overview <overview>`.
1616
Once you've completed :ref:`installation` of your private Deis controller,
1717
explore command-line :ref:`usage` which is elaborated on in the :ref:`tutorial`.
1818

‎docs/terms/build.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:title: Build
2+
:description: What is a Build?
3+
:keywords: build, release
4+
5+
.. _build:
6+
7+
Build
8+
=====

‎docs/terms/config.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:title: Config
2+
:description: What is Config?
3+
:keywords: config, release
4+
5+
.. _config:
6+
7+
Config
8+
======

‎docs/terms/container.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
:title: Container
2-
:description: What is a Deis Container?
3-
:keywords: lxc container, lxc, container, deis, docker
2+
:description: What is a Container?
3+
:keywords: lxc container, lxc, container, docker
44

55
.. _container:
66

7-
LXC Container
8-
=============
7+
Container
8+
=========

‎docs/terms/controller.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:title: Controller
2+
:description: What is a Deis Controller?
3+
:keywords: deis, controller
4+
5+
.. _controller:
6+
7+
Controller
8+
==========

‎docs/terms/flavor.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:title: Flavor
2+
:description: What is a Flavor?
3+
:keywords: flavor
4+
5+
.. _flavor:
6+
7+
Flavor
8+
======

0 commit comments

Comments
 (0)