1. docker
  2. Commit 04f092792f66b751a8d0e5d4860852a175393194
Browse code

Add docs and maintainers file for new sub pkgs

Michael Crosby authored on 2013/10/03 04:31:29
Showing 10 changed files
docs/sources/commandline/cli.rst
History View file @ 04f0927
... ... 
@@ -54,10 +54,14 @@ Available Commands
54 54
55 55 
 .. include:: command/kill.rst
56 56
57 
+.. include:: command/link.rst
58 
+
57 59 
 .. include:: command/login.rst
58 60
59 61 
 .. include:: command/logs.rst
60 62
63 
+.. include:: command/ls.rst
64 
+
61 65 
 .. include:: command/port.rst
62 66
63 67 
 .. include:: command/ps.rst
docs/sources/commandline/command/link.rst
History View file @ 04f0927
64 68 
new file mode 100644
... ... 
@@ -0,0 +1,29 @@
0 
+:title: Link Command
1 
+:description: Add a link or rename the link for a container
2 
+:keywords: link, docker, container, documentation, link, links
3 
+
4 
+============================================================================
5 
+``link`` -- Add a link or rename the link for a container
6 
+============================================================================
7 
+
8 
+::
9 
+
10 
+    Usage: docker link CURRENT_NAME NEW_NAME
11 
+
12 
+    Link a container to a new name.
13 
+
14 
+
15 
+Examples:
16 
+--------
17 
+
18 
+.. code-block:: bash
19 
+
20 
+    $ docker link /59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc /redis
21 
+    $ docker ls
22 
+    NAME                                                                      ID                                                                 IMAGE
23 
+    /redis                                                                    59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc   crosbymichael/redis:latest
24 
+    /59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc         59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc   crosbymichael/redis:latest
25 
+
26 
+
27 
+This will create a new link for the existing name ``/59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc``
28 
+with the new name ``/redis`` so that we can new reference the same container under the new name ``/redis``.
docs/sources/commandline/command/ls.rst
History View file @ 04f0927
0 29 
new file mode 100644
... ... 
@@ -0,0 +1,29 @@
0 
+:title: Ls Command
1 
+:description: Ls all links for containers
2 
+:keywords: ls, docker, container, documentation, link, links
3 
+
4 
+============================================================================
5 
+``ls`` -- List all links for containers
6 
+============================================================================
7 
+
8 
+::
9 
+
10 
+    Usage: docker ls
11 
+
12 
+    List all links for containers and display the relationship between parent
13 
+    and child containers.
14 
+
15 
+
16 
+Examples:
17 
+--------
18 
+
19 
+.. code-block:: bash
20 
+
21 
+    $ docker ls
22 
+    NAME                                                                      ID                                                                 IMAGE
23 
+    /redis                                                                    39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89   crosbymichael/redis:latest
24 
+    /webapp                                                                   cffb86ffa80b11cd8777d300759ee53c4e61729431c30ec9552dd9e6d3abc87d   demo:latest
25 
+    /webapp/redis                                                             39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89   crosbymichael/redis:latest
26 
+
27 
+This will display all links and the names that you can use the reference the link.  Parent child
28 
+relationships are also displayed with ls.
docs/sources/commandline/command/rm.rst
History View file @ 04f0927
... ... 
@@ -11,3 +11,26 @@
11 11 
     Usage: docker rm [OPTIONS] CONTAINER
12 12
13 13 
     Remove one or more containers
14 
+        -link="": Remove the link instead of the actual container
15 
+
16 
+
17 
+Examples:
18 
+--------
19 
+
20 
+.. code-block:: bash
21 
+
22 
+    $ docker rm /redis
23 
+    /redis
24 
+
25 
+
26 
+This will remove the container referenced under the link ``/redis``.
27 
+
28 
+
29 
+.. code-block:: bash
30 
+
31 
+    $ docker rm -link /webapp/redis
32 
+    /webapp/redis
33 
+
34 
+
35 
+This will remove the underlying link between ``/webapp`` and the ``/redis`` containers removing all
36 
+network communication.
docs/sources/commandline/command/run.rst
History View file @ 04f0927
... ... 
@@ -33,6 +33,7 @@
33 33 
       -w="": Working directory inside the container
34 34 
       -lxc-conf=[]: Add custom lxc options -lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
35 35 
       -expose=[]: Expose a port from the container without publishing it to your host
