Skip to content
This repository was archived by the owner on Jun 12, 2018. It is now read-only.

Commit df62fa3

Browse files
fgrehmfgrehm
committed
Merge pull request #45 from fgrehm/docs
Docs for 0.0.1
2 parents ea34e8f + 17e89b0 commit df62fa3

File tree

5 files changed

+389
-85
lines changed

5 files changed

+389
-85
lines changed

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Devstep
22

3-
Dead simple, no frills development environment builder that leverages
4-
[Docker](https://www.docker.io/) and the [buildpack](https://devcenter.heroku.com/articles/buildpacks)
5-
abstraction for fast and easy provisioning of project dependencies.
3+
A dead simple, no frills development environment builder that is based around a
4+
simple goal:
65

7-
See http://fgrehm.viewdocs.io/devstep or the project's [/docs](/docs) folder
8-
for more information.
6+
> I want to `git clone` and run a single command to hack on any software project.
7+
8+
For more information please check http://fgrehm.viewdocs.io/devstep

‎docs/getting-started.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
# Getting Started
2+
-----------------
3+
4+
Devstep comes in two flavors, you can either use the provided CLI or you can build
5+
on top of the provided images from `Dockerfile`s.
6+
7+
Regardless of the flavor you choose, it is a good idea to `docker pull fgrehm/devstep:v0.0.1`
8+
before creating your first container / image for a better "user experience".
9+
Docker will download that image as needed but by pulling it first you'll reduce
10+
the waiting time when interacting with Devstep for the first time.
11+
12+
## Sanity check
13+
---------------
14+
15+
This project is being developed and tested on an Ubuntu 14.04 host with Docker
16+
1.0.0+, while it is likely to work on other distros / Docker versions /
17+
[boot2docker](http://boot2docker.io/), I'm not sure how it will behave on the wild.
18+
19+
## Using the CLI
20+
----------------
21+
22+
Before you try out the CLI, make sure you have Docker installed and that your
23+
user is capable to run `docker` commands [without `sudo`](http://docs.docker.io/installation/ubuntulinux/#giving-non-root-access).
24+
25+
> **IMPORTANT**: The `developer` user that is used by Devstep assumes your user
26+
and group ids are equal to `1000` when using the CLI or the container's init
27+
process will be aborted. This is to guarantee that files created within Docker
28+
containers have the appropriate permissions so that you can manipulate them
29+
on the host without the need to use `sudo`. This is currently a Devstep limitation
30+
that will be worked around in case there is enough demand or will be fixed once
31+
Docker adds support for user namespaces ([#6600](https://github.com/dotcloud/docker/pull/6600)
32+
/ [#6602](https://github.com/dotcloud/docker/pull/6602) / [#6603](https://github.com/dotcloud/docker/pull/6603)
33+
/ [#4572](https://github.com/dotcloud/docker/pull/4572)).
34+
35+
> The `1000` id was chosen because it is the default uid / gid of Ubuntu Desktop users
36+
that are created during the installation process. To work around this limitation,
37+
please build your own image using the appropriate ids and add a `DEVSTEP_SOURCE_IMAGE=<YOUR-IMAGE>`
38+
line to your `~/.devsteprc`.
39+
40+
To install the CLI, you can run the one liner below and read on for more:
41+
42+
```sh
43+
L=$HOME/bin/devstep && curl -sL https://github.com/fgrehm/devstep/raw/master/devstep > $L && chmod +x $L
44+
```
45+
46+
_The snippet above assumes `$HOME/bin` is on your PATH, please change `$HOME/bin`
47+
to an appropriate path in case your system is not configured like that._
48+
49+
### `devstep hack`
50+
51+
This is the easiest way to get started with Devstep. By running the command
52+
from your project's root, Devstep will:
53+
54+
1. Create a Docker container based on `fgrehm/devstep` with project sources bind
55+
mounted at `/workspace`.
56+
2. Detect and install project's dependencies on the new container using the
57+
available buildpacks.
58+
3. Start a `bash` session with everything in place for you to do your work.
59+
60+
Once you `exit` the `bash` session, the container will be garbage collected
61+
(aka `docker rm`ed).
62+
63+
In case you need to provide additional parameters to the underlying `docker run`
64+
command you can use the `-r` flag. For example, `devstep hack -r "-p 80:8080"` will
65+
redirect the `8080` port on your host to the port `80` within the container.
66+
67+
### `devstep build`
68+
69+
By running the command from your project's root, Devstep will:
70+
71+
1. Create a Docker container based on `fgrehm/devstep` with project sources bind
72+
mounted at `/workspace`.
73+
2. Detect and install project's dependencies on the new container using the
74+
available buildpacks.
75+
3. `docker commit` the container to a `devstep/<PROJECT>:<TIMESTAMP>` image.
76+
4. `docker tag` the new image as `devstep/<PROJECT>:latest`.
77+
78+
The `devstep/<PROJECT>` images act like snapshots of your project dependencies
79+
and will be used as the source image for subsequent `devstep` commands instead
80+
of the `fgrehm/devstep` image.
81+
82+
For example, running a `devstep hack` after building the image will use `devstep/<PROJECT>:latest`
83+
as the base container for new "hacking sessions" so that you don't have to build
84+
your project's environment from scratch. The same applies for a new `devstep build`,
85+
which will build on top of the latest image reducing the overall build time when
86+
compared to reconfiguring the environment from scratch using
87+
`Dockerfile`s.
88+
89+
Because the `build` command bind mounts your project sources on the Docker container
90+
during the configuration process, you'll have to provide the full path to sources
91+
on the host machine as a Docker volume in order to work on the project.
92+
`devstep hack` can take care of that for you or you can manually:
93+
94+
```sh
95+
docker run -ti -v `pwd`:/workspace devstep/<PROJECT>
96+
```
97+
98+
### Bootstrapping a new project (AKA solving the chicken or the egg problem)
99+
100+
Assuming you are willing to use Docker / Devstep to avoid cluttering your machine
101+
with development tools, there's no point on installing Ruby / Python / ... on your
102+
computer in order to scaffold a new project. To make that process easier, you can
103+
use the `devstep bootstrap` command.
104+
105+
That command will start an interactive `bash` session with the current directory
106+
bind mounted as `/workspace` on the container and you'll be able to manually
107+
install packages / tools required to scaffold your new project. You can even
108+
force a specific buildpack to run from there.
109+
110+
For example, scaffolding a new Rails project means:
111+
112+
```sh
113+
cd $HOME/projects # or whatever directory you keep your projects
114+
devstep bootstrap -w my_app
115+
116+
build-project -b ruby
117+
source $HOME/load-env.sh
118+
gem install rails
119+
rails new my_app
120+
121+
exit # Or do some extra setup before exiting
122+
```
123+
124+
Once you `exit` the container, you should end up with a `devstep/my_app` image
125+
and a brand new Rails app under `$HOME/projects/my_app` on your machine. To
126+
abort the bootstrap process, just `exit 1` from within the container and answer
127+
'No' when asked for confirmation for commiting the image.
128+
129+
As with `devstep build`, subsequent `devstep` commands like `build` and `hack`
130+
will use `devstep/my_app:latest` as the source image. Project sources
131+
also won't get stored inside the Docker image and you'll need to provide the
132+
full path to its sources on the host machine as a Docker volume in order to
133+
work on the project. `devstep hack` can take care of that for you or you can
134+
manually:
135+
136+
```sh
137+
docker run -ti -v `pwd`:/workspace devstep/<PROJECT>
138+
```
139+
140+
To bootstrap projects for other platforms and frameworks you can follow a similar
141+
approach, replacing the Ruby / Rails specifics with the platform / framework
142+
of choice.
143+
144+
### Caching project's dependencies packages on the host
145+
146+
As mentioned on the [introduction](introduction) section, Devstep is also capable
147+
of reducing disk space and initial configuration times by caching packages on the
148+
host using a strategy similar to [vagrant-cachier's cache buckets](http://fgrehm.viewdocs.io/vagrant-cachier/how-does-it-work).
149+
This behavior is enabled by default and will be further documented on the future.
150+
For now you need to know that the `/tmp/devstep/cache` dir on the host will be bind
151+
mounted to containers created by the CLI under `/.devstep/cache` and most of your
152+
project's dependencies packages will be downloaded to there. Note that the dependencies
153+
themselves are extracted and kept inside the images built by the CLI and you can
154+
safely clean things up or disable the caching behavior at will.
155+
156+
To disable the caching functionality you can add the `DEVSTEP_CACHE_PATH=""`
157+
line to your `~/.devsteprc`.
158+
159+
### Other commands
160+
161+
* `clean` -> Remove all images built for the current project
162+
* `pristine` -> Rebuild current project associated Docker image from scratch
163+
* `run` -> Run a one off command against the current source image
164+
* `images` -> Display images available for the current project
165+
* `ps` -> List all containers associated with the current project
166+
* `info` -> Show some information about the current project
167+
168+
For the most up-to-date list of supported commands, run `devstep --help`.
169+
170+
171+
## Building images using `Dockerfiles`
172+
--------------------------------------
173+
174+
In case your project require additional stuff to work you can use the provided
175+
`fgrehm/devstep`, `fgrehm/devstep-ab` or `fgrehm/devstep-sa` images as a starting
176+
point for your `Dockerfile`s.
177+
178+
The `fgrehm/devstep` image is the base image used for Devstep environments and
179+
requires you to manually trigger the build:
180+
181+
```Dockerfile
182+
FROM fgrehm/devstep:v0.0.1
183+
184+
# Add project to the image and build it
185+
ADD . /workspace
186+
WORKDIR /workspace
187+
RUN CLEANUP=1 /.devstep/bin/build-project /workspace
188+
```
189+
190+
To make things easier, there's also a `fgrehm/devstep-ab:v0.0.1` image that
191+
does the same steps as outlined above automatically for you by leveraging `ONBUILD`
192+
instructions, trimming down your `Dockerfile` to a single line:
193+
194+
```Dockerfile
195+
FROM fgrehm/devstep-ab:v0.0.1
196+
```
197+
198+
And in case you want to run extra services (like a DB) within the same container
199+
of your project, you can use the `fgrehm/devstep-sa` image:
200+
201+
```Dockerfile
202+
FROM fgrehm/devstep-sa:v0.0.1
203+
204+
# Add project to the image and build it
205+
ADD . /workspace
206+
WORKDIR /workspace
207+
RUN CLEANUP=1 /.devstep/bin/build-project /workspace
208+
209+
# Configure PostgreSQL and Redis to run on the project's container
210+
RUN /.devstep/bin/configure-addons postgresql redis
211+
```
212+
213+
By using a `Dockerfile` to build your images (instead of using `devstep build`)
214+
you'll be able to skip mounting project's sources on the container when running
215+
it and a simple `docker run -it <IMAGE-NAME>` should do the trick. **_Keep in mind
216+
that changes made to project sources will be kept inside the container and
217+
you'll lose them when you `docker rm` it._**
218+
219+
220+
## Available buildpacks
221+
-----------------------
222+
223+
* [Bats](https://github.com/fgrehm/devstep/tree/master/buildpacks/bats)
224+
* [Golang](https://github.com/fgrehm/devstep/tree/master/buildpacks/golang)
225+
* [Inline](https://github.com/fgrehm/devstep/tree/master/buildpacks/inline)
226+
* [NodeJS](https://github.com/fgrehm/devstep/tree/master/buildpacks/nodejs)
227+
* [PHP](https://github.com/fgrehm/devstep/tree/master/buildpacks/php)
228+
* [Python](https://github.com/fgrehm/devstep/tree/master/buildpacks/python)
229+
* [Ruby](https://github.com/fgrehm/devstep/tree/master/buildpacks/ruby)
230+
231+
232+
## More information
233+
-------------------
234+
235+
If you reached this point it means you should have a good understanding of how
236+
Devstep works and what you can do with it. If you are still wondering how you can
237+
use the tool and / or benefit from it, please create a [new issue](https://github.com/fgrehm/devstep/issues/new)
238+
so that we can discuss how can we improve the docs :)

‎docs/index.md‎

Lines changed: 20 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,36 @@
11
# Devstep
22

3-
Devstep is a dead simple, no frills development environment builder that is based
4-
around a simple goal:
3+
A dead simple, no frills development environment builder that is based around a
4+
simple goal:
55

66
> I want to `git clone` and run a single command to hack on any software project.
77
8-
To accomplish that, Devstep comes with a CLI that uses a "self suficient"
9-
[Docker](https://www.docker.io/) image and the [buildpack](https://devcenter.heroku.com/articles/buildpacks)
10-
abstraction for fast and easy provisioning of project dependencies.
8+
[Devstep demo on Vimeo](https://vimeo.com/99482658)
119

12-
## WAT?!?
10+
<br>
1311

14-
Have you ever deployed an app to a platform like Heroku? How awesome it is to
15-
`git push` some code and see it running without worrying about the infrastructure
16-
it is going to run on? Now imagine that idea applied to any type of project,
17-
regardless of whether they are web apps or not. This is what I'm trying to achieve
18-
with Devstep.
12+
## WAT?!
1913

20-
Be it a CLI tool, a plugin for some framework or a web app, I don't care, I just
21-
want "someone" to do the heavy lifting of preparing an isolated and disposable
22-
environment using as close to "zero configuration" as possible so that I can
23-
focus on writing and delivering working software :-)
14+
Yeah, just give Devstep your code and let it take care of the rest (including
15+
automatic port forwarding to linked containers). Check out this demo of using
16+
Devstep with [Discourse]():
2417

18+
[Discourse demo on Vimeo](http://vimeo.com/99212562)
2519

26-
## Why should I use it?
20+
<br>
2721

28-
You can configure a Docker base image yourself using a `Dockerfile`, so why bother
29-
using Devstep?
22+
And before I forget, Devstep is not just for the web, it is also suitable for building
23+
/ developing libraries and CLI tools:
3024

31-
Because configuring a base system from scratch to hack on a project (using Docker
32-
or not) is not an easy task for many people. Devstep's base image alleviates that
33-
pain by providing an environment [similar to Heroku's](https://github.com/progrium/cedarish)
34-
and should be capable of building and running a wide range of applications / tools
35-
/ libraries (given there is a buildpack for the platform being used of course).
36-
37-
Devstep is also capable of reducing the disk space and initial configuration times by
38-
(optionally) caching packages on host using a strategy similar to [vagrant-cachier's cache buckets](http://fgrehm.viewdocs.io/vagrant-cachier/how-does-it-work),
39-
allowing you to even build images while offline.
40-
41-
## Ok, so how does it work?
42-
43-
Devstep is a Docker image builder that takes your app's source as an input and
44-
produces a Docker image with all dependencies required for hacking on it. You
45-
can use Devstep in two different ways (from `Dockerfile`s or from the provided
46-
Bash CLI) and you are free to manually run the images or use other tools to manage
47-
your containers at runtime.
48-
49-
For quick hacks, there is a `devstep hack` command that will create a new
50-
container, install everything that is needed for your project and will fire up
51-
a bash session for some hacking. Once you `exit` it, it will be garbage collected
52-
(aka `docker rm`ed).
53-
54-
55-
## What's on the [Docker image](https://index.docker.io/u/fgrehm/devstep)?
56-
57-
Same packages installed by [`progrium/cedarish`](https://github.com/progrium/cedarish)
58-
(we use it as a base image) plus [some other stuff](Dockerfile), an init script
59-
based on [`phusion/baseimage-docker`](https://github.com/phusion/baseimage-docker)'s
60-
and [some buildpacks](https://github.com/fgrehm/devstep/tree/master/buildpacks).
61-
62-
63-
## Why standard Heroku buildpacks are not used?
64-
65-
Because development environments have a few different needs than production
66-
environments and not all projects are web apps. For example, PHP apps are likely
67-
to have [opcache](http://www.php.net/manual/en/intro.opcache.php) enabled
68-
on production to improve app's performance but have it disabled during development
69-
and Ruby on Rails apps might require assets to be precompiled.
25+
[Sidekiq demo on Vimeo](https://vimeo.com/99487410)
7026

27+
If you are just getting started with Devstep, check out the [introduction](introduction)
28+
and the [getting started](getting-started) guides.
7129

7230
## Project status
7331

74-
This is mostly the result of many different hacks that suit my own needs and
75-
seem to be working fine based on my [limited testing](https://github.com/fgrehm/devstep-examples).
76-
Use at your own risk and expect things to break. Also, don't get scared by some bad code you might see
77-
around as it will be cleaned up in case more people think this project is useful ;)
78-
79-
80-
## Installing the CLI
81-
82-
Assuming `$HOME/bin` is on your path, you can run the one liner below to install
83-
the [`devstep`](/devstep) script:
84-
85-
```sh
86-
L=$HOME/bin/devstep && curl -sL https://github.com/fgrehm/devstep/raw/master/devstep > $L && chmod +x $L
87-
```
88-
89-
90-
## :warning: Work in progress :warning:
91-
92-
_Documentation is being worked on, stay tunned for updates or have a look at
93-
project sources if you are feeling adventurous_
32+
This is mostly the result of many different hacks that suits my needs for developing
33+
Ruby on Rails and Go CLI apps. It has been working fine for my use cases since April /
34+
March 2014 and it also seems to play really well with other platforms based on my
35+
[limited testing](https://github.com/fgrehm/devstep-examples). Use at your own risk
36+
and expect things to break (and if it does break [please let me know!](https://github.com/fgrehm/devstep/issues/new)).

0 commit comments

Comments
 (0)