diff --git a/docs/sources/commandline/cli.rst b/docs/sources/commandline/cli.rst index 62dd3707a..f30186e54 100644 --- a/docs/sources/commandline/cli.rst +++ b/docs/sources/commandline/cli.rst @@ -54,10 +54,14 @@ Available Commands .. include:: command/kill.rst +.. include:: command/link.rst + .. include:: command/login.rst .. include:: command/logs.rst +.. include:: command/ls.rst + .. include:: command/port.rst .. include:: command/ps.rst diff --git a/docs/sources/commandline/command/link.rst b/docs/sources/commandline/command/link.rst new file mode 100644 index 000000000..5ab5aad3f --- /dev/null +++ b/docs/sources/commandline/command/link.rst @@ -0,0 +1,29 @@ +:title: Link Command +:description: Add a link or rename the link for a container +:keywords: link, docker, container, documentation, link, links + +============================================================================ +``link`` -- Add a link or rename the link for a container +============================================================================ + +:: + + Usage: docker link CURRENT_NAME NEW_NAME + + Link a container to a new name. + + +Examples: +-------- + +.. code-block:: bash + + $ docker link /59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc /redis + $ docker ls + NAME ID IMAGE + /redis 59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc crosbymichael/redis:latest + /59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc 59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc crosbymichael/redis:latest + + +This will create a new link for the existing name ``/59669e088202c2ebe150b4346cb3301562d073b51261176a354a74e8f618bfbc`` +with the new name ``/redis`` so that we can new reference the same container under the new name ``/redis``. diff --git a/docs/sources/commandline/command/ls.rst b/docs/sources/commandline/command/ls.rst new file mode 100644 index 000000000..0da681336 --- /dev/null +++ b/docs/sources/commandline/command/ls.rst @@ -0,0 +1,29 @@ +:title: Ls Command +:description: Ls all links for containers +:keywords: ls, docker, container, documentation, link, links + +============================================================================ +``ls`` -- List all links for containers +============================================================================ + +:: + + Usage: docker ls + + List all links for containers and display the relationship between parent + and child containers. + + +Examples: +-------- + +.. code-block:: bash + + $ docker ls + NAME ID IMAGE + /redis 39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 crosbymichael/redis:latest + /webapp cffb86ffa80b11cd8777d300759ee53c4e61729431c30ec9552dd9e6d3abc87d demo:latest + /webapp/redis 39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 crosbymichael/redis:latest + +This will display all links and the names that you can use the reference the link. Parent child +relationships are also displayed with ls. diff --git a/docs/sources/commandline/command/rm.rst b/docs/sources/commandline/command/rm.rst index 8a2309ce7..189e3bebc 100644 --- a/docs/sources/commandline/command/rm.rst +++ b/docs/sources/commandline/command/rm.rst @@ -11,3 +11,26 @@ Usage: docker rm [OPTIONS] CONTAINER Remove one or more containers + -link="": Remove the link instead of the actual container + + +Examples: +-------- + +.. code-block:: bash + + $ docker rm /redis + /redis + + +This will remove the container referenced under the link ``/redis``. + + +.. code-block:: bash + + $ docker rm -link /webapp/redis + /webapp/redis + + +This will remove the underlying link between ``/webapp`` and the ``/redis`` containers removing all +network communication. diff --git a/docs/sources/commandline/command/run.rst b/docs/sources/commandline/command/run.rst index 88aec87d6..c3fd36406 100644 --- a/docs/sources/commandline/command/run.rst +++ b/docs/sources/commandline/command/run.rst @@ -33,6 +33,7 @@ -w="": Working directory inside the container -lxc-conf=[]: Add custom lxc options -lxc-conf="lxc.cgroup.cpuset.cpus = 0,1" -expose=[]: Expose a port from the container without publishing it to your host + -link="": Add link to another container (containerid:alias) Examples -------- @@ -83,4 +84,34 @@ working directory, by changing into the directory to the value returned by ``pwd``. So this combination executes the command using the container, but inside the current working directory. +.. code-block:: bash + docker run -p 127.0.0.0::80 ubuntu bash + +This the ``-p`` flag now allows you to bind a port to a specific +interface of the host machine. In this example port ``80`` of the +container will have a dynamically allocated port bound to 127.0.0.1 +of the host. + +.. code-block:: bash + + docker run -p 127.0.0.1:80:80 ubuntu bash + +This will bind port ``80`` of the container to port ``80`` on 127.0.0.1 of your +host machine. + +.. code-block:: bash + + docker run -expose 80 ubuntu bash + +This will expose port ``80`` of the container for use within a link +without publishing the port to the host system's interfaces. + +.. code-block:: bash + + docker run -link /redis:redis ubuntu bash + +The ``-link`` flag will link the container named ``/redis`` into the +newly created container with the alias ``redis``. The new container +can access the network and environment of the redis container via +environment variables. diff --git a/docs/sources/examples/index.rst b/docs/sources/examples/index.rst index 01251680b..74a7e7c40 100644 --- a/docs/sources/examples/index.rst +++ b/docs/sources/examples/index.rst @@ -1,6 +1,6 @@ :title: Docker Examples :description: Examples on how to use Docker -:keywords: docker, hello world, node, nodejs, python, couch, couchdb, redis, ssh, sshd, examples, postgresql +:keywords: docker, hello world, node, nodejs, python, couch, couchdb, redis, ssh, sshd, examples, postgresql, link .. _example_list: @@ -24,3 +24,4 @@ to more substantial services like you might find in production. postgresql_service mongodb running_riak_service + linking_into_redis diff --git a/docs/sources/examples/linking_into_redis.rst b/docs/sources/examples/linking_into_redis.rst new file mode 100644 index 000000000..6c9b7a4ff --- /dev/null +++ b/docs/sources/examples/linking_into_redis.rst @@ -0,0 +1,146 @@ +:title: Linking to an Redis container +:description: Running redis linked into your web app +:keywords: docker, example, networking, redis, link + +.. _linking_redis: + +Linking Redis +============= + +.. include:: example_header.inc + +Building a redis container to link as a child of our web application. + +Building the redis container +---------------------------- + +We will use a pre-build version of redis from the index under +the name ``crosbymichael/redis``. If you are interested in the +Dockerfile that was used to build this container here it is. + +.. code-block:: bash + + # Build redis from source + # Make sure you have the redis source code checked out in + # the same directory as this Dockerfile + FROM ubuntu + + RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list + RUN apt-get update + RUN apt-get upgrade -y + + RUN apt-get install -y gcc make g++ build-essential libc6-dev tcl + + ADD . /redis + + RUN (cd /redis && make) + RUN (cd /redis && make test) + + RUN mkdir -p /redis-data + VOLUME ["/redis-data"] + EXPOSE 6379 + + ENTRYPOINT ["/redis/src/redis-server"] + CMD ["--dir", "/redis-data"] + + +We need to ``EXPOSE`` the default port of 6379 so that our link knows what ports +to connect to our redis container on. If you do not expose any ports for the +image then docker will not be able to establish the link between containers. + + +Run the redis container +----------------------- + +.. code-block:: bash + + docker run -d -e PASSWORD=docker crosbymichael/redis --requirepass=docker + +This will run our redis container using the default port of 6379 and using +as password to secure our service. Next we will link the redis container to +a new name using ``docker link`` and ``docker ls``. + + +Linking an existing container +----------------------------- + +.. code-block:: bash + + docker ls + + NAME ID IMAGE + /39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 crosbymichael/redis:latest + + +Docker will automatically create an initial link with the container's id but +because the is long and not very user friendly we can link the container with +a new name. + +.. code-block:: bash + + docker link /39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 /redis + + docker ls + + NAME ID IMAGE + /redis 39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 crosbymichael/redis:latest + /39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 39588b6a45100ef5b328b2c302ea085624f29e6cbab70f88be04793af02cec89 crosbymichael/redis:latest + +Now we can reference our running redis service using the friendly name ``/redis``. +We can issue all the commands that you would expect; start, stop, attach, using the new name. + +Linking redis as a child +------------------------ + +Next we can start a new web application that has a dependency on redis and apply a link +to connect both containers. If you noticed when running our redis service we did not use +the ``-p`` option to publish the redis port to the host system. Redis exposed port 6379 +but we did not publish the port. This allows docker to prevent all network traffic to +the redis container except when explicitly specified within a link. This is a big win +for security. + + +Now lets start our web application with a link into redis. + +.. code-block:: bash + + docker run -t -i -link /redis:db ubuntu bash + + root@4c01db0b339c:/# env + + HOSTNAME=4c01db0b339c + DB_NAME=/4c01db0b339cf19958731255a796ee072040a652f51652a4ade190ab8c27006f/db + TERM=xterm + DB_PORT=tcp://172.17.0.8:6379 + DB_PORT_6379_TCP=tcp://172.17.0.8:6379 + PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + PWD=/ + DB_ENV_PASSWORD=dockerpass + SHLVL=1 + HOME=/ + container=lxc + _=/usr/bin/env + root@4c01db0b339c:/# + + +When we inspect the environment of the linked container we can see a few extra environment +variables have been added. When you specified ``-link /redis:db`` you are telling docker +to link the container named ``/redis`` into this new container with the alias ``db``. +Environment variables are prefixed with the alias so that the parent container can access +network and environment information from the child. + +.. code-block:: bash + + # The name of the child container + DB_NAME=/4c01db0b339cf19958731255a796ee072040a652f51652a4ade190ab8c27006f/db + # The default protocol, ip, and port of the service running in the container + DB_PORT=tcp://172.17.0.8:6379 + # A specific protocol, ip, and port of various services + DB_PORT_6379_TCP=tcp://172.17.0.8:6379 + # Get environment variables of the container + DB_ENV_PASSWORD=dockerpass + + +Accessing the network information along with the environment of the child container allows +us to easily connect to the redis service on the specific ip and port and use the password +specified in the environment. diff --git a/gograph/MAINTAINERS b/gograph/MAINTAINERS new file mode 100644 index 000000000..1e998f8ac --- /dev/null +++ b/gograph/MAINTAINERS @@ -0,0 +1 @@ +Michael Crosby (@crosbymichael) diff --git a/iptables/MAINTAINERS b/iptables/MAINTAINERS new file mode 100644 index 000000000..1e998f8ac --- /dev/null +++ b/iptables/MAINTAINERS @@ -0,0 +1 @@ +Michael Crosby (@crosbymichael) diff --git a/proxy/MAINTAINERS b/proxy/MAINTAINERS new file mode 100644 index 000000000..1e998f8ac --- /dev/null +++ b/proxy/MAINTAINERS @@ -0,0 +1 @@ +Michael Crosby (@crosbymichael)