pax_global_header00006660000000000000000000000064141502724400014511gustar00rootroot0000000000000052 comment=216317d9e145b250f231802cb3d770cf7a46b8c8 DUE-3.0.0/000077500000000000000000000000001415027244000121265ustar00rootroot00000000000000DUE-3.0.0/.gitattributes000066400000000000000000000002421415027244000150170ustar00rootroot00000000000000# If building with quilt, don't need .gitignore export-ignore # debian/rules replaces makefile, so skip it # when generating the tarball. Makefile export-ignore DUE-3.0.0/ChangeLog000066400000000000000000000167701415027244000137130ustar00rootroot00000000000000due (3.0.0-1) unstable; urgency=medium * Version bump to 3.0.0 * Support Podman as well as Docker. * Replace qemu, qemu-system Recommends with just qemu-user-static. Closes: bug#992947 * templates: Add pre and post install local dirs to build local packages into containers * templates: debian-package and onie support for Debian 11 * Makefile: Clean up and provide better help by default * debian-package: due-manage-local-repo: support multiple named local repositories * libdue: support sub-type template directory file hierarchy for templates * Fix invocation bug when running ARM64 containers on aarch64 hosts * Fix save/load import/export mismatch when writing and reading image files. -- Alex Doyle Tue, 31 Aug 2021 11:11:11 -0700 due (2.3.0-1) unstable; urgency=medium * Version bump to 2.3.0 * Red Hat image support in libdue and container scripts. * ChangeLog: Lintian cleanup. -- Alex Doyle Sat, 02 Jan 2021 06:06:06 -0700 due (2.2.0-1) unstable; urgency=medium * Version bump to 2.2.0 * libdue: Initial support to run under Red Hat Linux * Makefile: debian package build target, help * README.md: installation update * ChangeLog: Lintian cleanup. -- Alex Doyle Fri, 25 Dec 2020 07:07:07 -0700 due (2.1.0-1) unstable; urgency=medium * debian-package: duebuild now builds binaries by default, not source as well. * debian-package: fixed incorrect examples in help-examples. * debian-package: --use-local-repo now usues due-manage-local-repo.sh. * debian-package: added due-manage-local-repo.sh to let the user add/remove local pacakges. * debian-package: README.md - updated with due-manage-local-repo.sh documentation. * debian-package: duebuild - better error handling on dependency install fails. * common-templates: c-add-docker-user script will add user to docker group, if it exists * onie: Initial support for a Debian 10 build environment -- Alex Doyle Fri, 27 Nov 2020 17:00:00 -0700 due (2.0.0-1) unstable; urgency=medium * Initial upload. Closes: #931617 * debian-package: Set ulimit -n 10000 for slow Apt on Jessie images * debian-package: Install python version based on image Debian release * debian-package: Clean up files generated when resolving build dependencies * debian-package: Keep current package configuration on packag upgrades * debian-package: Absolute path option for local package repository * debian-package: Don't error out if no dependencies need to be installed. * ONIE: Debian 10 build environment support * libdue for emulation, qemu--static comes from source image's arch * due: do not filter images after --run-image has been invoked. * due: add --delete option * due: add --manage --browse Docker registry option * docs: Markdown cleanup. Updated some stale docs. * docs: Added Branching.md to explaing the branch/release structure. * Makefile: write release version in libdue to documentation. * git branches: refactored for Debian naming conventions. * everything: Ran spell check. -- Alex Doyle Fri, 21 Aug 2020 21:53:56 -0700 due (1.6.3-1) unstable; urgency=medium * Add --filter to --create --help. * Add *.buildinfo and *.changes to .gitignore. * Close #8 Use ncores to maximize build jobs. * Clean exit if bad menu value chosen * Mention --run-image option on image menu (addresses issue #10 ) * Close #12 - add wget as part of default install * Container/image export/import rework. -- Alex Doyle Sat, 01 Aug 2020 16:53:56 -0700 due (1.6.2-1) UNRELEASED; urgency=medium * Change --snapshot to --export. Works with --import now * Sanity check mounting two --volumes to the same container dir * duebuild takes --build as a synonym for --cbuild -- Alex Doyle Tue, 28 Jul 2020 21:33:40 -0700 due (1.6.1-1) UNRELEASED; urgency=medium * --login now executes ~/.bashrc, etc * Fix typo in stop container script. * Shellcheck corrections for container-create-user.sh -- Alex Doyle Thu, 09 Jul 2020 17:03:15 -0700 due (1.6.0-1) UNRELEASED; urgency=medium * Added debian-upstream branch for promotion to Debian. * Packaging/Licensing cleanup prompted by Debian QA tools. -- Alex Doyle Sun, 28 Jun 2020 15:16:59 -0700 due (1.5.0-1) UNRELEASED; urgency=medium * Command line help is no longer order specific * Debian package build: duebuild takes --deb-build-opt * Debian package build: duebuild takes --build-command * Debian package build: --jobs now applies with default build -- Alex Doyle Sun, 14 Jun 2020 09:35:04 -0700 due (1.4.0-1) UNRELEASED; urgency=medium * Copyright updates to 2020 * Debian package build: add local package repository feature. * Debian package build: improved package dependency install error handling. * Debian package build: container apt upgrades before build. * Debian package build: update documentation with package build examples. -- Alex Doyle Sat, 06 Jun 2020 10:21:05 -0700 due (1.3.1-1) UNRELEASED; urgency=medium * Update version number * Invoke help after --build if 'help' is typed * Stop containers script now has containers in the name, not images -- Alex Doyle Thu, 14 May 2020 17:46:51 -0700 due (1.3.0-1) UNRELEASED; urgency=medium * Non interactive commands now return a return code. * debian-package duebuild has better .dsc build support. * Label support to auto-mount host directories with DUEMountHostDirectories. -- Alex Doyle Tue, 12 May 2020 17:46:51 -0700 due (1.2.1-1) UNRELEASED; urgency=medium * Added first time setup checks and hints. -- Alex Doyle Mon, 13 Apr 2020 18:21:55 -0700 due (1.2.0-1) UNRELEASED; urgency=medium * Added --dockerarg to pass arguments directly to docker * Added docker run argument setting based on container type * Fixed bug where container --tag option wasn't passed. -- Alex Doyle Tue, 17 Mar 2020 01:02:00 -0800 due (1.1.0-1) UNRELEASED; urgency=medium * Added --stop option for running containers. * Added --create --clean option to delete due-buid-merge directory. * Added --container-name option to set the name of a container. * Fixed arm32v5 (armel) container creation with qemu on amd64 * Fixed bug where --command was run as --interactive, when it is not. * Fixed bug where image tags were not considered in filtering. * Script incremental cleanup with ShellCheck -- Alex Doyle Sat, 29 Feb 2020 12:00:01 -0800 due (1.0.1-1) UNRELEASED; urgency=medium * ONIE template fixes for Debian 8, duebuild script, better docs. * Added --run --debug option to debug partially created images. * Added more printouts of shell/Docker commands DUE runs. * Added date printouts to --delete-matched, clarified script name. * Fixed --login skipping the first entry. * Fixed double setting of prompt/path in due-bashrc.template. * Fixed --cbuild parsing passed arguments rather than passing them. * Documentation has more examples and formatting consistency. * Documented existing --build option that reduces build invocation typing. * Documentation rebuild is now separate from package build. -- Alex Doyle Sat, 01 Feb 2020 08:08:08 -0700 due (1.0.0-1) UNRELEASED; urgency=medium * Initial Debian packaging -- Alex Doyle Sun, 29 Dec 2019 14:52:02 -0700 DUE-3.0.0/LICENSE.txt000066400000000000000000000020571415027244000137550ustar00rootroot00000000000000Copyright (c) 2019-2020 Cumulus Networks, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. DUE-3.0.0/README.md000066400000000000000000000201241415027244000134040ustar00rootroot00000000000000# Dedicated User Environment (DUE) DUE is a wrapper for Docker to create easy to use build environments. ## The TL:DR Start with a Docker image for your desired Debian based operating system **+** DUE configuration utilities **+** configuration for your build target **=** DUE image. The due launcher application will run this image with defaults specified by the image itself, so that building, regardless of the target's architecture or operating system, can be as easy as: ### `due --build` See **./docs/GettingStarted.md** to get started creating and running an example image. Or run `./due --help` to jump right in with the comprehensive command line help and examples. ## The elevator pitch Need to build for Debian 8 armel, but only have an x86 host with Ubuntu 18.04? DUE supports building for **different architectures** and **OS versions**. Tired of users missing a step in configuring the build dependencies for your software? Supply a "template" to configure a Docker image and now everybody is using DUE to **build in identical environments**. Painfully aware you're building in a container because the configuration you'd get from your home directory isn't present, and you have to copy files around? DUE lets you **be yourself in a container**. ## Talks and tutorial videos [Building ONIE](https://www.youtube.com/watch?v=-5onRbZA0QQ) [DebConf 20 talk on building everything with DUE](https://meetings-archive.debian.net/pub/debian-meetings/2020/DebConf20/7-due-a-container-manager-for-building-things-that-arent-debianized-and-things-that-are.webm) [Package build demo from DebConf 20](https://youtu.be/8h60O8O0RcY ) ## The L:DR If you're building software, odds are it requires some level of build environment configuration. Docker containers can be used to replicate that environment, and DUE can be used to make that experience not suck. A listing of the problems DUE solves requires a bit of context to explain how the design requirements were determined, so bear with me while I get in to a bit of: # History **Dedicated User Environment** came out of build environment design work I'd done at Cumulus Networks, and they were gracious enough to allow me to open source it. Cumulus Linux is a Debian based operating system for white box network switches, and the Debian build infrastructure was great...until we had to start building things that weren't already part of Debian, and for licensing reasons, could never be. The scope of things to build expanded for me when I also took on the position of Open Network Install Environment project lead, working with the Open Compute Foundation, and needed to support pull requests, debug and image build testing for what is essentially a tiny operating system. I was already using Docker for Debian package builds, and a Dockerfile build environment had already been created for ONIE, which left me wondering why there wasn't a set "template" that could be used to set up dedicated build environments? Especially for distributed open source projects where developers can't be sharing the same hardware, but could use a common development environment for debug. Incidentally, this history explains why most of the starter image templates have a networking focus... # Design ## Design requirements (Or, what am I trying to solve here?) 1. **Easy build environment setup** by using a "template" for build environments. Whoever wrote the software I'm trying to build has already solved the problem of setting up things to build - why have developers solve the problem again? 2. Easy setup leads to **identical build environments** for debugging build issues. There is no more comparing versions of packages installed between systems because everybody is using the same environment. 3. **Preserve build environments.** I hate it when a software update breaks my ability to build something. Changes are almost always well intentioned, but mid-development is frequently not the time to tackle compatibility issues. For example, older platform builds on ONIE haven't been updated for modern kernels, and may never be, but providing an age-appropriate build container will allow for rebuilding them with bug fixes, should anyone be inclined. 4. Create a **build environment that feels 'natural'**. I don't want to have to be 'build user' or 'root' in a container that has none of my configuration, where I have to copy files around to get them out of the container. I want to feel like I'm still on my host system - with a contextual indicator being the only thing to remind me that I'm not. 5. I want **builds to "just work"** without a 'but'. If I'm currently building for Debian 10 and need to build for Ubuntu 16, it's _almost_ the same thing, 'but' package versions are different. Well, give me an environment with the different versions and I'll build there. 6. It has to be **easy to use**, because I'll be encouraging people with priorities other than designing build environments to use it, and, apart from being friendly, the less the end user has to do, the less support I'll have to do. 7. It has to be **easy to modify**, since developer requirements will vary. By writing it with Bash scripts the code resembles the commands the developers would want to run anyway. 8. It has to work on **shared user systems**. Many users should be able to run containers off the same image without colliding. 9. It should **work with build automation**. I want developers using the same environment my automated build code will use so that bugs caused by environmental discrepancies can be avoided. This is a variant of #2, but I think it's significant enough to warrant its own mention. 10. The framework for this should be **commonly available** so that developers can distribute their own templates and know end users can easily obtain the framework to turn those templates into build environments. # Getting started See **docs/GettingStarted.md** for instructions to build and run containers with DUE. # Further reading See **docs/Troubleshooting.md** and **docs/FAQ.md** # Build environment support. Currently DUE supports the following templates which demonstrate different image build configurations. See their README.md files under the templates/ directory, or run `./due --create --help-examples` for a quick summary. ## example This is a bare minimum install of DUE which can work offline once the originating container has been downloaded to the host system. It is a jumping off point for creating your own templates, or a useful test configuration for debugging common image creation issues. ## debian-package As the name implies, this template contains configuration for building Debian packages. The user specifies the Debian based release (Debian 9, Ubuntu 18.04, etc ), and occasionally architecture ( arm32v5/debian:buster ), to create a directory with a Dockerfile and some additional files. One of those additional files is a default build script, `duebuild`, which will handle resolving build dependencies, allowing a build to be invoked by just running the container without logging in to it. ## ONIE The **O**pen **N**etwork **I**nstall **E**nvironment is an example of configuring a build environment for a particular target. There are a number of build dependencies that have to be present, and at the moment, the ONIE code prefers Debian 9 (Stretch) and does not build with the tools provided by Debian 10 (Buster). Being able to create a Debian Stretch container with all the dependencies already available saves developers from sorting out if they have the right packages/versions, as well as also providing a standard environment where build issues can be debugged. ## FRR The **F**ree **R**ange **R**outing project provides commercial grade network routing. In addition to having all the packages required to build, this template uses an APT repository key and additional sources.list entry to pull build dependencies from the FRR package repository. It also uses a relative path link to copy the `duebuild` script from the `debian-package` template, should you be building FRR for a Debian distribution. ## Additional Base Images ...can be found at [https://hub.docker.com](https://hub.docker.com/) DUE-3.0.0/docs/000077500000000000000000000000001415027244000130565ustar00rootroot00000000000000DUE-3.0.0/docs/Branching.md000066400000000000000000000013001415027244000152650ustar00rootroot00000000000000# A brief explanation of branches, through change propagation. # master This is the upstream - changes are introduced here, and it has some ability to install DUE using the Makefile. It has no Debian specific packaging files. It also creates the 'upstream tarball' via `make orig.tar` # debian/master This is the top level for Debian packaging, and it does have Debian specific packaging files. It is not release specific, but can be used to build DUE as an installable Debian package. See GettingStarted.md for directions for generating a tarfile from the `master` branch, and building on `debian/master` This holds the debian/changelog, and gets updated via 'git merge master' DUE-3.0.0/docs/Building.md000066400000000000000000000064721415027244000151460ustar00rootroot00000000000000#Building There are a few ways to build using DUE. ##Build inside the container This is the expected use case if you are debugging a build. 1. Run due (if the code is not under your home directory, use the `--mount-dir` command to have the container mount it.) 2. Select a build container. 3. You are now logged in with your home directory mounted. 4. cd to the build directory. 5. Build as you normally would. ##Build outside the container. In this case, you'll invoke commands that run inside the container that do the build. This is the expected use case for code that you know builds, or automated build environments. **Tip** Use the `--run-image image-name:image-tag` argument to skip the image selection menu if you already know which image and tag you want to run. There are two options for running build commands in the container: ###The `--command` option, which allows for very specific invocations. 1. Mounts the current directory in the container. 2. Runs everything after `--command` in the container. 3. Exits. **Example:** List working directory in the container, and print its path: `due --run --command ls -l \; pwd` ###The --build option, which invokes `/usr/local/bin/duebuild` in the container. The `duebuild` script provides the opportunity to simplify build configuration by performing mandatory steps and allowing the user to just specify the optional ones. There are two expected arguments and behaviors from the `duebuild` script: **`--default`** - The script will try to do a build of the target with default settings. This can be as simple as 'make all' or 'dpkg-buildpackage -uc -us', or more involved. The end goal is to produce a binary that showcases the software without user the user making decisions, if possible. **`--cbuild `** This takes the rest of the command line as and passes it to whatever the default build mechanism is (make, dpkg-buildpackage, etc) As build requirements may vary, other options may be present in the duebuild script to prepare the build environment, or post process the output. For example, the user might want to change the version of a Debian package build to have a development string in it, or skip running tests if they are doing debug builds. The duebuild script is a convenient place to handle this complexity. See the existing duebuild scripts under the `templates` directory for examples of this. ##Practical build invocation examples ####Example: Build a Debian package #####Using --command due --run --command sudo mk-build-deps --install --remove ./debian/control --tool \"apt-get -y\" \; dpkg-buildpackage -uc -us #####Using --build --default due --run --build --default #####Using --build --cbuild due --run --build --cbuild -uc -us or due --run --build --cbuild -uc -b -j8 ####Example: Building a Debian package with different arguments #####Using --command due --run --command sudo mk-build-deps --install --remove ./debian/control --tool \"apt-get -y\" \; dpkg-buildpackage -uc -b -j8 ##### A failure using --build --default due --run --build --default -b -j8 Unrecognized option [ -b ]. Exiting ERROR - /usr/local/bin/duebuild [ --default -b -j8 ] failed with return code [ 1 ] ( Fails because default does not take other arguments, and would also still be supplying the '-us' anyway) DUE-3.0.0/docs/FAQ.md000066400000000000000000000223701415027244000140130ustar00rootroot00000000000000# Frequently Asked Questions Well, maybe not _frequently_ but things worth knowing. # Template creation ## Handling apt keys The DUE install scripts will automatically add any keys for an APT repository. The FRR template has an example of pulling a key and adding a custom repository to the sources.list in its container. ## Soft links to include other files. See `templates/frr/filesystem/usr/local/bin` for a relative path link to the debian-package's `duebuild` script for building debian packages. This can be useful if you are creating templates that have common code. ## The template README files supply default build instructions DUE scans all `template//README.md` files and looks for a line starting with: `Create` and containing `with:` ...when `due --create help` is run. If you are creating your own templates, I _highly_recommend_ putting this in there. During development it is very useful to have DUE kick out a complete command to build an image, and it creates a convenient starting point for new users. ## Local vs system installed execution Running `./due` has it access only files in the local directory. Running `due` will have it use the version installed on the host system (if it has been built and installed as a package). Depending on the context, local template directories may be available (./due) or not. This is useful if you're debugging on a shared user system and don't want to break everybody else. ## Where do I find more containers? Browse [https://hub.docker.com](https://hub.docker.com/) for images to use with --from ## Cross architecture support DUE will use QEMU to run containers of alternate architecture types. The templates/debian-package/README.md has an example of using an armv5 container to use as a build environment on an x86 system. Cross compilation may be faster, but this is very convenient. # Run time ## How do I know that I am in a container? There are a couple of options. First, If there is a `/.dockerenv` file - you're in a container. Second, if the container was created by DUE, the bash prompt (PS1) may hint this if the container's `/etc/due-bashrc` is sourced. If your home directory in the container already has a `~/.bashrc`, and it sets `PS1`, it will override the container. If desired, you can get around this by either: 1. Sourcing the `/etc/due-bashrc` on log in with `. /etc/due-bashrc` OR 2. Adding the following to the end of your `~/.bashrc` `if [ -e /etc/due-bashrc ];then` ` . /etc/due-bashrc` `fi` ## How do I specify a container from the command line and skip menu selection? Use `due --run--image ` Due uses `` as a `*name*` wildcard match, and if there is only one match, runs that image. Otherwise you'll get the menu. ## How do I know what arguments a container's duebuild script will take? Run `due --duebuild --help` and you can select a container to run `duebuild --help` in. ## Can I log in to a running container? Yes, use `due --login`, which will show all running DUE created containers, and should log you in as yourself. This is handy if you're used to working with multiple terminals. **NOTE** if you log into someone _else's_ running container, you will not have an account created, and would want to come in as root with `due --login --debug` ## Can I use DUE with containers it did not create? Yes, although functionality will be limited. `due --run --any` will show all Docker images. Note that for images not created by DUE, you may need to add the --username and --userid options to have an account to log in as. The root account usually works, so: `due --run --any --username root --userid 0` will probably get you a sane environment. ## Well, can I log in to containers that DUE did not create? Yes - `due --login --any` will show all running containers on the system, although you'll probably want to supply `--username root --userid 0` if the container wasn't created by DUE. Or use `due --login --debug`, which is a shortcut to log you in as root. ## On using `--privileged`. Do. Not. Recommend. The `--privileged` option gives a Docker container access to host device entries that would normally not be accessible. This can be useful for things like loopback mounting a file system to write to it, or having a container that runs other containers. **However** this also allows the container to modify the host system, and presents a **security/stability** risk, as users in the container may be able to affect the host system without realizing they are doing so. Within DUE it was a deliberate design choice to make things like this inconvenient so that the user has to be acutely aware of what they are doing. ## Using `--privileged` If you are indeed in a situation where this is necessary, `--privileged` can be passed to the command line invocation of Docker by using `due --run --dockerarg "--privileged"`. The `--dockerarg` option passes the following parameter through. It can be used multiple times for multiple arguments. If you need to have a container that has Docker installed in it to run other containers, and example invocation would be: `due --run --dockerarg "--privileged" --mount-dir "/dev:/dev" --mount-dir "/var/run/docker.sock:/var/run/docker.sock"` Note that this does mount two directories from the host system that can be modified by the container. **Use with caution.** # Debugging See `docs/Troubleshooting.md` # Design ## Why Bash? A couple of reasons: 1. I wanted the user to be able to easily modify existing code, and Bash seemed to be the lowest common denominator for programming experience. If one can use the command line, they've got half of Bash programming figured out already. 2. Bash is pretty much installed everywhere, and is a bit more flexible than sh/dash. 3. Bash scripts aren't architecture dependent, so DUE should run on any Debian system that supports Docker. ## Why just Debian, and not another Linux? If you read the History section, you'll know I've mainly been working with Debian and some Ubuntu, so development here overlapped with tackling problems that needed immediate solutions, so that's where all the testing and development has been on Debian. DUE could easily be smart enough to work with other Linux distributions, given some debug time. I'd see the main obstacle being to make the installer scripts aware of alternatives to APT for package management. Plus being Debian compatible covers running Ubuntu and a few other distributions as well, so it seems like really good coverage for the amount of effort. ## Why not just a docker file? Yeah, I asked myself this quite a bit, wondering if I was reinventing the wheel here, and came to a few conclusions: ### Easier development On the development side, I see a few advantages to generating the Dockerfile than directly editing it: 1. A **default directory structure** makes adding files to the image very obvious. Ex: files under `filesystem/usr/bin` go in `/usr/bin`. 2. **Pre** and **post install scripts** make it obvious where those scripts will execute in the install process. 3. **Softlink awareness** allows copying files between templates for assembly without requiring multiple copies of the file. Ex: the FRR template steals the `duebuild` script from the `debian-package` template using a softlink. 4. **Template processing** allows for minor detail change details between builds. Ex: setting the container identity with --from allows for a Debian 10 or Ubuntu 16.04 container to be built with exactly the same configuration. 5. **Debugging inside the container** is easier as DUE puts all the files used in container creation in the container, and they can be run individually inside to narrow down issues. 6. **Current user identity is preserved** by wrapping the Docker invocation (see below) 6. It allows for **embedding default information** into the container that can be parsed at Runtime (see **Easier Runtime**, below). ...and in the end, there is a Dockerfile created that does all this, but the user doesn't have to do as much work. ### Easier Runtime From a user perspective, Docker is very flexible, but this comes with the cost of complexity, and I'd found insofar as build environments went, I was doing the same few operations over and over, with minor variants. Things like remembering a container name, or setting myself up with the same account on my host system were just a hassle. By having DUE use a number of defaults and some simplified arguments at run time reduces the typing (and, in my case, resulting errors) to make things more friendly. Insofar as I can tell, any of the following can't easily be done with a Dockerfile. So things like: * Auto creation of a matching **user account** in the container. * Auto mounting the user's **home/work directory** so their configuration is available, and work can be saved when the container exits. * A **selection menu** for available containers, rather than having to remember the container name. * Labels embedded in the container that provide **defaults for running** the container. * Example: Debian package builds put the build products one level up from the current directory. DUE debian-package containers know to mount the host directory one level up in the container so that build products are seamlessly there when the container exits. Seems simple, but it's super irritating if it is not there. DUE-3.0.0/docs/GettingStarted.md000066400000000000000000000311061415027244000163310ustar00rootroot00000000000000# Getting Started **Formatting Conventions** If you are viewing this document as a text file, literal commands to type are start and end with back ticks like `this`. If you are using a Markdown viewer, you will see just the text: this but the font will be `different`. **The point** If you cut and paste from this file, do not copy the `s # Installing from a .deb If you have a .deb file of DUE that was installed with Apt, skip to **A Practical Example** below. If it is just a deb file, `sudo dpkg -i due_*deb` and resolve missing dependencies using Apt. # Installing from a Git checkout ## Install DUE's software dependencies To run DUE from the source directory, you will need to install the following packages: * docker.io (docker.ce works as well) * git * bsdutils * rsync * jq * curl * and maybe pandoc, if you plan on updating the man pages. Running `make install` from the `master` Git branch as root will attepmpt to install these packages for both Debian and Red Hat Linux. ## Add yourself to the Docker group Once Docker is installed, add yourself to the docker group with: `sudo /usr/sbin/usermod -a -G docker $(whoami)` You will probably have to log out and back in for your new membership to take effect. ## Run DUE locally with ./due If DUE is invoked with a ./, it will use the copy of `due` in the local directory (as expected) and use the template files that are under the local directory. This allows users to try it out without installing it on their systems. **Ex:** `./due` ## Installing DUE The preferred method of installing DUE is to build a .deb of it, using the debian/master branch and install the deb. Alternately, typing `make install` as `root` from the master Git branch will install DUE files in the system, which is currently the easiest way to install DUE in a Red Hat Linux system. # A Practical Example: create an image and build DUE as a Debian package DUE can be used to build itself as a Debian package. 1. Start with DUE's `master` Git branch. 2. Create a Debian package build container, using an example from `./due --create help`. If you are using Ubuntu, this might look like: `./due --create --from ubuntu:18.04 --description "Package Build for Ubuntu 18.04" --name pkg-u-18.04 --prompt PKGU1804 --tag pkg-ubuntu-18.04 --use-template debian-package` **TIP** `--filter` term can be used with `due --create --help` to limit the output to entries that match the term. 3. At this point you can type `make debian-package`and the makefile will: 3a. `make orig.tar` 3b. `git checkout debian/master` 3c. `due --build` 3d. Ask you to choose the image to build with, if you have more than one. 3e. Build the .deb, leaving it in the parent directory of DUE. 3f. ...and check out the `master` Git branch again. ...or you can run those steps individually. Once the build completes, there should be a due*.deb in the directory above where you just built. This can be installed with: `sudo dpkg -i due_*all.deb` **Note** if you have problems, read the `Troubleshooting.md` file which is in the current directory. ## Working in a container 1. Run `./due --run` If the image created in the previous step is the only one on the system, it will be run by default. Otherwise DUE will present a menu of images to choose from. Example: ` REPOSITORY TAG SIZE IMAGE ID` `-----------------------------------------------------------------------------------------` `1 due-example-debian-10 debian-10 114MB b45c5e64d1a3` `2 due-package-debian-10 debian-10 732MB 6053b1f43bcd` `3 due-onie-build debian-9 823MB 70cb5b66aa87` `4 due-pkg-u-18.04 pkg-ubuntu-18.04 598MB aae462a75630` 2. For reference, the Docker command used to start the container will scroll by, as well as the output from the DUE scripts that dynamically create your user account in the container, and any other additional configuration. 3. DUE will have mounted your home directory by default and created a user account for you in the container that matches the one you have on your host system. 4. You are now in a bash shell in the container. DUE defaults to setting the prompt to something that indicates the role of the container, as this may not be obvious. The Ubuntu package build example sets the prompt to `@PKGU1804` 5. If you want to use the default build script for the container, run `duebuild --help` to see what common build operations are available, or just start to build as you normally would. 6. Type `exit` to leave the container. ..And that's the basics of using DUE to create and run containers. **TIP** You can specify the image to use with `--run-image`: **Ex:** `due --run-image due-pkg-u-18.04:pkg-ubuntu-18.04 --build` <- build using `due-pkg-u-18.04` image with tag `pkg-ubuntu-18.04` The rest of this document will get in to using specific types of containers, and how you can create and debug your own. **TIP** Take a look at the README.md files under the `./templates` directory as well. # Run time: A few things to know about running DUE Take a look at the help by running `./due --run help` You'll find things like using `--image` (to limit the names of images shown, or run a particular container) or using `--login` to access a running container ### Local or system context? DUE can be built as a Debian package and be installed system-wide, or run from the local directory. There are a few behavior changes depending on which option you're using. #### Local context If you are using DUE from a source code check out, invoking it with `./due` limits its search paths for templates and the `libdue` library to the local directory. This is useful for local debugging, or trying it out without having to install it. #### System context If you build DUE into a package and install it, it will store the templates under `/usr/share/due`. The templates that are available system-wide can be listed with `due --create help` DUE also installs an `/etc/due/due.conf` that will hold any system wide settings. Users can override this by running: `./due --manage --copy-config` which will install: ~/.conf/due/due.conf` ###Tip: Knowing you are in a Docker container Docker containers have a `/.dockerenv` file, so any configuration scripts you have can be set to check for that. For example, on my laptop, DUE is configured to mount ~/ My .bashrc has the following logic: > `#Only set prompt if NOT in a container.` > `if [ ! -e /.dockerenv ];then` > ` export PS1='\u@\h$:\$ '` > `fi` This allows me to preserve the prompt hints that describe the container. # Files: **`due`** User interface script for DUE, and the script that a user executes at run time. Note: If due is run with ./due, it references all the local files, rather than ones that may be installed on the system. **`libdue`** Library functions that are the core code of DUE **`LICENSE.txt`** Documents DUE's MIT license **`README.md`** Starter documentation. **`Makefile`** This is present in the Master branch for basic installation and configuration. It is **not** present in the `debian/*` branches. ### Directories: **`debian`** Files for building DUE as a Debian package, rules, changelog, etc. Note: this is, for obvious reasons, only present in `debian/*` Git branches. **`docs`** DUE documentation **`etc`** Holds the DUE configuration file for the system's /etc directory. A copy of this is added to the user's home directory under: `~/.config/due/due.conf` Note that there are currently two configurable parameters for the system (`/etc/due/due.conf`) or a user (`~/.config/due/due.conf`) `DUE_ENV_DEFAULT_HOMEDIR` - change your home directory to another directory on the host. Handy if your home directory is on an NFS file system (See `Troubleshooting.md`) or you need to use a different disk partition to work in. `DUE_USER_CONTAINER_LIMIT` - set a limit on multi user systems for how many containers a user should be running. Sometimes it is tough to keep track... **`templates`** Holds all files used to create a dedicated type of image. The default is to use just the contents of `common-templates` if no other template type is specified. If a template type is specified (ONIE build, Debian package build, etc) then that will be merged with the contents of `common-templates` to produce the image. Files ending in `.template` are processed to contain values set by using arguments in conjunction with `--create`, so that things like the source container, prompt, or name can be set dynamically. **`due-build-merge`** This is the work/build area that holds image merges for build. For any image build, there will be two directories: 1. **`-template-merge`** Directory generated by `--create` when a `--use-template ` is specified. This directory contains the contents of `templates/common-templates`, with the contents of the specified source template (`debian-package`, `example`,etc) merged in. If the source template has a file with the same name as a common template, the common template file will be overwritten. At this stage, all the files are present, but strings in them that get replaced for final configuration have not been replaced yet. 2. **``** This is mostly a copy of `name-template-merge` but with all **REPLACE** terms in the files set to their final values. This would be things like the base docker image to use, the name of the image, or the prompt to use inside the container. The Dockerfile used to create the final image comes from this directory. By default, DUE runs the configuration and build as a single step. It's left broken out here as it is useful for debugging. Changes to configuration can be made in this directory and a new image generated by running `due --create --dir`. Of course, if you want those changes to be preserved for future creation, you'll need to update the `DUE/templates` directory with a new entry. **TIP** the image build area can be deleted for a clean build by running `due --create --clean` #Image build details: If you want a closer look at how the templates get turned in to the final Dockerfile We'll start with the files involved. ### Directory creation works as follows: Establish the starting template directory. If `--use-template` is not passed, `templates/common-templates` is used as the starting template directory If `--use-template ` is used, the files from `templates/` are merged with the files from common-templates into a `-template-merge` directory, where `` was supplied on the command line by the --name argument. **So:** `templates/ + common-templates = -template-merge directory` ####Create the build directory This copies any non-template files from the `-template-merge` directory into the `` directory under `due-build-merge/`. It then parses the *.template files that: 1. Originated in the `` template directory. 2. Were copied into `-template-merge` directory. 3. Parses them and replaces terms defined with `REPLACE_` with values specified by the user. (Things like the prompt, or originating container) 4. ...and copies them in the `` directory. **So:** `-template-merge directory + template REPLACE preprocessing -> build directory ` Finally, the Docker image is created using `--create --dir `, parsing the contents of ``. Due will run all of this in one step. Having both stages preserved can be handy for debugging, which is why it's not just one directory, with term replacements done in place. **So to summarize:** `templates/ + common-templates + template REPLACE preprocessing = build directory -> build image` ###Example: image creation. Create a build directory for ONIE, and build the image: `./due --create --from debian:stretch --description \"ONIE build container\" --name oniebuild --prompt ONIE --tag onie-build --use-template onie"` This creates: * the starting template directory onie-template-merge from `templates/onie` * the configuration directory oniebuild-build-merge * the build directory oniebuild * and builds the image **NOTES:** To build an image clean, you'll want to delete the `` related directories in `due-build-merge` You can build just the Docker image stage with `./due --build-dir ` ##Example: build the Docker image from an existing directory. `./due --create --build-dir oniebuild` DUE-3.0.0/docs/Troubleshooting.md000066400000000000000000000121451415027244000165720ustar00rootroot00000000000000# Troubleshooting ...for when things don't go as expected ## Symptom: Docker isn't installed ### Installing Docker without a DUE .deb If you've downloaded DUE as source, run: `sudo apt update ; sudo apt install docker.io git rsync binfmt-support qemu qemu-user-static` The last three packages there are optional, but necessary if you want to run alternate architectures. **TIP** if you are on the master Git branch of DUE, run `make install` to achieve the same effect. ### Installing Docker through the DUE .deb The lack of Docker will be obvious on the initial install of the DUE .deb, as you'll see the error: `due depends on docker.io | docker-ce; however: Package docker.io is not installed. Package docker.ce is not installed` To resolve this, try: `sudo apt update` `sudo apt install --fix-broken` If that fails (and might, depending on how old the version of your operating system is), try `sudo apt install docker.io` ...and if that fails, try downloading and installing docker.ce from [https://hub.docker.com](https://hub.docker.com/) ## Symptom: Docker containers don't run (or only run as root). You'll see `Got permission denied while trying to connect to the Docker daemon socket` You are probably not a member of the Docker group, so you'll need to: ### Add yourself to the Docker group: `sudo usermod -a -G docker $(whoami)` You may have to *log out* and back in again for the group change to take effect. Running `groups` should show `docker` along with your other groups. ## Symptom: Strange failures and permission errors in the container. Check that the host directory the container is using is a **LOCAL** file system. I've seen strange permission related errors when Docker is mounting a file system that is network mounted. If your home directory is **NFS** mounted on your build system, consider creating a work directory on the host system and using either `/etc/due/due.conf` or `~/.config/due/due.conf` ( generate this with `./due --manage --copy-config` ) to specify this local work directory as your "home" directory. You'll probably want to copy config files, etc to the new "home" directory. ## Symptom: Can't mount file systems or missing dev entries in container. Certain operations (like loopback mounting files) are restricted within the container because they would require root level access to the host file system. While Docker containers can run with the `--privileged` option which would allow this access, it also provides a false sense of security that actions taken within the container won't trash the host system. Bottom line: this _can_ be done, but it carries risks. ## Symptom: Running emulated containers fails. If QEMU is properly and fully installed, DUE should be able to run containers of other architectures seamlessly If you're reading this, then you've found a seam and should file a bug at: [https://github.com/CumulusNetworks/DUE/issues](https://github.com/CumulusNetworks/DUE/issues) ### Fails with: `standard\_init\_linux.go:211: exec user process caused "exec format error"` So far this has been the only time I've seen this die, and I tracked it down to my system's `binfmt-support` not being configured to handle ARM binaries. Ideally, qemu should register the architectures it can run with binfmt-support, so that when non-native code is encountered, it can be passed off to qemu. ####Other emulation related failures to check: #####Are there qemu-* entries under `/proc/sys/fs/binfmt_misc/` If `ls -l /proc/sys/fs/binfmt_misc` doesn't show them, then a few required packages may not be installed. Try: `sudo apt update ; sudo apt install qemu qemu-user-static binfmt-support` This should create the entries. If this fails, try reconfiguring qemu-user-static, with: `sudo dpkg-reconfigure qemu-user-static` which should have configured binfmt-support to have the entries. I had to do this on one system, for reasons that aren't completely clear to me. #####Is the binfmt service running? List bimfmt files `systemctl list-unit-files | grep binfmt` Restart binfmt-support `sudo systemctl restart binfmt-support.service` # Debugging a failed image creation If image creation does not complete, a partial image will have been created with the name ``. Running `due --manage --list-images` will list all containers on the system with the most recently created ones listed first. To get inside the failed container and debug it, run: `due --run --debug` and select the image. Then: `cd /due_configuration` Here you'll find all the configuration scripts that were run to create the container, so you can run them as needed to track down the failure. Your home directory will be mounted under `/home/root`, so any file changes you make can be persisted by copying them there. ## Cleaning up failed images Run `due --manage --delete-matched none` This gets the IDs of all images that have 'none' in their name and generates a script named `delete_these_docker_images.sh` that can be run to delete all those images. `--delete-matched` filters images with with `*term-supplied*` so you should check that the images listed in the script are, indeed, the ones you want to get rid of. DUE-3.0.0/docs/due.1000066400000000000000000000341461415027244000137250ustar00rootroot00000000000000.\" Automatically generated by Pandoc 2.5 .\" .TH "DUE" "1" "" "Version 3.0.0" "Dedicated User Environment" .hy .SH NAME .PP \f[B]due\f[R] \- Dedicated User Environment. A build environment for your build environments. .SH SYNOPSIS .PP \f[B]due\f[R] [\f[B]\-r|\[en]run\f[R] \f[I]args\f[R]] [\f[I]dedication\f[R]] .PD 0 .P .PD \f[B]due\f[R] [ \f[B]\[en]create\f[R] \f[I]args\f[R] ] [\f[I]dedication\f[R]] .PD 0 .P .PD \f[B]due\f[R] [ \f[B]\[en]delete\f[R] \f[I]term\f[R] ] [\f[I]dedication\f[R]] .PD 0 .P .PD \f[B]due\f[R] [\f[B]\-m\f[R]|\f[B]\[en]manage\f[R] \f[I]args\f[R]] [\f[I]dedication\f[R]] .PD 0 .P .PD \f[B]due\f[R] [\f[B]\-v\f[R]|\f[B]\[en]version\f[R]] .PD 0 .P .PD \f[B]due\f[R] [\f[B]\-h\f[R]|\f[B]\[en]help\f[R]] .SH DESCRIPTION .PP DUE is a set of wrapper scripts for both creating Docker container based build environments, and running them with intelligent defaults so that the user can feel like they are still on the host system. .PP Key features include: .PP 1 \- Creating an account in the container for the user at run time and mounting the user\[cq]s home/work directory so configuration files are available. .PP 2 \- List based browsing of images to run and active containers to log in to. .PP 3 \- Use of container `templates' to pre configure and build containers for a particular target or Debian based operating system, eliminating errors caused by missing dependencies, or misconfiguration. .PP 4 \- Commands can be run using the container without having to log into it, allowing for use in automated build environments. .PP 5 \- Compatibility with both Docker and Podman for running containers. .SS Functional Options .PP Each of these options has context specific help and sub commands .TP .B \-r, \[en]run Start new containers. .TP .B \[en]build, \[en]duebuild Execute container\[cq]s /usr/local/bin/duebuild script in current directory. See the \[en]run section for more. .TP .B \[en]create Make and configure new Docker images. .TP .B \[en]delete Delete existing Docker images that match the term. .TP .B \-m, \[en]manage Manipulate and query existing images. .TP .B \-h, \[en]help Usage information. .TP .B \-v, \[en]version Print DUE\[cq]s version number. .SS \[en]run options .PP These options are available after the \[en]run argument, and relate to starting and logging in to containers. .SS Starting an image .TP .B \-i, \[en]run\-image [filter] Allows the user to reduce the number of images shown to run by restricting them to entries that contain [filter]. If only one image matches the filter, it will be invoked without asking the user to choose it. .TP .B \-a, \[en]all Show all containers on the system. DUE can be used to log in to containers that it did not create, but the user may have to supply a default \[en]username and \[en]userid (usually \[en]username root and \[en]userid 0. See below ) .TP .B \[en]ignore\-type .IP .nf \f[C] When accessing the container, do not attempt to create a user \f[R] .fi .RS account for the user logging in, and assume the container was not created by DUE. This can be useful with image creation debug. .RE .TP .B \-c, \[en]command [cmd] Run [cmd] in the container using the \[en]login\-shell. This must be the last command parsed, as [cmd] is handed off to be run in the container. The primary use of this would be using the container to build without having to interactively log in to it. Note: when issuing multiple commands, remember to \[dq]\[dq] your arguments, and backslash () any semicolons (;) used to split up the commands. Otherwise the shell where the commands are invoked will take anything after the first ;, and treat it as a command to be run locally. This can obfuscate things if the command can work inside or out of the container. .PD 0 .P .PD Example: look at /proc and the password file in a container: ./due \[en]run \[en]command \[lq]ls \-lrt /proc\[rq] ; \[lq]cat /etc/passwd\[rq] .TP .B \[en]build | \[en]duebuild If there is a /usr/local/bin/duebuild script in the container, this option will run it with a default configuration, or take additional passed arguments if present. Those arguments will vary depending on the nature of the target being built by the container\[cq]s duebuild script. For more information, check the template/README.md for the image type, or use: due \[en]duebuild \[en]help to select a container and get its duebuild script\[cq]s help options directly. .TP .B \[en]duebuild Same behavior as \[en]build, but a bit clearer that it is working with the selected container\[cq]s duebuild script. One notable difference is that due \[en]duebuild \[en]help will select a container and execute duebuild \[en]help to see the options provided by that particular script. .TP .B \[en]dockerarg [arg] Put [arg] in the docker run invocation. For multiple arguments, use multiple invocations of \[en]dockerarg. This allows for things like running containers with \[en]privileged .TP .B \[en]debug Sets defaults of \[en]username root \[en]userid 0 and the \[en]any option to show images that were not created by DUE. Helpful for internal debug if image creation dies running internal configuration scripts. .TP .B \[en]container\-name name Change the name of the running container. This can provide clarity in a build automation environment, where containers may be automatically spun up. Note that if the new name does not have `due' in it, it will be filtered out from DUE\[cq]s \[en]login option unless \[en]all is also provided. This may or may not be desirable behavior. .TP .B \[en]home\-dir [host path] Absolute path to a directory to use as the home directory when the user logs in. Defaults to the user\[cq]s home directory unless overridden with this argument, or set otherwise in /etc/due/due.conf, or \[ti]/config/due/due.conf .TP .B \[en]mount\-dir [hp:cp] Mount absolute path on host system (hp) at absolute path in container. The colon (:) is necessary to separate the two. Multiple \[en]mount\-dir commands can be used in a single invocation. Example: mount host /tmp dir in container /var/build: \[en]mount\-dir /tmp/:var/build .SS Logging in to a running container .TP .B \-l, \[en]login Choose an existing container to log in to. .TP .B \[en]username [username] Name to use when logging in. .TP .B \[en]userid [id#] User ID to use when logging in. .TP .B \[en]groupname [groupname] Container user\[cq]s default group .TP .B \[en]groupid [id#] ID of container user\[cq]s group .TP .B \[en]login\-shell [path] Program to use as login .TP .B \[en]help\-runtime Invoke runtime help .TP .B \[en]help\-runtime\-examples Show examples of use .SS \[en]create options .PP These options are accessed after the \[en]create argument, and, predictably enough, relate to creating new images. .SS Creation Overview .PP Containers created by DUE will always have files from \&./templates/common\-templates in every image. The primary example of this is the \f[B]container\-create\-user.sh\f[R] script that sets up an account for the user in the container, and allows commands to be run in the container as if it was the user invoking them. .PP The order of creation is as follows, using the debian\-package template as an example, where the resulting image will be named `debian\-package\-10' .PP 1 \- The contents of common\-templates are copied to a debian\-package\-10\-template\-merge directory under \&./due\-build\-merge/ .PD 0 .P .PD 2 \- The contents of the debian\-package template directory copied in to the debian\-package\-10\-template\-merge directory and will overwrite any files with identical names. .PD 0 .P .PD 3 \- Any REPLACE_ fields in the template files are replaced with values supplied from the command line (such as the starting container image) and all files are copied to ./due\-build\-merge/debian\-package\-10 .PD 0 .P .PD 4 \- The ./due\-build\-merge/debian\-package\-10/Dockerfile.create file is used to create the image from this build directory. .SS Creation tips .PP Quick image changes can be made by editing the build directory ( \&./due\-build\-merge/debian\-package\-10 ) and re running ./due \[en]create \[en]build\-dir ./due\-build\-merge/debian\-package\-10 .PP The final image will hold a /due\-configuration directory, which holds everything that went into the image. This is very useful for install script debug inside the container. .PP A list of available default configurations is provided by running: due \[en]create \[en]help This will parse the README.md files under the \&./templates directory looking for specific strings. This output can be filtered by using wildcard syntax as follows: due \[en]create \[en]help \[en]filter .SS Advanced image creation .PP DUE 3.0.0 introduced hierarchical template parsing, where a template could be a combination of files provided by `sub\-type' directories, to reduce file duplication. With this, files with identical names and paths will overwrite the ones provided by higher directories. .PP Example: Given directory structure: due/templates/foo/sub\-type/bar/sub\-type/baz .PP Image creation using the `baz' template will be: 1 \- files from templates/common\-templates 2 \- plus files from foo overwriting any files with the same relative path from common\-templates 3 \- plus files from bar overwriting foo files the same way 4 \- plus files from baz overwriting bar files the same way. .PP While not normally needed, this may be useful for supporting a number of Images with minor but important differences. See templates/README.md for more information. .SS Creation example .PP 1 \- Configure an image build directory under due\-build\-merge named from \[en]name Mandatory: .TP .B \[en]from [name:tag] Pull name:tag from registry to use as starting point for the image. .TP .B \[en]use\-template [role] Use files from templates/[role] to generate the config directory. .TP .B \[en]description \[lq]desc\[rq] Quoted string to describe the container on login. .TP .B \[en]name name Name for resulting image and config directory. Ex: debian\-stretch\-build, ubuntu\-18.04\-build, etc .PP Optional: .TP .B \[en]prompt [prompt] Set in container prompt to [prompt] to provide user context .TP .B \[en]no\-image With \[en]create, allow directories to be created, but do not try to build the image. Effectively stops use of \[en]dir. Useful for debugging directory configuration issues. .TP .B \[en]filter [term] With \[en]create \[en]help, filter examples to contain [term]. .PP 2 \- Build a Docker image from the image build directory. .TP .B \[en]dir [dirname] Build using an existing configuration directory. .TP .B \[en]clean Delete the due\-build\-merge staging directories. .SS \[en]manage options .PP These options are accessed after the \[en]manage argument, and can make working with containers/images easier. .TP .B \-l, \[en]list\-images List images created by DUE. .TP .B \[en]stop Use the menu interface to stop a running container. Works with \[en]all to show containers not started by the user. If is supplied, it will match all the user\[cq]s containers to that pattern and produce a script that can be edited and run to delete the listed containers. NOTE: \[en]all \[en]stop can be used to do some serious damage. NOTE: since all DUE containers are started with \-rm, stopping a container deletes it and all the data in it from memory. .TP .B \[en]export\-container name Export a running container to disk as a Docker image named name. Note that to run the saved image it must be added back to the system with \[en]import. .TP .B \[en]export\-image name Save an existing Docker image as a file that can be copied elsewhere. If name is not supplied, the user can choose from a menu. .TP .B \[en]import\-image name Import a docker image stored on disk as tar file .TP .B \[en]copy\-config Create a personal DUE configuration file in \[ti]/.config/due/due.config .TP .B \[en]make\-dev\-dir [dir] Populate a local directory for DUE container development. .TP .B \[en]list\-templates List available templates. .TP .B \[en]delete\-matched [term] Delete containers that contain this term. USE WITH CAUTION! .TP .B \[en]docker\-clean Run `docker system prune ; docker image prune' to reclaim disk space. .TP .B \[en]help\-examples Examples of using management options. .SH FILES .TP .B \f[I]/etc/due/due.conf\f[R] Global configuration file .TP .B \f[I]\[ti]/.conf/due/due.conf\f[R] Per\-user default configuration file. Overrides the global one. \f[C]due \-\-manage \-\-copy\-config\f[R] will set that up for the user. .SH ENVIRONMENT .PP The configuration file sets up the following variables: .PP \f[C]DUE_ENV_DEFAULT_HOMEDIR\f[R] \- evaled to define the user\[cq]s home directory. This can be useful if there is a naming convention for work directories on shared systems, or your home directory is an NFS mount (which can create .PD 0 .P .PD strange behavior when mounted in Docker) or you need to use a bigger build directory. .PP \f[C]DUE_USER_CONTAINER_LIMIT\f[R] \- limit the number of containers a user is allowed to run. Handy on a shared system to remind people of what they have running. This can easily be circumvented, though. .SH BUGS .PP See GitHub Issues: [https://github.com/[CumulusNetworks]/[DUE]/issues] .SH AUTHOR .PP Alex Doyle .SH COPYRIGHT .PP SPDX\-License\-Identifier: MIT .PP Copyright (c) 2021 Nivia Corporation. .PD 0 .P .PD Copyright (c) 2019,2020 Cumulus Networks, Inc. .PP Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \[lq]Software\[rq]), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: .PP The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. .PP THE SOFTWARE IS PROVIDED \[lq]AS IS\[rq], WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .SH SEE ALSO .PP \f[B]due.conf(4)\f[R] DUE-3.0.0/docs/manpage-due-1.md000066400000000000000000000324021415027244000157220ustar00rootroot00000000000000% DUE(1) Version 3.0.0 | Dedicated User Environment # NAME **due** - Dedicated User Environment. A build environment for your build environments. # SYNOPSIS | **due** \[**-r|--run** _args_] \[_dedication_] | **due** \[ **--create** _args_ ] \[_dedication_] | **due** \[ **--delete** _term_ ] \[_dedication_] | **due** \[**-m**|**--manage** _args_] \[_dedication_] | **due** \[**-v**|**--version**] | **due** \[**-h**|**--help**] # DESCRIPTION DUE is a set of wrapper scripts for both creating Docker container based build environments, and running them with intelligent defaults so that the user can feel like they are still on the host system. Key features include: 1 - Creating an account in the container for the user at run time and mounting the user's home/work directory so configuration files are available. 2 - List based browsing of images to run and active containers to log in to. 3 - Use of container 'templates' to pre configure and build containers for a particular target or Debian based operating system, eliminating errors caused by missing dependencies, or misconfiguration. 4 - Commands can be run using the container without having to log into it, allowing for use in automated build environments. 5 - Compatibility with both Docker and Podman for running containers. Functional Options ------- Each of these options has context specific help and sub commands -r, --run : Start new containers. --build, --duebuild : Execute container's /usr/local/bin/duebuild script in current directory. See the --run section for more. --create : Make and configure new Docker images. --delete : Delete existing Docker images that match the term. -m, --manage : Manipulate and query existing images. -h, --help : Usage information. -v, --version : Print DUE's version number. --run options ------- These options are available after the --run argument, and relate to starting and logging in to containers. Starting an image ------- -i, --run-image [filter] : Allows the user to reduce the number of images shown to run by restricting them to entries that contain [filter]. If only one image matches the filter, it will be invoked without asking the user to choose it. -a, --all : Show all containers on the system. DUE can be used to log in to containers that it did not create, but the user may have to supply a default --username and --userid (usually --username root and --userid 0. See below ) --ignore-type : When accessing the container, do not attempt to create a user account for the user logging in, and assume the container was not created by DUE. This can be useful with image creation debug. -c, --command [cmd] : Run [cmd] in the container using the --login-shell. This must be the last command parsed, as [cmd] is handed off to be run in the container. The primary use of this would be using the container to build without having to interactively log in to it. Note: when issuing multiple commands, remember to "" your arguments, and backslash (\) any semicolons (;) used to split up the commands. Otherwise the shell where the commands are invoked will take anything after the first ;, and treat it as a command to be run locally. This can obfuscate things if the command can work inside or out of the container. Example: look at /proc and the password file in a container: ./due --run --command "ls -lrt /proc" \; "cat /etc/passwd" --build | --duebuild : If there is a /usr/local/bin/duebuild script in the container, this option will run it with a default configuration, or take additional passed arguments if present. Those arguments will vary depending on the nature of the target being built by the container's duebuild script. For more information, check the template/README.md for the image type, or use: due --duebuild --help to select a container and get its duebuild script's help options directly. --duebuild : Same behavior as --build, but a bit clearer that it is working with the selected container's duebuild script. One notable difference is that due --duebuild --help will select a container and execute duebuild --help to see the options provided by that particular script. --dockerarg [arg] : Put [arg] in the docker run invocation. For multiple arguments, use multiple invocations of --dockerarg. This allows for things like running containers with --privileged --debug : Sets defaults of --username root --userid 0 and the --any option to show images that were not created by DUE. Helpful for internal debug if image creation dies running internal configuration scripts. --container-name [name] : Change the name of the running container. This can provide clarity in a build automation environment, where containers may be automatically spun up. Note that if the new name does not have 'due' in it, it will be filtered out from DUE's --login option unless --all is also provided. This may or may not be desirable behavior. --home-dir [host path] : Absolute path to a directory to use as the home directory when the user logs in. Defaults to the user's home directory unless overridden with this argument, or set otherwise in /etc/due/due.conf, or ~/config/due/due.conf --mount-dir [hp:cp] : Mount absolute path on host system (hp) at absolute path in container. The colon (:) is necessary to separate the two. Multiple --mount-dir commands can be used in a single invocation. Example: mount host /tmp dir in container /var/build: --mount-dir /tmp/:var/build Logging in to a running container ------- -l, --login : Choose an existing container to log in to. --username [username] : Name to use when logging in. --userid [id#] : User ID to use when logging in. --groupname [groupname] : Container user's default group --groupid [id#] : ID of container user's group --login-shell [path] : Program to use as login --help-runtime : Invoke runtime help --help-runtime-examples : Show examples of use --create options ------- These options are accessed after the --create argument, and, predictably enough, relate to creating new images. Creation Overview ------- Containers created by DUE will always have files from ./templates/common-templates in every image. The primary example of this is the **container-create-user.sh** script that sets up an account for the user in the container, and allows commands to be run in the container as if it was the user invoking them. The order of creation is as follows, using the debian-package template as an example, where the resulting image will be named 'debian-package-10' 1 - The contents of common-templates are copied to a debian-package-10-template-merge directory under ./due-build-merge/ 2 - The contents of the debian-package template directory copied in to the debian-package-10-template-merge directory and will overwrite any files with identical names. 3 - Any REPLACE_ fields in the template files are replaced with values supplied from the command line (such as the starting container image) and all files are copied to ./due-build-merge/debian-package-10 4 - The ./due-build-merge/debian-package-10/Dockerfile.create file is used to create the image from this build directory. Creation tips ------- Quick image changes can be made by editing the build directory ( ./due-build-merge/debian-package-10 ) and re running ./due --create --build-dir ./due-build-merge/debian-package-10 The final image will hold a /due-configuration directory, which holds everything that went into the image. This is very useful for install script debug inside the container. A list of available default configurations is provided by running: due --create --help This will parse the README.md files under the ./templates directory looking for specific strings. This output can be filtered by using wildcard syntax as follows: due --create --help --filter Advanced image creation ------- DUE 3.0.0 introduced hierarchical template parsing, where a template could be a combination of files provided by 'sub-type' directories, to reduce file duplication. With this, files with identical names and paths will overwrite the ones provided by higher directories. Example: Given directory structure: due/templates/foo/sub-type/bar/sub-type/baz Image creation using the 'baz' template will be: 1 - files from templates/common-templates 2 - plus files from foo overwriting any files with the same relative path from common-templates 3 - plus files from bar overwriting foo files the same way 4 - plus files from baz overwriting bar files the same way. While not normally needed, this may be useful for supporting a number of Images with minor but important differences. See templates/README.md for more information. Creation example ------- 1 - Configure an image build directory under due-build-merge named from --name Mandatory: --from [name:tag] : Pull name:tag from registry to use as starting point for the image. --use-template [role] : Use files from templates/[role] to generate the config directory. --description "desc" : Quoted string to describe the container on login. --name [name] : Name for resulting image and config directory. Ex: debian-stretch-build, ubuntu-18.04-build, etc Optional: --prompt [prompt] : Set in container prompt to [prompt] to provide user context --no-image : With --create, allow directories to be created, but do not try to build the image. Effectively stops use of --dir. Useful for debugging directory configuration issues. --filter [term] : With --create --help, filter examples to contain [term]. 2 - Build a Docker image from the image build directory. --dir [dirname] : Build using an existing configuration directory. --clean : Delete the due-build-merge staging directories. --manage options ------- These options are accessed after the --manage argument, and can make working with containers/images easier. -l, --list-images : List images created by DUE. --stop : Use the menu interface to stop a running container. Works with --all to show containers not started by the user. If is supplied, it will match all the user's containers to that pattern and produce a script that can be edited and run to delete the listed containers. NOTE: --all --stop can be used to do some serious damage. NOTE: since all DUE containers are started with -rm, stopping a container deletes it and all the data in it from memory. --export-container [name] : Export a running container to disk as a Docker image named name. Note that to run the saved image it must be added back to the system with --import. --export-image [name] : Save an existing Docker image as a file that can be copied elsewhere. If name is not supplied, the user can choose from a menu. --import-image [name] : Import a docker image stored on disk as tar file --copy-config : Create a personal DUE configuration file in ~/.config/due/due.config --make-dev-dir [dir] : Populate a local directory for DUE container development. --list-templates : List available templates. --delete-matched [term] : Delete containers that contain this term. USE WITH CAUTION! --docker-clean : Run 'docker system prune ; docker image prune' to reclaim disk space. --help-examples : Examples of using management options. FILES ===== */etc/due/due.conf* : Global configuration file *~/.conf/due/due.conf* : Per-user default configuration file. Overrides the global one. `due --manage --copy-config` will set that up for the user. ENVIRONMENT =========== The configuration file sets up the following variables: `DUE_ENV_DEFAULT_HOMEDIR` - evaled to define the user's home directory. This can be useful if there is a naming convention for work directories on shared systems, or your home directory is an NFS mount (which can create strange behavior when mounted in Docker) or you need to use a bigger build directory. `DUE_USER_CONTAINER_LIMIT` - limit the number of containers a user is allowed to run. Handy on a shared system to remind people of what they have running. This can easily be circumvented, though. BUGS ==== See GitHub Issues: [https://github.com/[CumulusNetworks]/[DUE]/issues] AUTHOR ====== Alex Doyle COPYRIGHT ========= SPDX-License-Identifier: MIT Copyright (c) 2021 Nivia Corporation. Copyright (c) 2019,2020 Cumulus Networks, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. SEE ALSO ======== **due.conf(4)** DUE-3.0.0/due000077500000000000000000001347441415027244000126460ustar00rootroot00000000000000#!/bin/bash # SCRIPT_PURPOSE: Dedicated User Environment CLI # Copyright 2021 Nvidia Corporation. All rights reserved. # Copyright 2019,2020 Cumulus Networks, Inc. All rights reserved. # # SPDX-License-Identifier: MIT INSTALLED_DUE_DIR="/usr/share/due" LIBRARY_FILE="/usr/lib/libdue" if [ -e ./libdue ];then # Use local copy if it exists. We are running from a source # checkout and probably want the current file, rather than # the installed one TOP_LEVEL_DIR=$(pwd) LIBRARY_FILE="${TOP_LEVEL_DIR}/libdue" fi if [ ! -e "$LIBRARY_FILE" ];then echo "ERROR! Failed to find [ $LIBRARY_FILE ]. Exiting." exit 1 fi # Source the installed or checked out version of libdue . "$LIBRARY_FILE" # Verbosity level. 0 is terse. VERBOSITY_LEVEL=0 DUE_NAME=$( basename "$0" ) # DUE has two pathing modes # 1 - using system installed copy # 2 - using a checkout or build environment locally. # # If 2 - then all paths are local to the current directory, assuming # the user is doing development and wants the local to override the # currently installed version. # # TOP_LEVEL_DIR will be set appropriately. # Short description of the code function fxnHelpAbout() { # print how to get to this help if [ "$1" = "invocation" ];then echo "$DUE_NAME --help-about Overview of what DUE does." return fi echo "" echo " About DUE:" echo "" echo " DUE (Dedicated User Environment) is a collection of Bash functions to simplify" echo " the process of creating a Docker Image that can be used for software development" echo " for any Linux that has supplied an image." echo " If you are new to Docker:" echo " Image = effectively a configured file system in a file on disk." echo " Container = a running instance of an Image." echo "" } # Top level help function fxnHelp () { # print how to get to this help if [ "$1" = "invocation" ];then echo "$DUE_NAME --help Top level help." return fi echo "" echo " Usage: $DUE_NAME [ option ]" echo "" echo " due is a wrapper to use Docker containers as Debian build environments." echo "" echo " -c | --create Build an image using configuration from DIR" echo " --delete Generate a script to delete all images containing " echo " -r | --run Select image to run from a menu." echo " --build Shortcut to run the container's duebuild script." echo " --duebuild Same as --build but takes --help to print a container's duebuild help." echo " -m | --manage Manage existing images and containers." echo " -v | --verbose Print extra information when running." echo " --version Print version of DUE." echo "" echo " -h | --help Top level help (this message)." echo " Also provides context specific help when used" echo " with the arguments above." echo " --help-examples Specific examples of use when used with the arguments above." echo " --help-topics Summary of all help sections, with access instructions." echo " --help-about A description of what DUE can do." echo " --help-env-vars Bash environment variables DUE will use." echo " --help-all Print ALL THE HELP!" echo "" } # # A top level help examples to go with top level help. # function fxnHelpExamples() { echo "############################################################################" echo "#" echo "# DUE examples:" echo "#" echo "############################################################################" echo"" echo "Build from a source directory, using a container's duebuild script." echo " $0 --build" echo "" echo " Log into a running container:" echo " $0 --login" echo "" echo " Run a commands in a specific container:" echo " $0 --run-image due-pkg-sid:pkg-sid --command ls -l \; cat /etc/os-release " echo "" echo " Print a container's duebuild help:" echo " $0 --help --duebuild " echo "" echo "See topic specific help for topic specific examples." echo " Ex: $0 --help-examples --build" } # Help with managing existing images, containers, templates function fxnHelpManage() { if [ "$1" = "invocation" ];then echo "$DUE_NAME --manage --help Utility functions for container management." return fi echo "############################################################################" echo "#" echo "# Help for: --manage " echo "#" echo "############################################################################" echo " Utility functions to make development and use of DUE easier." echo "" echo " Usage: $DUE_NAME --manage [ option ]" echo "" echo " -l | --list-images List images created by DUE." echo " --export-container Save a running container as a Docker image named [name]" echo " --export-image Export a docker image as a file. [name] is optional." echo " --import-image Import Docker image file named [name]" echo "" echo " --browse Browse a docker registry. Ex: due --manage --browse localhost:5000" echo "" echo " --copy-config Create a personal DUE configuration file in ~/.config/due/due.config" echo " --make-dev-dir Populate a local directory for DUE container development." echo " --list-templates List available templates." echo " --docker-clean Run 'docker system prune ; docker image prune' to reclaim disk space." echo "" echo " --stop Stop a running container. Optional pattern " echo " --delete-matched [term] Delete containers that contain this term. USE WITH CAUTION!" echo "" echo " --help This help." echo " --help-examples Examples of using management options." echo "" } # Example usage of management commands function fxnHelpManageExamples() { if [ "$1" = "invocation" ];then echo "$DUE_NAME --manage --help-examples Management use cases." return fi echo "############################################################################" echo "#" echo "# Help: example commands for: --manage " echo "#" echo "############################################################################" echo "" echo " To delete containers that failed to create:" echo " $DUE_NAME --manage --delete-matched none " echo " Safety tip: don't put 'none' in your container names!" echo "" echo " Stop containers you left running:" echo " $DUE_NAME --manage --stop " echo "" echo " Stop all my package build containers with a script:" echo " $DUE_NAME --manage --stop pkg " echo "" echo " Save the current state of a container as an image on disk." echo " $DUE_NAME --manage --export-container myNewImage " echo "" echo " Export a Docker image to disk." echo " $DUE_NAME --manage --export-image imageFile " echo "" echo " Import a Docker image." echo " $DUE_NAME --manage --import-image imageFile " echo "" echo " Clean the image build area " echo " $DUE_NAME --manage --clean" echo '' } # Help with creating containers, images, directories # TAKES: # invocation - help just on running # or argument to filter examples with function fxnHelpCreate() { if [ "$1" = "invocation" ];then echo "$DUE_NAME --create --help Make new containers and configuration directories." return fi # Lots of examples can be generated - allow a filter term exampleFilter="$1" echo "############################################################################" echo "#" echo "# Help for: --create " echo "#" echo "############################################################################" echo " Create or delete Docker images used to build for particular targets" echo " or different Linux releases, provided you can find a container for it." echo "" echo " Usage: $DUE_NAME --create [ option ]" echo "" echo " Image management options:" echo "" echo " 1 - Configure an image build directory under due-build-merge named from --name" echo " Mandatory:" echo " --from Pull name:tag from registry to use as starting point for the image." echo " --use-template Use files from templates/ to generate the config directory." echo " --description \"desc\" Quoted string to describe the container on login." echo " --name Name for resulting image and config directory." echo " Ex: debian-stretch-build, ubuntu-18.04-build, etc" echo " Optional:" echo " --prompt Set in container prompt to to provide user context" echo " --no-image Allow build directory to be created. Do not build the image." echo "" echo " 2 - Build a Docker image from the image build directory." echo "" echo " --build-dir Build using an existing configuration directory." echo "" echo " --clean Remove due-build-merge directory." echo " --help This help." echo " --filter With --help, filter output to contain " echo " --create --help-examples Examples of using create." echo "" echo "" # show local image creation configurations fxnListContainersForCreation $exampleFilter echo "" } function fxnHelpCreateExamples() { if [ "$1" = "invocation" ];then echo "$DUE_NAME --create --help-examples Container and config use cases." return fi echo "############################################################################" echo "#" echo "# Help: example commands for: --create" echo "#" echo "############################################################################" # show local image creation configurations fxnListContainersForCreation $exampleFilter echo "" echo " Ex: clean container creation work area." echo " $0 --create --clean" echo "" echo " Ex: filter creation examples to only show those containing 'foo' " echo " $0 --create --help --filter foo" echo "" } # Image management options # # help with running the containers you've already created # function fxnHelpRun() { if [ "$1" = "invocation" ];then echo "$DUE_NAME --run --help Running the images you created." return fi echo "############################################################################" echo "#" echo "# Help for: --run " echo "#" echo "############################################################################" echo "" echo " Usage: $DUE_NAME --run [ option ]" echo " If no option is supplied, a menu of images to run will be provided." echo "" echo " Specify how to run an image or log into an existing container." echo "" echo " Run time options:" echo "" echo " Image selection:" echo " Select image to run from a menu." echo " --all Do not filter list of available containers." echo " --ignore-type Treat container as if it was not made by DUE." echo " --debug Debug partially built container. Defaults to setting:" echo " --any --username root --userid 0" echo " -i | --run-image Restrict shown images to those that match *filter*." echo " If only one image matches a line from due --list-images" echo " it will be run automatically." echo " Image commands:" echo " -c | --command will be executed by --login-shell in the container" echo " NOTE: this must be the last argument, as everything after" echo " --command will be interpreted as the command." echo " NOTE2: Quote \"\" your arguments if using multiple commands!" echo " NOTE3: \ any ; so everything after the ; goes to DUE" echo " --build Invoke container's /usr/local/bin/duebuild script" echo " (if present in container) in current directory." echo " --duebuild Same as --build, but appending --help will run" echo " duebuild --help in a container you select." echo " --container-name Change the name of the container to " echo "" echo " Pass commands to Docker " echo " --dockerarg will be applied directly to the Docker invocation." echo " use multiple times for multiple args." echo "" echo " Host directories to mount in the container:" echo " --home-dir Absolute path on host system to mount as container user home directory" echo " Default: $HOST_HOME_DIR" echo " Pass 'container' as path to use home dir that comes with the container." echo " --mount-dir Mount absolute path to host directory hp at location cp in container." echo " Ex: mount host /tmp in container /var/build: --mount-dir /tmp:/var/build " echo "" echo " Log in to an active container" echo " -l | --login Choose existing running container to log in to." echo " -a | --all Log into any container as root using sh" echo " Log in as a particular user:" echo " --username Name to use when logging in. Default: $USER_NAME" echo " --userid User ID to use when logging in. Default: $USER_ID" echo " --groupname Container user's default group Default: $USER_GROUP_NAME" echo " --groupid ID of container user's group Default: $USER_GROUP_ID" echo " --login-shell Program to use as login Default: $LOGIN_SHELL" echo "" echo "" #experimental # echo " --debug Pass a debug flag to the container." echo "" echo " Help:" echo " --help --run This message." echo " --run --help-examples Show examples of use." echo "" } # # Examples of run time use # function fxnHelpRunExamples() { if [ "$1" = "invocation" ];then echo "$DUE_NAME --run --help-examples Container run time use cases." return fi echo "############################################################################" echo "#" echo "# Help: example commands for: --run " echo "#" echo "############################################################################" echo "" echo " Log into a container as current user: " echo " ...with host home directory mounted as home directory in the container." echo " $DUE_NAME --run " echo "" echo " ...with /var/lib/build as home directory." echo " $DUE_NAME --run --home-dir /var/lib/build " echo "" echo " ...mount additional host system directory 'work-dir' in the container at /build" echo " $DUE_NAME --run --mount-dir /home/$(whoami)/work-dir/:/build" echo "" echo " Log into a container as user ufoo" echo " ...and use the container home dir " echo " $DUE_NAME --run --username ufoo --home-dir container" echo "" echo " Log into a container that is already running:" echo " $DUE_NAME --login ` ## /usr/local/bin/due-manage-local-repo.sh A script for managing a local package repository. See its command line help for details, and **`Building a package that depends on previously built packages`** below. # Use ## Build as yourself You can use `due --run` and select the DUE image, which will: 1. Mount your "home" directory ( this doesn't have to be your host's ~/ - see `docs/GettingStarted.md` ) 2. Create an account for you in the container, with your username and user ID. 3. Source a .bashrc, and allow access to any other . files. 4. ...and now you can navigate to your build directory, to build from the command line. ## Build without interaction There are a number of ways to use the container to build a Debian package without logging in to the container. See DUE/docs/Building.md for additional information. **Tip** Use the `--run-image image-name:image-tag` argument to skip the image selection menu if you already know which image and tag you want to run. Start by: cd -ing to the top level package directory ( such that running `ls ./debian/control` will succeed.) Then try one of the following: #### Using --command **Purpose:** run arbitrary commands in a container **Description:** Here the container executes everything after `--command` in a Bash shell. **Example:** `due --run --command sudo mk-build-deps --install --remove ./debian/control --tool \"apt-get -y\" \; dpkg-buildpackage -uc -us` **NOTES:** 1. The **\;** is necessary to separate the two commands to be run in the container. Without the **'\'**, the invoking shell will interpret everything after the **';'** as a command to be run _after_ invoking DUE. This can create confusion and complicate debugging as it will not be obvious the second command is failing outside of the container. #### Using --build **Purpose:** Use container's `duebuild` script to perform additional configuration. **Description:** Here, `--build` is a shortcut to invoke the `/usr/local/bin/duebuild --default` script in the container, and provide a bit of abstraction so as to not bother the user with the details of the build. **Tip:** get help for the container's `duebuild` script by running: `due --help --duebuild