36 
+      -link="": Add link to another container (containerid:alias)
36 37
37 38 
 Examples
38 39 
 --------
... ... 
@@ -83,4 +84,34 @@ working directory, by changing into the directory to the value
83 83 
 returned by ``pwd``. So this combination executes the command
84 84 
 using the container, but inside the current working directory.
85 85
86 
+.. code-block:: bash
87 
+
88 
+    docker run -p 127.0.0.0::80 ubuntu bash
89 
+
90 
+This the ``-p`` flag now allows you to bind a port to a specific
91 
+interface of the host machine.  In this example port ``80`` of the
92 
+container will have a dynamically allocated port bound to 127.0.0.1
93 
+of the host.
94 
+
95 
+.. code-block:: bash
96 
+
97 
+    docker run -p 127.0.0.1:80:80 ubuntu bash
98 
+
99 
+This will bind port ``80`` of the container to port ``80`` on 127.0.0.1 of your
100 
+host machine.
101 
+
102 
+.. code-block:: bash
103 
+
104 
+    docker run -expose 80 ubuntu bash
105 
+
106 
+This will expose port ``80`` of the container for use within a link
107 
+without publishing the port to the host system's interfaces.
108 
+
109 
+.. code-block:: bash
110 
+
111 
+    docker run -link /redis:redis ubuntu bash
86 112
113 
+The ``-link`` flag will link the container named ``/redis`` into the
114 
+newly created container with the alias ``redis``.  The new container
115 
+can access the network and environment of the redis container via
116 
+environment variables.
docs/sources/examples/index.rst
History View file @ 04f0927
... ... 
@@ -1,6 +1,6 @@
1 1 
 :title: Docker Examples
2 2 
 :description: Examples on how to use Docker
3 
-:keywords: docker, hello world, node, nodejs, python, couch, couchdb, redis, ssh, sshd, examples, postgresql
3 
+:keywords: docker, hello world, node, nodejs, python, couch, couchdb, redis, ssh, sshd, examples, postgresql, link
4 4
5 5
6 6 
 .. _example_list:
... ... 
@@ -24,3 +24,4 @@ to more substantial services like you might find in production.
24 24 
    postgresql_service
25 25 
    mongodb
26 26 
    running_riak_service
