toolbox/README.md

![README](data/gfx/README.gif)

[![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox)
[![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic)

[![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/)
[![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/)

[Toolbox](https://containertoolbx.org/) is a tool for Linux operating systems,
which allows the use of containerized command line environments. It is built
on top of [Podman](https://podman.io/) and other standard container
technologies from [OCI](https://opencontainers.org/).

This is particularly useful on
[OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like
[Fedora CoreOS](https://coreos.fedoraproject.org/) and
[Silverblue](https://silverblue.fedoraproject.org/). The intention of these
systems is to discourage installation of software on the host, and instead
install software as (or in) containers — they mostly don't even have package
managers like DNF or YUM. This makes it difficult to set up a development
environment or install tools for debugging in the usual way.

Toolbox solves this problem by providing a fully mutable container within
which one can install their favourite development and debugging tools, editors
and SDKs. For example, it's possible to do `yum install ansible` without
affecting the base operating system.

However, this tool doesn't *require* using an OSTree based system. It works
equally well on Fedora Workstation and Server, and that's a useful way to
incrementally adopt containerization.

The toolbox environment is based on an [OCI](https://www.opencontainers.org/)
image. On Fedora this is the `fedora-toolbox` image. This image is used to
create a toolbox container that seamlessly integrates with the rest of the
operating system by providing access to the user's home directory, the Wayland
and X11 sockets, networking (including Avahi), removable devices (like USB
sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev
database, etc..


## Installation & Use

See our guides on
[installing & getting started](https://containertoolbx.org/install/) with
Toolbox and [Linux distro support](https://containertoolbx.org/distros/).
README.md, data: Replace outdated logos with pixels https://github.com/containers/toolbox/issues/920 2021-11-12 16:44:13 +00:00			`![README](data/gfx/README.gif)`
README.md: Add description 2018-09-13 12:17:34 +00:00
README.md: Add badges for CI status and downstream packages https://github.com/containers/toolbox/pull/589 2020-10-22 15:27:04 +00:00			`[![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox)`
Make use of dynamic CI status badge 2021-02-10 13:35:05 +00:00			`[![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic)`
README.md: Add badges for CI status and downstream packages https://github.com/containers/toolbox/pull/589 2020-10-22 15:27:04 +00:00
			`[![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/)`
			`[![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/)`

README.md: Link to the website instead of the code repository Now that there's a website at https://containertoolbx.org/ it makes more sense to link to it instead of linking back to the same location where the README.md resides. 2021-12-08 16:19:47 +00:00			`[Toolbox](https://containertoolbx.org/) is a tool for Linux operating systems,`
			`which allows the use of containerized command line environments. It is built`
			`on top of [Podman](https://podman.io/) and other standard container`
README.md: Improve the introductory paragraph Using the word 'unprivileged' confuses readers because it means different things to different people. eg., it can mean 'rootless' or 'sandboxed', which are quite different things. It becomes even more confusing given the ongoing work to make 'sudo toolbox ...' work. It's nice to mention that Toolbox is targetted at Linux operating systems and that it relies on standard container technologies from OCI. https://github.com/containers/toolbox/pull/597 2020-10-27 15:33:24 +00:00			`technologies from [OCI](https://opencontainers.org/).`
README.md: Rework in various ways - OSTree systems aren't fully immutable, you can install things we just discourage it - fedora-toolbox can (and should!) be used on non-OSTree based systems as well https://github.com/debarshiray/fedora-toolbox/pull/43 2019-01-26 09:57:26 +00:00
			`This is particularly useful on`
README.md: Tweak Toolbox is being used with Endless OS, which is an OSTree based operating system built out of Debian packages, not RPMs; and in the Fedora universe, CoreOS is being increasingly treated as a primary use-case for Toolbox alongside Silverblue. https://github.com/containers/toolbox/pull/299 2019-10-14 10:49:29 +00:00			`[OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like`
docs: fix reference to Fedora CoreOS CoreOS hasn't existed since late 2016 and refers to the now-defunct Container Linux. Fedora CoreOS is an entirely separate project. 2020-10-15 14:48:41 +00:00			`[Fedora CoreOS](https://coreos.fedoraproject.org/) and`
README.md: Make it easier to read https://github.com/containers/toolbox/pull/685 2021-01-25 20:42:39 +00:00			`[Silverblue](https://silverblue.fedoraproject.org/). The intention of these`
README.md: Rework in various ways - OSTree systems aren't fully immutable, you can install things we just discourage it - fedora-toolbox can (and should!) be used on non-OSTree based systems as well https://github.com/debarshiray/fedora-toolbox/pull/43 2019-01-26 09:57:26 +00:00			`systems is to discourage installation of software on the host, and instead`
README.md: Make it easier to read https://github.com/containers/toolbox/pull/685 2021-01-25 20:42:39 +00:00			`install software as (or in) containers — they mostly don't even have package`
			`managers like DNF or YUM. This makes it difficult to set up a development`
			`environment or install tools for debugging in the usual way.`

			`Toolbox solves this problem by providing a fully mutable container within`
			`which one can install their favourite development and debugging tools, editors`
			and SDKs. For example, it's possible to do `yum install ansible` without
			`affecting the base operating system.`
README.md: Rework in various ways - OSTree systems aren't fully immutable, you can install things we just discourage it - fedora-toolbox can (and should!) be used on non-OSTree based systems as well https://github.com/debarshiray/fedora-toolbox/pull/43 2019-01-26 09:57:26 +00:00
README.md: Make it easier to read https://github.com/containers/toolbox/pull/685 2021-01-25 20:42:39 +00:00			`However, this tool doesn't require using an OSTree based system. It works`
			`equally well on Fedora Workstation and Server, and that's a useful way to`
			`incrementally adopt containerization.`
README.md: Add description 2018-09-13 12:17:34 +00:00
README.md: Add a hyperlink for OCI 2019-02-19 14:16:28 +00:00			`The toolbox environment is based on an [OCI](https://www.opencontainers.org/)`
Drop the Buildah dependency and the user-specific customized image This works by configuring the toolbox container after it has been created, instead of before. The toolbox script itself is mentioned as the entry point of the container, which does 'exec sleep +Inf' once the initialization is done. A new command 'init-container' was added to perform the initialization. It is primarily meant to be used as the entry point for all toolbox containers, and must be run inside the container that's to be initialized. It is not expected to be directly invoked by humans, and cannot be used on the host. As a result, the default name for the toolbox containers is now fedora-toolbox-<version-id>, not fedora-toolbox-<user>-<version-id>. For backwards compatibility, 'toolbox enter' and 'toolbox run' will continue to work with containers using the old naming scheme. https://github.com/debarshiray/toolbox/pull/160 2019-05-10 18:38:46 +00:00			image. On Fedora this is the `fedora-toolbox` image. This image is used to
			`create a toolbox container that seamlessly integrates with the rest of the`
README.md: Make it easier to read https://github.com/containers/toolbox/pull/685 2021-01-25 20:42:39 +00:00			`operating system by providing access to the user's home directory, the Wayland`
README.md, doc/toolbox: Synchronize with doc/toolbox-create https://github.com/containers/toolbox/pull/814 2021-06-26 09:07:24 +00:00			`and X11 sockets, networking (including Avahi), removable devices (like USB`
			`sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev`
			`database, etc..`

Initial revision 2018-08-31 16:02:49 +00:00
README.md: Shorten it by linking to the website wherever possible https://github.com/containers/toolbox/pull/949 2021-12-08 14:54:07 +00:00			`## Installation & Use`
README.md: Add a section on how to install Toolbox https://github.com/containers/toolbox/pull/683 2021-01-25 19:19:48 +00:00
README.md: Shorten it by linking to the website wherever possible https://github.com/containers/toolbox/pull/949 2021-12-08 14:54:07 +00:00			`See our guides on`
			`[installing & getting started](https://containertoolbx.org/install/) with`
			`Toolbox and [Linux distro support](https://containertoolbx.org/distros/).`
Generate & install completion scripts in build system The previous commit added a means to generating the completion scripts and this one plugs that into the build system. A new build option 'install_completions' has been introduced. Set to 'True' by default. Completions for bash and fish use pkg-config for getting the preferred install locations for the completions. If the packages are not available, fallbacks are in-place. The 'completion' subdir has been kept to work around the ideology of Meson that does not allow creating/outputing files in subdirectories nor using the output of custom_target() in install_data(). https://github.com/containers/toolbox/pull/840 2021-11-21 14:16:07 +00:00