Docker/baseimage-docker
1
0
Fork 1
mirror of https://github.com/phusion/baseimage-docker.git synced 2026-03-26 04:18:46 +00:00
Code Issues Releases Wiki Activity
Files
b618cf9d31389e2454d0ba5e1c370b6ad0853191
baseimage-docker/index.html
Hongli Lai (Phusion) b618cf9d31 Fix indenting
2014-02-02 13:19:37 +01:00

309 lines
17 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<!-- Design by http://www.blacktie.co/2013/10/minimal-dark-bootstrap-3-theme/#more-54 -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="">
<link rel="shortcut icon" href="assets/ico/favicon.png">
<title>Baseimage-docker: A minimal Ubuntu base image modified for Docker-friendliness</title>
<!-- Bootstrap core CSS -->
<link href="assets/css/bootstrap.css" rel="stylesheet">
<!-- Custom styles for this template -->
<link href="assets/css/main.css" rel="stylesheet">
<link rel="stylesheet" href="assets/css/font-awesome.min.css">
<link href='http://fonts.googleapis.com/css?family=Oswald:400,300,700' rel='stylesheet' type='text/css'>
<link href='http://fonts.googleapis.com/css?family=EB+Garamond' rel='stylesheet' type='text/css'>
<link href='http://fonts.googleapis.com/css?family=Open+Sans:600' rel='stylesheet' type='text/css'>
<style type="text/css">
body {
background-color: #3f3f3f;
}
#headerwrap {
min-height: 800px;
}
a.btn {
font-family: 'Open Sans', sans-serif;
font-weight: 600;
}
#eyecatcher_nav a {
width: 19em;
}
#f {
text-align: left;
background: #3f3f3f;
}
#f h1, #f h2, #f h3 {
color: white;
text-align: center;
}
#f h1 {
font-weight: bold;
}
#f h2 {
font-weight: 700;
margin: 1em 0 1em 0;
}
h2.quote {
font-family: 'EB Garamond', serif;
}
blockquote, dt, dd, ul, li {
color: white;
font-size: 20px;
}
dd {
margin-left: 1.5em;
margin-bottom: 0.5em;
}
pre {
overflow: auto;
word-wrap: normal;
white-space: pre;
}
</style>
</head>
<body data-spy="scroll" data-offset="0" data-target="#theMenu">
<!-- ========== HEADER SECTION ========== -->
<section id="home" name="home"></section>
<div id="headerwrap">
<div class="container">
<br>
<div class="row">
<h1>
<span style="display: block; margin-bottom: 0.5em">YOUR DOCKER IMAGE<br>MIGHT BE BROKEN</span>
<span style="font-size: 80%">without you knowing it</span>
</h1>
<br>
<h3>Learn the right way to build your Dockerfile.</h3>
<br><br>
<div id="eyecatcher_nav">
<div class="hidden-xs hidden-sm">
<a href="#intro" class="btn btn-primary btn-lg" style="margin-right: 0.75em">What are you talking about?</a>
<a href="#solution" class="btn btn-info btn-lg">Get the solution: baseimage-docker</a>
</div>
<div class="visible-xs visible-sm">
<a href="#intro" class="btn btn-primary btn-lg">What are you talking about?</a><br><br>
<a href="#solution" class="btn btn-info btn-lg">Get the solution: baseimage-docker</a>
</div>
</div>
<br>
<br>
</div>
</div><!-- /container -->
</div><!-- /headerwrap -->
<!-- ========== ABOUT SECTION ========== -->
<section id="about" name="about"></section>
<div id="f">
<div class="container">
<div class="row">
<h1 id="intro">So you're building a Docker image. What might be wrong with it?</h1>
<p class="centered"><i class="icon icon-circle"></i><i class="icon icon-circle"></i><i class="icon icon-circle"></i></p>
<!-- INTRO INFORMATIO-->
<div class="col-lg-6 col-lg-offset-3">
<p>You learned about <a href="http://www.docker.io">Docker</a>. It's awesome and you're excited. You go and create a Dockerfile:</p>
<pre>FROM ubuntu:12.04
RUN apt-get install all_my_dependencies
ADD my_app_files /my_app
CMD ["/my_app/start.sh"]</pre>
<p>Cool, it seems to work. Pretty easy, right?</p>
<p>Not so fast.</p>
<p>You just built a container which contains a minimal operating system, and which only runs your app. But the operating system inside the container is not configured correctly. <em>A proper Unix system</em> should run all kinds of important system services. You're not running them, you're only running your app.</p>
<h2 class="quote">"What do you mean? I'm just using Ubuntu in Docker. Doesn't the OS inside the container take care of everything automatically?"</h2>
<p>Not quite. You have Ubuntu <em>installed</em> in Docker. The files are there. But that doesn't mean Ubuntu's running as it should.</p>
<p>When your Docker container starts, <em>only</em> the CMD command is run. The only processes that will be running inside the container is the CMD command, and all processes that it spawns. That's why all kinds of important system services are not run automatically &ndash; you have to run them yourself.</p>
<p>Furthermore, Ubuntu is not designed to be run inside Docker. Its init system, Upstart, assumes that it's running on either real hardware or virtualized hardware, but not inside a Docker container, which is a locked down environment with e.g. no direct access to many kernel resources. Normally, that's okay: inside a container you don't want to run Upstart anyway. You don't want a full system, you want a minimal system. But configuring that minimal system for use within a container has many strange corner cases that are hard to get right if you are not intimately familiar with the Unix system model. This can cause a lot of strange problems.</p>
<h2 class="quote">"What important system services am I missing?"</h2>
<dl>
<dt>A <em>correct</em> init process</dt>
<dd>
<p>Here's how the Unix process model works. When a system is started, the first process in the system is called <a href="https://en.wikipedia.org/wiki/Init">the init process</a>, with PID 1. The system halts when this processs halts. If you call <code>CMD ["/my_app/start.sh"]</code> in your Dockerfile, then start.sh is your init process.</p>
<p>But the init process has an extra responsibility. It inherits all <a href="https://en.wikipedia.org/wiki/Orphan_process">orphaned child processes</a>. It is expected that the init process <a href="https://en.wikipedia.org/wiki/Wait_(system_call)">reaps them</a>.</p>
<p>Most likely, your init process is not doing that at all. As a result your container will become filled with <a href="https://en.wikipedia.org/wiki/Zombie_process">zombie processes</a> over time.</p>
<p>Furthermore, <code>docker stop</code> sends SIGTERM to the init process, which is then supposed to stop all services. If your init process is your app, then it'll probably only shut down itself, not all the other processes in the container. The kernel will then forcefully kill those other processes, not giving them a chance to gracefully shut down, potentially resulting in file corruption, stale temporary files, etc. You really want to shut down all your processes gracefully.</p>
</dd>
<dt>syslog</dt>
<dd>
<p>Syslog is the standard Unix logging service. A syslog daemon is necessary so that many services - including the kernel itself - can correctly log to /var/log/syslog. If no syslog daemon is running, a lot of important messages are silently swallowed. You don't want warnings and errors to be silently swallowed, do you?</p>
<p>The syslog daemon is not run automatically. You have to start it yourself.</p>
</dd>
<dt>cron</dt>
<dd>
<p>Many apps use cron services. But cron jobs never get run until the cron daemon is running. Your container.</p>
<p>The cron daemon is not run automatically. You have to start it yourself.</p>
</dd>
<dt>SSH daemon</dt>
<dd>
<p>Your container is a full OS. It can run all kinds of things. Occasionally, you will have to administer it, e.g. checking its CPU usage and memory usage, inspecting what your app is doing, etc.</p>
<p>It's hard to do that properly from outside the container. You really should have a way to login to the container. That's why you should run an SSH daemon, so that you can SSH into the container.</p>
<p>The SSH daemon is not run automatically. You have to start it yourself.</p>
</dd>
</dl>
<h2 class="quote">"Does all this apply too if I'm using CentOS inside the container, or another Linux distribution?"</h2>
<p>Yes. The problem exist in those cases too.</p>
<h2 class="quote">"But I thought Docker is about running a single process in a container?"</h2>
<p>Absolutely not true. Docker runs fine with multiple processes in a container. In fact, there is no technical reason why you should limit yourself to one process &ndash; it only makes things harder for you and breaks all kinds of essential system functionality, e.g. syslog.</p>
<p>We <em>encourage</em> you to use multiple processes.</p>
<p>Managing multiple processes can be painful, but it doesn't have to. We have a solution for that, so read on.</p>
</div>
</div>
<div class="row">
<h1 id="solution">Getting everything right: baseimage-docker</h1>
<p class="centered"><i class="icon icon-circle"></i><i class="icon icon-circle"></i><i class="icon icon-circle"></i></p>
<div class="col-lg-6 col-lg-offset-3">
<p>Solving <a href="#intro">all the aforementioned problems</a> is a huge pain. I'm sure you have better things to do than to worry about them. That's where <a href="https://github.com/phusion/baseimage-docker">baseimage-docker</a> jumps in.</p>
<p>Baseimage-docker is a special Docker image that is configured for correct use within Docker containers. It is Ubuntu, plus modifications for Docker-friendliness. Every single of the aforementioned problem is taken care of for you.</p>
<p>You can use it as a base for your own Docker images. That means it's available for pulling from <a href="https://index.docker.io/u/phusion/baseimage/">the Docker registry</a>!</p>
<p class="centered"><a href="https://github.com/phusion/baseimage-docker" class="btn btn-info">Github</a>
<a href="https://index.docker.io/u/phusion/baseimage/" class="btn btn-primary">Docker registry</a>
<a href="https://groups.google.com/d/forum/passenger-docker" class="btn btn-info">Discussion forum</a>
<a href="https://twitter.com/phusion_nl" class="btn btn-info">Twitter</a>
<a href="http://blog.phusion.nl/" class="btn btn-info">Blog</a></p>
<h2>Why use baseimage-docker?</h2>
<p>You can configure the stock <code>ubuntu</code> image yourself from your Dockerfile, so why bother using baseimage-docker?</p>
<ul>
<li><strong>Stop reinventing the wheel.</strong><br>Configuring the base system for Docker-friendliness is no easy task. As stated before, there are many corner cases. By the time that you've gotten all that right, you've reinvented baseimage-docker. Using baseimage-docker will save you from this effort.</li>
<li><strong>Reduce development time.</strong><br>It reduces the time needed to write a correct Dockerfile. You won't have to worry about the base system and can focus on your stack and your app.</li>
<li><strong>Reduce building time.</strong><br>It reduces the time needed to run <code>docker build</code>, allowing you to iterate your Dockerfile more quickly.</li>
<li><strong>Reduce deployment time.</strong><br>It reduces download time during redeploys. Docker only needs to download the base image once: during the first deploy. On every subsequent deploys, only the changes you make on top of the base image are downloaded.</li>
<h2>What's included?</h2>
<dl>
<dt>A <em>correct</em> init process</dt>
<dd>
Baseimage-docker comes with an init process <code>/sbin/my_init</code> that reaps orphaned child processes correctly, and responds to SIGTERM correctly. This way your container won't become filled with zombie processes, and <code>docker stop</code> will work correctly.
</dd>
<dt>Fixes APT incompatibilities with Docker</dt>
<dd>See <a href="https://github.com/dotcloud/docker/issues/1024">Docker issue #1024</a>.</dd>
<dt>syslog-ng</dt>
<dd>It runs a syslog daemon so that important system messages don't get lost.</dd>
<dt>cron daemon</dt>
<dd>It runs a cron daemon so that cronjobs work.</dd>
<dt>SSH server</dt>
<dd><p>Allows you to easily login to your container to inspect or administer things.</p>
<p>Password and challenge-response authentication are disabled by default. Only key authentication is allowed.</p>
<p><em><strong>Security note</strong>: by default, it allows access to a predefined key, in order to make debugging easy. You should replace this ASAP. See the instructions in the documentation.</em>
</dd>
<dt><a href="http://smarden.org/runit/">runit</a></dt>
<dd><p>Used for service supervision and management. Much easier to use than SysV init and supports restarting daemons when they crash. Much easier to use and more lightweight than Upstart.</p>
<p>Baseimage-docker <em>encourages</em> you to run multiple processes through the use of runit.</p>
<p>You might be familiar with supervisord. Runit (written in C) is much lighter weight than supervisord (written in Python).</p>
</dd>
<dt>setuser</dt>
<dd>A custom tool for running a command as another user. Easier to use than <code>su</code>, has a smaller attack vector than <code>sudo</code>, and unlike <code>chpst</code> this tool sets <code>$HOME</code> correctly. Available as <code>/sbin/setuser</code>.</dd>
</dl>
<p>Despite all these components, baseimage-docker is extremely lightweight: it only consumes 6 MB of memory.</p>
</div>
</div>
<div class="row">
<h1 id="solution">GETTING STARTED NOW</h1>
<p class="centered"><i class="icon icon-circle"></i><i class="icon icon-circle"></i><i class="icon icon-circle"></i></p>
<div class="col-lg-6 col-lg-offset-3">
<p>The image is called <code>phusion/baseimage</code>, and is available on the Docker registry.</p>
<p>By default, it allows SSH access for <a href="https://github.com/phusion/baseimage-docker/blob/master/image/insecure_key.pub">a predefined key</a>. This makes it easy for you to login to the container, but <strong>you should replace this key as soon as possible</strong>.</p>
<p>Example Dockerfile:</p>
<pre># Use phusion/baseimage as base image. To make your builds
# reproducible, make sure you lock down to a specific version, not
# to `latest`! See
# https://github.com/phusion/baseimage-docker/blob/master/Changelog.md
# for a list of version numbers.
FROM phusion/baseimage:&lt;VERSION&gt;
# Set correct environment variables.
ENV HOME /root
# Remove authentication rights for insecure_key.
RUN rm -f /root/.ssh/authorized_keys /home/*/.ssh/authorized_keys
# Regenerate SSH host keys. baseimage-docker does not contain any, so you
# have to do that yourself. You may also comment out this instruction; the
# init system will auto-generate one during boot.
RUN /etc/my_init.d/00_regen_ssh_host_keys.sh
# Use baseimage-docker's init system.
CMD ["/sbin/my_init"]
# ...put your own build instructions here...
# Clean up APT when done.
RUN apt-get clean &amp;&amp; rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*</pre>
<h2>More documentation</h2>
<p>This website only covers the basics. Please refer to <a href="https://github.com/phusion/baseimage-docker#readme">the Github repository</a> for more documentation. Topics include:</p>
<ul>
<li>Adding additional daemons</li>
<li>Running scripts during container startup</li>
<li>Instructions on logging into the container</li>
</ul>
<h2>You may also want to check out these</h2>
<ul>
<li>Using baseimage-docker? <a href="https://twitter.com/share">Tweet about us</a> or <a href="https://twitter.com/phusion_nl">follow us on Twitter</a>.</li>
<li>Having problems? Want to participate in development? Please post a message at <a href="https://groups.google.com/d/forum/passenger-docker">the discussion forum</a>.</li>
<li>Looking for a more complete base image, one that is ideal for <strong>Ruby, Python, Node.js and Meteor web apps</strong>? Take a look at <a href="https://github.com/phusion/passenger-docker">passenger-docker</a>.</li>
</ul>
</div>
</div>
</div><!-- /container -->
</div><!-- /f -->
<!-- ========== CONTACT SECTION ========== -->
<section id="contact" name="contact"></section>
<div id="f">
<div class="container">
<div class="row">
<h3>BROUGHT TO YOU BY PHUSION</h3>
<p class="centered"><i class="icon icon-circle"></i><i class="icon icon-circle"></i><i class="icon icon-circle"></i></p>
<div class="col-lg-6 col-lg-offset-3 centered">
<a href="https://www.phusionpassenger.com"><img src="icon.png" width="350" height="350" alt="Phusion"></a>
</div>
</div>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink