tyler.durden
/
compose
mirror of https://github.com/docker/compose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update readme to reflect how it currently works

This commit is contained in:
Ben Firshman 2013-12-20 18:10:30 +00:00
parent 507940535f
commit 791028866c
1 changed files with 67 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
README.md
View File

@ -3,15 +3,17 @@ Plum
**WARNING**: This is a work in progress and probably won't work yet. Feedback welcome.
Plum is tool for defining and running apps with Docker. It uses a simple, version-controllable YAML configuration file that looks something like this:
Plum is tool for defining and running application environments with Docker. It uses a simple, version-controllable YAML configuration file that looks something like this:
```yaml
web:
build: .
links:
- db
ports:
- 8000:8000
db:
image: orchardup/postgresql
web:
build: web/
link: db
```
Installing
@ -26,26 +28,20 @@ Defining your app
Put a `plum.yml` in your app's directory. Each top-level key defines a "service", such as a web app, database or cache. For each service, Plum will start a Docker container, so at minimum it needs to know what image to use.
The way to get started is to just give it an image name:
The simplest way to get started is to just give it an image name:
```yaml
db:
image: orchardup/postgresql
```
Alternatively, you can give it the location of a directory with a Dockerfile (or a Git URL, as per the `docker build` command), and it'll automatically build the image for you:
```yaml
db:
build: /path/to/postgresql/build/directory
```
You've now given Plum the minimal amount of configuration it needs to run:
```bash
$ plum start
Building db... done
db is running at 127.0.0.1:45678
Pulling image orchardup/postgresql...
Starting myapp_db_1...
myapp_db_1 is running at 127.0.0.1:45678
<...output from postgresql server...>
```
@ -55,79 +51,99 @@ By default, `plum start` will run until each container has shut down, and relay
```bash
$ plum start -d
Building db... done
db is running at 127.0.0.1:45678
Starting myapp_db_1... done
myapp_db_1 is running at 127.0.0.1:45678
$ plum ps
SERVICE STATE PORT
db up 45678
Name State Ports
------------------------------------
myapp_db_1 Up 5432->45678/tcp
```
### Building services
Plum can automatically build images for you if your service specifies a directory with a `Dockerfile` in it (or a Git URL, as per the `docker build` command).
This example will build an image with `app.py` inside it:
#### app.py
```python
print "Hello world!"
```
#### plum.yaml
```yaml
web:
build: .
```
#### Dockerfile
FROM ubuntu:12.04
RUN apt-get install python
ADD . /opt
WORKDIR /opt
CMD python app.py
### Getting your code in
Some services may include your own code. To get that code into the container, ADD it in a Dockerfile.
`plum.yml`:
If you want to work on an application being run by Plum, you probably don't want to have to rebuild your image every time you make a change. To solve this, you can share the directory with the container using a volume so the changes are reflected immediately:
```yaml
web:
build: web/
build: .
volumes:
- .:/opt
```
`web/Dockerfile`:
FROM orchardup/rails
ADD . /code
CMD bundle exec rackup
### Communicating between containers
Your web app will probably need to talk to your database. You can use [Docker links] to enable containers to communicate, pass in the right IP address and port via environment variables:
Your dweb app will probably need to talk to your database. You can use [Docker links](http://docs.docker.io/en/latest/use/port_redirection/#linking-a-container) to enable containers to communicate, pass in the right IP address and port via environment variables:
```yaml
db:
image: orchardup/postgresql
web:
build: web/
link: db
build: .
links:
- db
```
This will pass an environment variable called DB_PORT into the web container, whose value will look like `tcp://172.17.0.4:45678`. Your web app's code can then use that to connect to the database.
This will pass an environment variable called `MYAPP_DB_1_PORT` into the web container, whose value will look like `tcp://172.17.0.4:45678`. Your web app's code can use that to connect to the database. To see all of the environment variables available, run `env` inside a container:
You can pass in multiple links, too:
```yaml
link:
- db
- memcached
- redis
```bash
$ plum start -d db
$ plum run web env
```
In each case, the resulting environment variable will begin with the uppercased name of the linked service (`DB_PORT`, `MEMCACHED_PORT`, `REDIS_PORT`).
### Container configuration options
You can pass extra configuration options to a container, much like with `docker run`:
```yaml
web:
build: web/
build: .
-- override the default run command
run: bundle exec thin -p 3000
-- override the default command
command: bundle exec thin -p 3000
-- expose ports - can also be an array
ports: 3000
-- expose ports, optionally specifying both host and container ports (a random host port will be chosen otherwise)
ports:
- 3000
- 8000:8000
-- map volumes - can also be an array
volumes: /tmp/cache
-- map volumes
volumes:
- cache/:/tmp/cache
-- add environment variables - can also be a dictionary
-- add environment variables
environment:
RACK_ENV: development
```
@ -145,18 +161,3 @@ $ plum run web bash
```
Running more than one container for a service
---------------------------------------------
You can set the number of containers to run for each service with `plum scale`:
```bash
$ plum start -d
db is running at 127.0.0.1:45678
web is running at 127.0.0.1:45679
$ plum scale db=0,web=3
Stopped db (127.0.0.1:45678)
Started web (127.0.0.1:45680)
Started web (127.0.0.1:45681)
```