github.com/rawahars/moby@v24.0.4+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 devicemapper:
    93  ```bash
    94  export DOCKER_BUILDTAGS='exclude_graphdriver_devicemapper'
    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_devicemapper exclude_graphdriver_btrfs'
   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  * iptables version 1.4 or later
   110  * procps (or similar provider of a "ps" executable)
   111  * e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs)
   112  * xfsprogs (in use: mkfs.xfs)
   113  * XZ Utils version 4.9 or later
   114  * pigz (optional)
   115  
   116  Additionally, the Docker client needs the following software to be installed and
   117  available at runtime:
   118  
   119  * Git version 1.7 or later
   120  
   121  ### Kernel Requirements
   122  
   123  The Docker daemon has very specific kernel requirements. Most pre-packaged
   124  kernels already include the necessary options enabled. If you are building your
   125  own kernel, you should check out `contrib/check-config.sh`.
   126  
   127  Note that in client mode, there are no specific kernel requirements, and that
   128  the client will even run on alternative platforms such as Mac OS X / Darwin.
   129  
   130  ### Optional Dependencies
   131  
   132  Some of Docker's features are activated by using optional command-line flags or
   133  by having support for them in the kernel or userspace. A few examples include:
   134  
   135  * 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)
   136  * ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module)
   137  * Libseccomp to allow running seccomp profiles with containers
   138  
   139  ## Daemon Init Script
   140  
   141  Docker expects to run as a daemon at machine startup. Your package will need to
   142  include a script for your distro's process supervisor of choice. Be sure to
   143  check out the "contrib/init" folder in case a suitable init script already
   144  exists.
   145  
   146  In general, Docker should be run as root, similar to the following:
   147  
   148  ```bash
   149  dockerd
   150  ```
   151  
   152  Generally, it is encouraged that additional configuration be placed in
   153  `/etc/docker/daemon.json`.