From 8cf0f2dbe54e5ff5175a830af30ba428f8b1f526 Mon Sep 17 00:00:00 2001 From: Andy Rothfusz Date: Wed, 9 Oct 2013 12:31:40 -0700 Subject: [PATCH] Update documentation --- docs/sources/use/host_integration.rst | 139 ++++++++++++++++++-------- 1 file changed, 98 insertions(+), 41 deletions(-) diff --git a/docs/sources/use/host_integration.rst b/docs/sources/use/host_integration.rst index cc2f56a5c7..47d9ea7528 100644 --- a/docs/sources/use/host_integration.rst +++ b/docs/sources/use/host_integration.rst @@ -2,67 +2,124 @@ :description: How to generate scripts for upstart, systemd, etc. :keywords: systemd, upstart, supervisor, docker, documentation, host integration + + +Host Integration +================ + +You can use your Docker containers with process managers like ``upstart``, +``systemd`` and ``supervisor``. + Introduction -============ +------------ -When you have finished setting up your image and are happy with your running -container, you may want to use a process manager like `upstart` or `systemd`. +When you have finished setting up your image and are happy with your +running container, you may want to use a process manager to manage +it. To help with this, we provide a simple image: ``creack/manger:min`` -In order to do so, we provide a simple image: creack/manger:min. - -This image takes the container ID as parameter. We also can specify the kind of -process manager and meta datas like Author and Description. - -If no process manager is specified, then `upstart` is assumed. - -Note: The result will be an output to stdout. +This image takes the container ID as parameter. We also can specify +the kind of process manager and metadata like *Author* and +*Description*. The output will will be text suitable for a +configuration file, echoed to stdout. It is up to you to create the +.conf file (for `upstart +`_) or +.service file (for `systemd +`_) and +put it in the right place for your system. Usage -===== -Usage: docker run creack/manager:min [OPTIONS] +----- + +.. code-block:: bash + + docker run creack/manager:min [OPTIONS] + +.. program:: docker run creack/manager:min + +.. cmdoption:: -a="" + + Author of the image + +.. cmdoption:: -d="" + + Description of the image + +.. cmdoption:: -t="upstart" + + Type of manager requested: ``upstart`` or ``systemd`` + +Example Output +.............. + +.. code-block:: bash + + docker run creack/manager:min -t="systemd" b28605f2f9a4 + [Unit] + Description= + Author= + After=docker.service + + [Service] + Restart=always + ExecStart=/usr/bin/docker start -a b28605f2f9a4 + ExecStop=/usr/bin/docker stop -t 2 b28605f2f9a4 + + [Install] + WantedBy=local.target + - -a="": Author of the image - -d="": Description of the image - -t="upstart": Type of manager requested Development -=========== +----------- -The image creack/manager:min is a `busybox` base with the binary as entrypoint. -It is meant to be light and fast to download. +The image ``creack/manager:min`` is a ``busybox`` base with the +compiled binary of ``manager.go`` as the :ref:`Entrypoint +`. It is meant to be light and fast to download. -Now, if you want/need to change or add things, you can download the full -creack/manager repository that contains creack/manager:min and -creack/manager:dev. +If you would like to change or add things, you can download the full +``creack/manager`` repository that contains ``creack/manager:min`` and +``creack/manager:dev``. -The Dockerfiles and the sources are available in `/contrib/host_integration`. +The Dockerfiles and the sources are available in +`/contrib/host_integration +`_. Upstart -======= +------- -Upstart is the default process manager. The generated script will start the -container after docker daemon. If the container dies, it will respawn. -Start/Restart/Stop/Reload are supported. Reload will send a SIGHUP to the container. +Upstart is the default process manager. The generated script will +start the container after the ``docker`` daemon. If the container +dies, it will respawn. Start/Restart/Stop/Reload are +supported. Reload will send a SIGHUP to the container. -Example: -`CID=$(docker run -d creack/firefo-vnc)` -`docker run creack/manager:min -a 'Guillaume J. Charmes ' -d 'Awesome Firefox in VLC' $CID > /etc/init/firefoxvnc.conf` +Example (``upstart`` on Debian) +............................... -You can now do `start firefoxvnc` or `stop firefoxvnc` and if the container +.. code-block:: bash + + CID=$(docker run -d creack/firefo-vnc) + docker run creack/manager:min -a 'Guillaume J. Charmes ' -d 'Awesome Firefox in VLC' $CID > /etc/init/firefoxvnc.conf + +You can now ``start firefoxvnc`` or ``stop firefoxvnc`` and if the container dies for some reason, upstart will restart it. Systemd -======= +------- -In order to generate a systemd script, we need to -t option. The generated -script will start the container after docker daemon. If the container dies, it -will respawn. -Start/Restart/Reload/Stop are supported. +In order to generate a systemd script, we need to use the ``-t`` +option. The generated script will start the container after docker +daemon. If the container dies, it will respawn. +``Start/Restart/Reload/Stop`` are supported. -Example (fedora): -`CID=$(docker run -d creack/firefo-vnc)` -`docker run creack/manager:min -t systemd -a 'Guillaume J. Charmes ' -d 'Awesome Firefox in VLC' $CID > /usr/lib/systemd/system/firefoxvnc.service` +Example (``systemd`` on Fedora) +............................... -You can now do `systemctl start firefoxvnc` or `systemctl stop firefoxvnc` -and if the container dies for some reason, systemd will restart it. +.. code-block:: bash + + CID=$(docker run -d creack/firefo-vnc) + docker run creack/manager:min -t systemd -a 'Guillaume J. Charmes ' -d 'Awesome Firefox in VLC' $CID > /usr/lib/systemd/system/firefoxvnc.service + +You can now run ``systemctl start firefoxvnc`` or ``systemctl stop +firefoxvnc`` and if the container dies for some reason, ``systemd`` +will restart it.