jyapayne/compose
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update intro docs based on feedback.

Browse source 
Signed-off-by: Daniel Nephin <dnephin@docker.com>
This commit is contained in:
Daniel Nephin 2015-10-23 16:51:03 -04:00
commit d9bc91b7cc
3 changed files with 147 additions and 114 deletions
Download patch file Download diff file Expand all files Collapse all files

207
docs/gettingstarted.md
View file

@ -10,84 +10,103 @@ weight=3
<![end-metadata]-->
## Getting Started
# Getting Started
Let's get started with a walkthrough of getting a simple Python web app running
on Compose. It assumes a little knowledge of Python, but the concepts
demonstrated here should be understandable even if you're not familiar with
Python.
On this page you build a simple Python web application running on Compose. The
application uses the Flask framework and increments a value in Redis. While the
sample uses Python, the concepts demonstrated here should be understandable even
if you're not familiar with it.
### Installation and set-up
## Prerequisites
First, [install Docker and Compose](install.md).
Make sure you have already
[installed both Docker Engine and Docker Compose](install.md). You
don't need to install Python, it is provided by a Docker image.
Create a directory for the project:
## Step 1: Setup
$ mkdir composetest
$ cd composetest
1. Create a directory for the project:
Inside this directory, create `app.py`, a simple Python web app that uses the Flask
framework and increments a value in Redis.
$ mkdir composetest
$ cd composetest
from flask import Flask
from redis import Redis
2. With your favorite text editor create a file called `app.py` in your project
directory.
app = Flask(__name__)
redis = Redis(host='redis', port=6379)
from flask import Flask
from redis import Redis
@app.route('/')
def hello():
redis.incr('hits')
return 'Hello World! I have been seen %s times.' % redis.get('hits')
app = Flask(__name__)
redis = Redis(host='redis', port=6379)
if __name__ == "__main__":
app.run(host="0.0.0.0", debug=True)
@app.route('/')
def hello():
redis.incr('hits')
return 'Hello World! I have been seen %s times.' % redis.get('hits')
Next, define the Python dependencies in a file called `requirements.txt`:
if __name__ == "__main__":
app.run(host="0.0.0.0", debug=True)
flask
redis
3. Create another file called `requirements.txt` in your project directory and
add the following:
### Create a Docker image
flask
redis
Now, create a Docker image containing all of your app's dependencies. You
specify how to build the image using a file called
[`Dockerfile`](http://docs.docker.com/reference/builder/):
These define the applications dependencies.
FROM python:2.7
ADD . /code
WORKDIR /code
RUN pip install -r requirements.txt
CMD python app.py
## Step 2: Create a Docker image
This tells Docker to:
In this step, you build a new Docker image. The image contains all the
dependencies the Python application requires, including Python itself.
* Build an image starting with the Python 2.7 image.
* Add the current directory `.` into the path `/code` in the image.
* Set the working directory to `/code`.
* Install the Python dependencies.
* Set the default command for the container to `python app.py`
1. In your project directory create a file named `Dockerfile` and add the
following:
For more information on how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](http://docs.docker.com/reference/builder/).
FROM python:2.7
ADD . /code
WORKDIR /code
RUN pip install -r requirements.txt
CMD python app.py
You can build the image by running `docker build -t web .`.
This tells Docker to:
### Define services
* Build an image starting with the Python 2.7 image.
* Add the current directory `.` into the path `/code` in the image.
* Set the working directory to `/code`.
* Install the Python dependencies.
* Set the default command for the container to `python app.py`
For more information on how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](http://docs.docker.com/reference/builder/).
2. Build the image.
$ docker build -t web .
This command builds an image named `web` from the contents of the current
directory. The command automatically locates the `Dockerfile`, `app.py`, and
`requirements.txt` files.
## Step 3: Define services
Define a set of services using `docker-compose.yml`:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
links:
- redis
redis:
image: redis
1. Create a file called docker-compose.yml in your project directory and add
the following:
This template defines two services, `web` and `redis`. The `web` service:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
links:
- redis
redis:
image: redis
This Compose file defines two services, `web` and `redis`. The web service:
* Builds from the `Dockerfile` in the current directory.
* Forwards the exposed port 5000 on the container to port 5000 on the host machine.
@ -96,68 +115,74 @@ This template defines two services, `web` and `redis`. The `web` service:
The `redis` service uses the latest public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry.
### Build and run your app with Compose
## Step 4: Build and run your app with Compose
Now, when you run `docker-compose up`, Compose will pull a Redis image, build an image for your code, and start everything up:
1. From your project directory, start up your application.
$ docker-compose up
Pulling image redis...
Building web...
Starting composetest_redis_1...
Starting composetest_web_1...
redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
web_1 | * Running on http://0.0.0.0:5000/
web_1 | * Restarting with stat
$ docker-compose up
Pulling image redis...
Building web...
Starting composetest_redis_1...
Starting composetest_web_1...
redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
web_1 | * Running on http://0.0.0.0:5000/
web_1 | * Restarting with stat
If you're using [Docker Machine](https://docs.docker.com/machine), then `docker-machine ip MACHINE_VM` will tell you its address and you can open `http://MACHINE_VM_IP:5000` in a browser.
Compose pulls a Redis image, builds an image for your code, and start the
services you defined.
If you're using Docker on Linux natively, then the web app should now be listening on port 5000 on your Docker daemon host. If `http://0.0.0.0:5000` doesn't resolve, you can also try `http://localhost:5000`.
2. Enter `http://0.0.0.0:5000/` in a browser to see the application running.
You will see a message in your browser saying:
If you're using Docker on Linux natively, then the web app should now be
listening on port 5000 on your Docker daemon host. If http://0.0.0.0:5000
doesn't resolve, you can also try http://localhost:5000.
`Hello World! I have been seen 1 times.`
If you're using Docker Machine on a Mac, use `docker-machine ip MACHINE_VM` to get
the IP address of your Docker host. Then, `open http://MACHINE_VM_IP:5000` in a
browser.
Refreshing the page will increment the number.
You should see a message in your browser saying:
`Hello World! I have been seen 1 times.`
3. Refresh the page.
The number should increment.
## Step 5: Experiment with some other commands
If you want to run your services in the background, you can pass the `-d` flag
(for "detached" mode) to `docker-compose up` and use `docker-compose ps` to
see what is currently running:
$ docker-compose up -d
Starting composetest_redis_1...
Starting composetest_web_1...
$ docker-compose ps
Name Command State Ports
-------------------------------------------------------------------
composetest_redis_1 /usr/local/bin/run Up
composetest_web_1 /bin/sh -c python app.py Up 5000->5000/tcp
$ docker-compose up -d
Starting composetest_redis_1...
Starting composetest_web_1...
$ docker-compose ps
Name Command State Ports
-------------------------------------------------------------------
composetest_redis_1 /usr/local/bin/run Up
composetest_web_1 /bin/sh -c python app.py Up 5000->5000/tcp
The `docker-compose run` command allows you to run one-off commands for your
services. For example, to see what environment variables are available to the
`web` service:
$ docker-compose run web env
$ docker-compose run web env
See `docker-compose --help` to see other available commands. You can also install [command completion](completion.md) for the bash and zsh shell, which will also show you available commands.
If you started Compose with `docker-compose up -d`, you'll probably want to stop
your services once you've finished with them:
$ docker-compose stop
$ docker-compose stop
At this point, you have seen the basics of how Compose works.
## Where to go next
- Next, try the quick start guide for [Django](django.md),
[Rails](rails.md), or [WordPress](wordpress.md).
- See the reference guides for complete details on the [commands](./reference/index.md), the
[configuration file](compose-file.md) and [environment variables](env.md).
## More Compose documentation
- [User guide](/)
- [Installing Compose](install.md)
- [Get started with Django](django.md)
- [Get started with Rails](rails.md)
- [Get started with WordPress](wordpress.md)
- [Command line reference](./reference/index.md)
- [Compose file reference](compose-file.md)
- [Explore the full list of Compose commands](./reference/index.md)
- [Compose configuration file reference](compose-file.md)