diff options
Diffstat (limited to 'docs/sources/examples')
| -rw-r--r-- | docs/sources/examples/apt-cacher-ng.Dockerfile | 15 | ||||
| -rw-r--r-- | docs/sources/examples/apt-cacher-ng.rst | 102 | ||||
| -rw-r--r-- | docs/sources/examples/example_header.inc | 1 | ||||
| -rw-r--r-- | docs/sources/examples/hello_world.rst | 34 | ||||
| -rw-r--r-- | docs/sources/examples/https.rst | 126 | ||||
| -rw-r--r-- | docs/sources/examples/index.rst | 2 | ||||
| -rw-r--r-- | docs/sources/examples/mongodb.rst | 6 | ||||
| -rw-r--r-- | docs/sources/examples/nodejs_web_app.rst | 6 | ||||
| -rw-r--r-- | docs/sources/examples/postgresql_service.Dockerfile | 2 | ||||
| -rw-r--r-- | docs/sources/examples/postgresql_service.rst | 10 | ||||
| -rw-r--r-- | docs/sources/examples/python_web_app.rst | 2 | ||||
| -rw-r--r-- | docs/sources/examples/running_redis_service.rst | 8 | ||||
| -rw-r--r-- | docs/sources/examples/running_riak_service.rst | 2 | ||||
| -rw-r--r-- | docs/sources/examples/running_ssh_service.rst | 4 |
14 files changed, 283 insertions, 37 deletions
diff --git a/docs/sources/examples/apt-cacher-ng.Dockerfile b/docs/sources/examples/apt-cacher-ng.Dockerfile new file mode 100644 index 0000000000..3b7862bb58 --- /dev/null +++ b/docs/sources/examples/apt-cacher-ng.Dockerfile @@ -0,0 +1,15 @@ +# +# Build: docker build -t apt-cacher . +# Run: docker run -d -p 3142:3142 --name apt-cacher-run apt-cacher +# +# and then you can run containers with: +# docker run -t -i --rm -e http_proxy http://dockerhost:3142/ debian bash +# +FROM ubuntu +MAINTAINER SvenDowideit@docker.com + +VOLUME ["/var/cache/apt-cacher-ng"] +RUN apt-get update ; apt-get install -yq apt-cacher-ng + +EXPOSE 3142 +CMD chmod 777 /var/cache/apt-cacher-ng ; /etc/init.d/apt-cacher-ng start ; tail -f /var/log/apt-cacher-ng/* diff --git a/docs/sources/examples/apt-cacher-ng.rst b/docs/sources/examples/apt-cacher-ng.rst new file mode 100644 index 0000000000..dd844d4ef1 --- /dev/null +++ b/docs/sources/examples/apt-cacher-ng.rst @@ -0,0 +1,102 @@ +:title: Running an apt-cacher-ng service +:description: Installing and running an apt-cacher-ng service +:keywords: docker, example, package installation, networking, debian, ubuntu + +.. _running_apt-cacher-ng_service: + +Apt-Cacher-ng Service +===================== + +.. include:: example_header.inc + + +When you have multiple Docker servers, or build unrelated Docker containers +which can't make use of the Docker build cache, it can be useful to have a +caching proxy for your packages. This container makes the second download of +any package almost instant. + +Use the following Dockerfile: + +.. literalinclude:: apt-cacher-ng.Dockerfile + +To build the image using: + +.. code-block:: bash + + $ sudo docker build -t eg_apt_cacher_ng . + +Then run it, mapping the exposed port to one on the host + +.. code-block:: bash + + $ sudo docker run -d -p 3142:3142 --name test_apt_cacher_ng eg_apt_cacher_ng + +To see the logfiles that are 'tailed' in the default command, you can use: + +.. code-block:: bash + + $ sudo docker logs -f test_apt_cacher_ng + +To get your Debian-based containers to use the proxy, you can do one of three things + +1. Add an apt Proxy setting ``echo 'Acquire::http { Proxy "http://dockerhost:3142"; };' >> /etc/apt/conf.d/01proxy`` +2. Set an environment variable: ``http_proxy=http://dockerhost:3142/`` +3. Change your ``sources.list`` entries to start with ``http://dockerhost:3142/`` + +**Option 1** injects the settings safely into your apt configuration in a local +version of a common base: + +.. code-block:: bash + + FROM ubuntu + RUN echo 'Acquire::http { Proxy "http://dockerhost:3142"; };' >> /etc/apt/apt.conf.d/01proxy + RUN apt-get update ; apt-get install vim git + + # docker build -t my_ubuntu . + +**Option 2** is good for testing, but will +break other HTTP clients which obey ``http_proxy``, such as ``curl``, ``wget`` and others: + +.. code-block:: bash + + $ sudo docker run --rm -t -i -e http_proxy=http://dockerhost:3142/ debian bash + +**Option 3** is the least portable, but there will be times when you might need to +do it and you can do it from your ``Dockerfile`` too. + +Apt-cacher-ng has some tools that allow you to manage the repository, and they +can be used by leveraging the ``VOLUME`` instruction, and the image we built to run the +service: + +.. code-block:: bash + + $ sudo docker run --rm -t -i --volumes-from test_apt_cacher_ng eg_apt_cacher_ng bash + + $$ /usr/lib/apt-cacher-ng/distkill.pl + Scanning /var/cache/apt-cacher-ng, please wait... + Found distributions: + bla, taggedcount: 0 + 1. precise-security (36 index files) + 2. wheezy (25 index files) + 3. precise-updates (36 index files) + 4. precise (36 index files) + 5. wheezy-updates (18 index files) + + Found architectures: + 6. amd64 (36 index files) + 7. i386 (24 index files) + + WARNING: The removal action may wipe out whole directories containing + index files. Select d to see detailed list. + + (Number nn: tag distribution or architecture nn; 0: exit; d: show details; r: remove tagged; q: quit): q + + +Finally, clean up after your test by stopping and removing the container, and +then removing the image. + +.. code-block:: bash + + $ sudo docker stop test_apt_cacher_ng + $ sudo docker rm test_apt_cacher_ng + $ sudo docker rmi eg_apt_cacher_ng diff --git a/docs/sources/examples/example_header.inc b/docs/sources/examples/example_header.inc index 0621b39794..5841141e59 100644 --- a/docs/sources/examples/example_header.inc +++ b/docs/sources/examples/example_header.inc @@ -4,4 +4,5 @@ * This example assumes you have Docker running in daemon mode. For more information please see :ref:`running_examples`. * **If you don't like sudo** then see :ref:`dockergroup` + * **If you're using OS X or docker via TCP** then you shouldn't use `sudo` diff --git a/docs/sources/examples/hello_world.rst b/docs/sources/examples/hello_world.rst index 63362e7d7b..39d7abea2c 100644 --- a/docs/sources/examples/hello_world.rst +++ b/docs/sources/examples/hello_world.rst @@ -52,8 +52,8 @@ This command will run a simple ``echo`` command, that will echo ``hello world`` **Explanation:** -- **"sudo"** execute the following commands as user *root* -- **"docker run"** run a command in a new container +- **"sudo"** execute the following commands as user *root* +- **"docker run"** run a command in a new container - **"busybox"** is the image we are running the command in. - **"/bin/echo"** is the command we want to run in the container - **"hello world"** is the input for the echo command @@ -67,9 +67,9 @@ See the example in action .. raw:: html <iframe width="560" height="400" frameborder="0" - sandbox="allow-same-origin allow-scripts" - srcdoc="<body><script type="text/javascript" - src="https://asciinema.org/a/7658.js" + sandbox="allow-same-origin allow-scripts" + srcdoc="<body><script type="text/javascript" + src="https://asciinema.org/a/7658.js" id="asciicast-7658" async></script></body>"> </iframe> @@ -92,7 +92,7 @@ we stop it. .. code-block:: bash - CONTAINER_ID=$(sudo docker run -d ubuntu /bin/sh -c "while true; do echo hello world; sleep 1; done") + container_id=$(sudo docker run -d ubuntu /bin/sh -c "while true; do echo hello world; sleep 1; done") We are going to run a simple hello world daemon in a new container made from the ``ubuntu`` image. @@ -104,30 +104,30 @@ made from the ``ubuntu`` image. - **"while true; do echo hello world; sleep 1; done"** is the mini script we want to run, that will just print hello world once a second until we stop it. -- **$CONTAINER_ID** the output of the run command will return a +- **$container_id** the output of the run command will return a container id, we can use in future commands to see what is going on with this process. .. code-block:: bash - sudo docker logs $CONTAINER_ID + sudo docker logs $container_id Check the logs make sure it is working correctly. - **"docker logs**" This will return the logs for a container -- **$CONTAINER_ID** The Id of the container we want the logs for. +- **$container_id** The Id of the container we want the logs for. .. code-block:: bash - sudo docker attach -sig-proxy=false $CONTAINER_ID + sudo docker attach --sig-proxy=false $container_id Attach to the container to see the results in real-time. - **"docker attach**" This will allow us to attach to a background process to see what is going on. -- **"-sig-proxy=false"** Do not forward signals to the container; allows +- **"--sig-proxy=false"** Do not forward signals to the container; allows us to exit the attachment using Control-C without stopping the container. -- **$CONTAINER_ID** The Id of the container we want to attach too. +- **$container_id** The Id of the container we want to attach to. Exit from the container attachment by pressing Control-C. @@ -141,12 +141,12 @@ Check the process list to make sure it is running. .. code-block:: bash - sudo docker stop $CONTAINER_ID + sudo docker stop $container_id Stop the container, since we don't need it anymore. - **"docker stop"** This stops a container -- **$CONTAINER_ID** The Id of the container we want to stop. +- **$container_id** The Id of the container we want to stop. .. code-block:: bash @@ -162,9 +162,9 @@ See the example in action .. raw:: html <iframe width="560" height="400" frameborder="0" - sandbox="allow-same-origin allow-scripts" - srcdoc="<body><script type="text/javascript" - src="https://asciinema.org/a/2562.js" + sandbox="allow-same-origin allow-scripts" + srcdoc="<body><script type="text/javascript" + src="https://asciinema.org/a/2562.js" id="asciicast-2562" async></script></body>"> </iframe> diff --git a/docs/sources/examples/https.rst b/docs/sources/examples/https.rst new file mode 100644 index 0000000000..7a221ed951 --- /dev/null +++ b/docs/sources/examples/https.rst @@ -0,0 +1,126 @@ +:title: Docker HTTPS Setup +:description: How to setup docker with https +:keywords: docker, example, https, daemon + +.. _running_docker_https: + +Running Docker with https +========================= + +By default, Docker runs via a non-networked Unix socket. It can also optionally +communicate using a HTTP socket. + +If you need Docker reachable via the network in a safe manner, you can enable +TLS by specifying the `tlsverify` flag and pointing Docker's `tlscacert` flag to a +trusted CA certificate. + +In daemon mode, it will only allow connections from clients authenticated by a +certificate signed by that CA. In client mode, it will only connect to servers +with a certificate signed by that CA. + +.. warning:: + + Using TLS and managing a CA is an advanced topic. Please make you self familiar + with openssl, x509 and tls before using it in production. + +Create a CA, server and client keys with OpenSSL +------------------------------------------------ + +First, initialize the CA serial file and generate CA private and public keys: + +.. code-block:: bash + + $ echo 01 > ca.srl + $ openssl genrsa -des3 -out ca-key.pem + $ openssl req -new -x509 -days 365 -key ca-key.pem -out ca.pem + +Now that we have a CA, you can create a server key and certificate signing request. +Make sure that `"Common Name (e.g. server FQDN or YOUR name)"` matches the hostname you will use +to connect to Docker or just use '*' for a certificate valid for any hostname: + +.. code-block:: bash + + $ openssl genrsa -des3 -out server-key.pem + $ openssl req -new -key server-key.pem -out server.csr + +Next we're going to sign the key with our CA: + +.. code-block:: bash + + $ openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem \ + -out server-cert.pem + +For client authentication, create a client key and certificate signing request: + +.. code-block:: bash + + $ openssl genrsa -des3 -out client-key.pem + $ openssl req -new -key client-key.pem -out client.csr + + +To make the key suitable for client authentication, create a extensions config file: + +.. code-block:: bash + + $ echo extendedKeyUsage = clientAuth > extfile.cnf + +Now sign the key: + +.. code-block:: bash + + $ openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca-key.pem \ + -out client-cert.pem -extfile extfile.cnf + +Finally you need to remove the passphrase from the client and server key: + +.. code-block:: bash + + $ openssl rsa -in server-key.pem -out server-key.pem + $ openssl rsa -in client-key.pem -out client-key.pem + +Now you can make the Docker daemon only accept connections from clients providing +a certificate trusted by our CA: + +.. code-block:: bash + + $ sudo docker -d --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \ + -H=0.0.0.0:4243 + +To be able to connect to Docker and validate its certificate, you now need to provide your client keys, +certificates and trusted CA: + +.. code-block:: bash + + $ docker --tlsverify --tlscacert=ca.pem --tlscert=client-cert.pem --tlskey=client-key.pem \ + -H=dns-name-of-docker-host:4243 + +.. warning:: + + As shown in the example above, you don't have to run the ``docker`` + client with ``sudo`` or the ``docker`` group when you use + certificate authentication. That means anyone with the keys can + give any instructions to your Docker daemon, giving them root + access to the machine hosting the daemon. Guard these keys as you + would a root password! + +Other modes +----------- +If you don't want to have complete two-way authentication, you can run Docker in +various other modes by mixing the flags. + +Daemon modes +~~~~~~~~~~~~ +- tlsverify, tlscacert, tlscert, tlskey set: Authenticate clients +- tls, tlscert, tlskey: Do not authenticate clients + +Client modes +~~~~~~~~~~~~ +- tls: Authenticate server based on public/default CA pool +- tlsverify, tlscacert: Authenticate server based on given CA +- tls, tlscert, tlskey: Authenticate with client certificate, do not authenticate + server based on given CA +- tlsverify, tlscacert, tlscert, tlskey: Authenticate with client certificate, + authenticate server based on given CA + +The client will send its client certificate if found, so you just need to drop +your keys into `~/.docker/<ca, cert or key>.pem` diff --git a/docs/sources/examples/index.rst b/docs/sources/examples/index.rst index cf9ed9340a..94e2d917bb 100644 --- a/docs/sources/examples/index.rst +++ b/docs/sources/examples/index.rst @@ -26,3 +26,5 @@ to more substantial services like those which you might find in production. using_supervisord cfengine_process_management python_web_app + apt-cacher-ng + https diff --git a/docs/sources/examples/mongodb.rst b/docs/sources/examples/mongodb.rst index 3e37d74c30..913dc2699a 100644 --- a/docs/sources/examples/mongodb.rst +++ b/docs/sources/examples/mongodb.rst @@ -47,7 +47,7 @@ divert ``/sbin/initctl`` to ``/bin/true`` so it thinks everything is working. # Hack for initctl not being available in Ubuntu RUN dpkg-divert --local --rename --add /sbin/initctl - RUN ln -s /bin/true /sbin/initctl + RUN ln -sf /bin/true /sbin/initctl Afterwards we'll be able to update our apt repositories and install MongoDB @@ -86,10 +86,10 @@ the local port! .. code-block:: bash # Regular style - MONGO_ID=$(sudo docker run -d <yourname>/mongodb) + MONGO_ID=$(sudo docker run -P -d <yourname>/mongodb) # Lean and mean - MONGO_ID=$(sudo docker run -d <yourname>/mongodb --noprealloc --smallfiles) + MONGO_ID=$(sudo docker run -P -d <yourname>/mongodb --noprealloc --smallfiles) # Check the logs out sudo docker logs $MONGO_ID diff --git a/docs/sources/examples/nodejs_web_app.rst b/docs/sources/examples/nodejs_web_app.rst index 68c073da7b..55bd76db89 100644 --- a/docs/sources/examples/nodejs_web_app.rst +++ b/docs/sources/examples/nodejs_web_app.rst @@ -18,7 +18,7 @@ https://github.com/gasi/docker-node-hello. Create Node.js app ++++++++++++++++++ -First, create a ``package.json`` file that describes your app and its +First, create a directory ``src`` where all the files would live. Then create a ``package.json`` file that describes your app and its dependencies: .. code-block:: json @@ -50,7 +50,7 @@ Then, create an ``index.js`` file that defines a web app using the res.send('Hello World\n'); }); - app.listen(PORT) + app.listen(PORT); console.log('Running on http://localhost:' + PORT); @@ -91,7 +91,7 @@ To install the right package for CentOS, we’ll use the instructions from the .. code-block:: bash # Enable EPEL for Node.js - RUN rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm + RUN rpm -Uvh http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm # Install Node.js and npm RUN yum install -y npm diff --git a/docs/sources/examples/postgresql_service.Dockerfile b/docs/sources/examples/postgresql_service.Dockerfile index af1423f258..219a537882 100644 --- a/docs/sources/examples/postgresql_service.Dockerfile +++ b/docs/sources/examples/postgresql_service.Dockerfile @@ -7,7 +7,7 @@ MAINTAINER SvenDowideit@docker.com # Add the PostgreSQL PGP key to verify their Debian packages. # It should be the same key as https://www.postgresql.org/media/keys/ACCC4CF8.asc -RUN apt-key adv --keyserver keyserver.ubuntu.com --recv-keys B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8 +RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8 # Add PostgreSQL's repository. It contains the most recent stable release # of PostgreSQL, ``9.3``. diff --git a/docs/sources/examples/postgresql_service.rst b/docs/sources/examples/postgresql_service.rst index 5a2323471b..488e1530b2 100644 --- a/docs/sources/examples/postgresql_service.rst +++ b/docs/sources/examples/postgresql_service.rst @@ -37,24 +37,24 @@ And run the PostgreSQL server container (in the foreground): .. code-block:: bash - $ sudo docker run -rm -P -name pg_test eg_postgresql + $ sudo docker run --rm -P --name pg_test eg_postgresql There are 2 ways to connect to the PostgreSQL server. We can use :ref:`working_with_links_names`, or we can access it from our host (or the network). -.. note:: The ``-rm`` removes the container and its image when the container +.. note:: The ``--rm`` removes the container and its image when the container exists successfully. Using container linking ^^^^^^^^^^^^^^^^^^^^^^^ Containers can be linked to another container's ports directly using -``-link remote_name:local_alias`` in the client's ``docker run``. This will +``--link remote_name:local_alias`` in the client's ``docker run``. This will set a number of environment variables that can then be used to connect: .. code-block:: bash - $ sudo docker run -rm -t -i -link pg_test:pg eg_postgresql bash + $ sudo docker run --rm -t -i --link pg_test:pg eg_postgresql bash postgres@7ef98b1b7243:/$ psql -h $PG_PORT_5432_TCP_ADDR -p $PG_PORT_5432_TCP_PORT -d docker -U docker --password @@ -104,7 +104,7 @@ configuration and data: .. code-block:: bash - docker run -rm --volumes-from pg_test -t -i busybox sh + docker run --rm --volumes-from pg_test -t -i busybox sh / # ls bin etc lib linuxrc mnt proc run sys usr diff --git a/docs/sources/examples/python_web_app.rst b/docs/sources/examples/python_web_app.rst index 5b8e3f6b4b..33c038f9ab 100644 --- a/docs/sources/examples/python_web_app.rst +++ b/docs/sources/examples/python_web_app.rst @@ -51,7 +51,7 @@ try things out, and then exit when you're done. .. code-block:: bash - $ sudo docker run -i -t -name pybuilder_run shykes/pybuilder bash + $ sudo docker run -i -t --name pybuilder_run shykes/pybuilder bash $$ URL=http://github.com/shykes/helloflask/archive/master.tar.gz $$ /usr/local/bin/buildapp $URL diff --git a/docs/sources/examples/running_redis_service.rst b/docs/sources/examples/running_redis_service.rst index c9424867a4..5a5a1b003f 100644 --- a/docs/sources/examples/running_redis_service.rst +++ b/docs/sources/examples/running_redis_service.rst @@ -18,11 +18,11 @@ Firstly, we create a ``Dockerfile`` for our new Redis image. .. code-block:: bash - FROM ubuntu:12.10 - RUN apt-get update - RUN apt-get -y install redis-server + FROM debian:jessie + RUN apt-get update && apt-get install -y redis-server EXPOSE 6379 ENTRYPOINT ["/usr/bin/redis-server"] + CMD ["--bind", "0.0.0.0"] Next we build an image from our ``Dockerfile``. Replace ``<your username>`` with your own user name. @@ -49,7 +49,7 @@ use a container link to provide access to our Redis database. Create your web application container ------------------------------------- -Next we can create a container for our application. We're going to use the ``-link`` +Next we can create a container for our application. We're going to use the ``--link`` flag to create a link to the ``redis`` container we've just created with an alias of ``db``. This will create a secure tunnel to the ``redis`` container and expose the Redis instance running inside that container to only this container. diff --git a/docs/sources/examples/running_riak_service.rst b/docs/sources/examples/running_riak_service.rst index ae08a4b7f0..55e5e405c9 100644 --- a/docs/sources/examples/running_riak_service.rst +++ b/docs/sources/examples/running_riak_service.rst @@ -88,7 +88,7 @@ Almost there. Next, we add a hack to get us by the lack of ``initctl``: # Hack for initctl # See: https://github.com/dotcloud/docker/issues/1024 RUN dpkg-divert --local --rename --add /sbin/initctl - RUN ln -s /bin/true /sbin/initctl + RUN ln -sf /bin/true /sbin/initctl Then, we expose the Riak Protocol Buffers and HTTP interfaces, along with SSH: diff --git a/docs/sources/examples/running_ssh_service.rst b/docs/sources/examples/running_ssh_service.rst index d27799bee7..4161275019 100644 --- a/docs/sources/examples/running_ssh_service.rst +++ b/docs/sources/examples/running_ssh_service.rst @@ -19,14 +19,14 @@ Build the image using: .. code-block:: bash - $ sudo docker build -rm -t eg_sshd . + $ sudo docker build -t eg_sshd . Then run it. You can then use ``docker port`` to find out what host port the container's port 22 is mapped to: .. code-block:: bash - $ sudo docker run -d -P -name test_sshd eg_sshd + $ sudo docker run -d -P --name test_sshd eg_sshd $ sudo docker port test_sshd 22 0.0.0.0:49154 |