27 
+   linking_into_redis
docs/sources/examples/linking_into_redis.rst
History View file @ 04f0927
27 28 
new file mode 100644
... ... 
@@ -0,0 +1,146 @@
0 
+:title: Linking to an Redis container
1 
+:description: Running redis linked into your web app
2 
+:keywords: docker, example, networking, redis, link
3 
+
4 
+.. _linking_redis:
5 
+
6 
+Linking Redis
7 
+=============
8 
+
9 
+.. include:: example_header.inc
10 
+
11 
+Building a redis container to link as a child of our web application.
12 
+
13 
+Building the redis container
14 
+----------------------------
15 
+
16 
+We will use a pre-build version of redis from the index under
17 
+the name ``crosbymichael/redis``.  If you are interested in the
18 
+Dockerfile that was used to build this container here it is.
19 
+
20 
+.. code-block:: bash
21 
+
22 
+    # Build redis from source
23 
+    # Make sure you have the redis source code checked out in
24 
+    # the same directory as this Dockerfile
25 
+    FROM ubuntu
26 
+
27 
+    RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list
28 
+    RUN apt-get update
29 
+    RUN apt-get upgrade -y
30 
+
31 
+    RUN apt-get install -y gcc make g++ build-essential libc6-dev tcl
32 
+
33 
+    ADD . /redis
34 
+
35 
+    RUN (cd /redis && make)
36 
+    RUN (cd /redis && make test)
37 
+
38 
+    RUN mkdir -p /redis-data
39 
+    VOLUME ["/redis-data"]
40 
+    EXPOSE 6379
41 
+
42 
+    ENTRYPOINT ["/redis/src/redis-server"]
43 
+    CMD ["--dir", "/redis-data"]
44 
+
45 
+
46 
+We need to ``EXPOSE`` the default port of 6379 so that our link knows what ports
47 
+to connect to our redis container on.  If you do not expose any ports for the
48 
+image then docker will not be able to establish the link between containers.
49 
+
50 
+
51 
+Run the redis container
52 
+-----------------------
53 
+
54 
+.. code-block:: bash
55 
+
56 
+    docker run -d -e PASSWORD=docker crosbymichael/redis --requirepass=docker
57 
+
58 
+This will run our redis container using the default port of 6379 and using
59 
+as password to secure our service. Next we will link the redis container to
60 
+a new name using ``docker link`` and ``docker ls``.
61 
+
62 
+
63 
+Linking an existing container
64 
+-----------------------------
65 
+
66 
+.. code-block:: bash
67 
+
68 
+    docker ls
69 
+
70 
+    NAME                                                                      ID                                                                 IMAGE
71 
+    /39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89         39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89   crosbymichael/redis:latest
72 
+
73 
+
74 
+Docker will automatically create an initial link with the container's id but
75 
+because the is long and not very user friendly we can link the container with
76 
+a new name.
77 
+
78 
+.. code-block:: bash
79 
+
80 
+    docker link /39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 /redis
81 
+
82 
+    docker ls
83 
+
84 
+    NAME                                                                      ID                                                                 IMAGE
85 
+    /redis                                                                    39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89   crosbymichael/redis:latest
86 
+    /39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89         39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89   crosbymichael/redis:latest
87 
+
88 
+Now we can reference our running redis service using the friendly name ``/redis``.
89 
+We can issue all the commands that you would expect; start, stop, attach, using the new name.
90 
+
91 
+Linking redis as a child
92 
+------------------------
93 
+
94 
+Next we can start a new web application that has a dependency on redis and apply a link
95 
+to connect both containers.  If you noticed when running our redis service we did not use
96 
+the ``-p`` option to publish the redis port to the host system.  Redis exposed port 6379
97 
+but we did not publish the port.  This allows docker to prevent all network traffic to
98 
+the redis container except when explicitly specified within a link.  This is a big win
99 
+for security.
100 
+
101 
+
102 
+Now lets start our web application with a link into redis.
103 
+
104 
+.. code-block:: bash
105 
+
106 
+    docker run -t -i -link /redis:db ubuntu bash
107 
+
108 
+    root@4c01db0b339c:/# env
109 
+
110 
+    HOSTNAME=4c01db0b339c
111 
+    DB_NAME=/4c01db0b339cf19958731255a796ee072040a652f51652a4ade190ab8c27006f/db
112 
+    TERM=xterm
113 
+    DB_PORT=tcp://172.17.0.8:6379
114 
+    DB_PORT_6379_TCP=tcp://172.17.0.8:6379
115 
+    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
116 
+    PWD=/
117 
+    DB_ENV_PASSWORD=dockerpass
118 
+    SHLVL=1
119 
+    HOME=/
120 
+    container=lxc
121 
+    _=/usr/bin/env
122 
+    root@4c01db0b339c:/#
123 
+
124 
+
125 
+When we inspect the environment of the linked container we can see a few extra environment
126 
+variables have been added.  When you specified ``-link /redis:db`` you are telling docker
127 
+to link the container named ``/redis`` into this new container with the alias ``db``.
128 
+Environment variables are prefixed with the alias so that the parent container can access
129 
+network and environment information from the child.
130 
+
131 
+.. code-block:: bash
132 
+
133 
+    # The name of the child container
134 
+    DB_NAME=/4c01db0b339cf19958731255a796ee072040a652f51652a4ade190ab8c27006f/db
135 
+    # The default protocol, ip, and port of the service running in the container
136 
+    DB_PORT=tcp://172.17.0.8:6379
137 
+    # A specific protocol, ip, and port of various services
138 
+    DB_PORT_6379_TCP=tcp://172.17.0.8:6379
139 
+    # Get environment variables of the container
140 
+    DB_ENV_PASSWORD=dockerpass
141 
+
142 
+
143 
+Accessing the network information along with the environment of the child container allows
144 
+us to easily connect to the redis service on the specific ip and port and use the password
145 
+specified in the environment.
gograph/MAINTAINERS
History View file @ 04f0927
0 146 
new file mode 100644
... ... 
@@ -0,0 +1 @@
0 
+Michael Crosby <michael@crosbymichael.com> (@crosbymichael)
iptables/MAINTAINERS
History View file @ 04f0927
0 1 
new file mode 100644
... ... 
@@ -0,0 +1 @@
0 
+Michael Crosby <michael@crosbymichael.com> (@crosbymichael)
proxy/MAINTAINERS
History View file @ 04f0927
0 1 
new file mode 100644
... ... 
@@ -0,0 +1 @@
0 
+Michael Crosby <michael@crosbymichael.com> (@crosbymichael)