github.com/moby/docker@v26.1.3+incompatible/project/PACKAGERS.md (about)

     1  # Dear Packager,
     2  
     3  If you are looking to make Docker available on your favorite software
     4  distribution, this document is for you. It summarizes the requirements for
     5  building and running the Docker client and the Docker daemon.
     6  
     7  ## Package Name
     8  
     9  If possible, your package should be called "docker". If that name is already
    10  taken, a second choice is "docker-engine". Another possible choice is "docker.io".
    11  
    12  ## Official Build vs Distro Build
    13  
    14  The Docker project maintains its own build and release toolchain. It is pretty
    15  neat and entirely based on Docker (surprise!). This toolchain is the canonical
    16  way to build Docker. We encourage you to give it a try, and if the circumstances
    17  allow you to use it, we recommend that you do.
    18  
    19  You might not be able to use the official build toolchain - usually because your
    20  distribution has a toolchain and packaging policy of its own. We get it! Your
    21  house, your rules. The rest of this document should give you the information you
    22  need to package Docker your way, without denaturing it in the process.
    23  
    24  ## Build Dependencies
    25  
    26  The Dockerfile contains the most up-to-date list of build-time dependencies.
    27  
    28  ### Go Dependencies
    29  
    30  All Go dependencies are vendored under "./vendor". They are used by the official
    31  build, so the source of truth for the current version of each dependency is
    32  whatever is in "./vendor".
    33  
    34  If you would rather (or must, due to distro policy) package these dependencies
    35  yourself, take a look at "vendor.mod" for an easy-to-parse list of the
    36  exact version for each.
    37  
    38  ## Stripping Binaries
    39  
    40  Please, please, please do not strip any compiled binaries. This is really
    41  important.
    42  
    43  In our own testing, stripping the resulting binaries sometimes results in a
    44  binary that appears to work, but more often causes random panics, segfaults, and
    45  other issues. Even if the binary appears to work, please don't strip.
    46  
    47  See the following quotes from Dave Cheney, which explain this position better
    48  from the upstream Golang perspective.
    49  
    50  ### [go issue #5855, comment #3](https://code.google.com/p/go/issues/detail?id=5855#c3)
    51  
    52  > Super super important: Do not strip go binaries or archives. It isn't tested,
    53  > often breaks, and doesn't work.
    54  
    55  ### [launchpad golang issue #1200255, comment #8](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/8)
    56  
    57  > To quote myself: "Please do not strip Go binaries, it is not supported, not
    58  > tested, is often broken, and doesn't do what you want"
    59  >
    60  > To unpack that a bit
    61  >
    62  > * not supported, as in, we don't support it, and recommend against it when
    63  >   asked
    64  > * not tested, we don't test stripped binaries as part of the build CI process
    65  > * is often broken, stripping a go binary will produce anywhere from no, to
    66  >   subtle, to outright execution failure, see above
    67  
    68  ### [launchpad golang issue #1200255, comment #13](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/13)
    69  
    70  > To clarify my previous statements.
    71  >
    72  > * I do not disagree with the debian policy, it is there for a good reason
    73  > * Having said that, it stripping Go binaries doesn't work, and nobody is
    74  >   looking at making it work, so there is that.
    75  >
    76  > Thanks for patching the build formula.
    77  
    78  ## Building Docker
    79  
    80  Please use our build script ("./hack/make.sh") for compilation.
    81  
    82  ### `DOCKER_BUILDTAGS`
    83  
    84  There are build tags for disabling graphdrivers, if necessary. By default,
    85  support for all graphdrivers are built in.
    86  
    87  To disable btrfs:
    88  ```bash
    89  export DOCKER_BUILDTAGS='exclude_graphdriver_btrfs'
    90  ```
    91  
    92  To disable zfs:
    93  ```bash
    94  export DOCKER_BUILDTAGS='exclude_graphdriver_zfs'
    95  ```
    96  
    97  NOTE: if you need to set more than one build tag, space separate them:
    98  ```bash
    99  export DOCKER_BUILDTAGS='exclude_graphdriver_btrfs exclude_graphdriver_zfs'
   100  ```
   101  
   102  ## System Dependencies
   103  
   104  ### Runtime Dependencies
   105  
   106  To function properly, the Docker daemon needs the following software to be
   107  installed and available at runtime:
   108  
   109  * containerd version 1.6.22 or later
   110    * containerd versions 1.7.0 through 1.7.2 are incompatible
   111  * iptables version 1.4 or later
   112  * procps (or similar provider of a "ps" executable)
   113  * e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs)
   114  * xfsprogs (in use: mkfs.xfs)
   115  * XZ Utils version 4.9 or later
   116  * pigz (optional)
   117  
   118  Additionally, the Docker client needs the following software to be installed and
   119  available at runtime:
   120  
   121  * Git version 1.7 or later
   122  
   123  ### Kernel Requirements
   124  
   125  The Docker daemon has very specific kernel requirements. Most pre-packaged
   126  kernels already include the necessary options enabled. If you are building your
   127  own kernel, you should check out `contrib/check-config.sh`.
   128  
   129  Note that in client mode, there are no specific kernel requirements, and that
   130  the client will even run on alternative platforms such as Mac OS X / Darwin.
   131  
   132  ### Optional Dependencies
   133  
   134  Some of Docker's features are activated by using optional command-line flags or
   135  by having support for them in the kernel or userspace. A few examples include:
   136  
   137  * BTRFS graph driver (requires suitable kernel headers: `linux/btrfs.h` and `linux/btrfs_tree.h`, present in 4.12+; and BTRFS support enabled in the kernel)
   138  * ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module)
   139  * Libseccomp to allow running seccomp profiles with containers
   140  
   141  ## Daemon Init Script
   142  
   143  Docker expects to run as a daemon at machine startup. Your package will need to
   144  include a script for your distro's process supervisor of choice. Be sure to
   145  check out the "contrib/init" folder in case a suitable init script already
   146  exists.
   147  
   148  In general, Docker should be run as root, similar to the following:
   149  
   150  ```bash
   151  dockerd
   152  ```
   153  
   154  Generally, it is encouraged that additional configuration be placed in
   155  `/etc/docker/daemon.json`.