mirror of
https://github.com/89luca89/distrobox.git
synced 2026-08-17 16:34:42 -05:00
docs: update and format docs
This commit is contained in:
89luca89
+1
-1
@@ -6,4 +6,4 @@ Just follow them:
|
||||
|
||||
|
||||
|
||||
**Let's just all be wholesome to each other please**
|
||||
## Let's just all be wholesome to each other please
|
||||
|
||||
+35
-16
@@ -1,6 +1,7 @@
|
||||
# Contributing to Distrobox
|
||||
|
||||
We greatly appreciate your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
|
||||
We greatly appreciate your input! We want to make contributing to this project
|
||||
as easy and transparent as possible, whether it's:
|
||||
|
||||
- Reporting a bug
|
||||
- Discussing the current state of the code
|
||||
@@ -21,7 +22,9 @@ We actively welcome your pull requests:
|
||||
|
||||
## Any contributions you make will be under the GPLv3 Software License
|
||||
|
||||
In short, when you submit code changes, your submissions are understood to be under the same [GPLv3 License](https://choosealicense.com/licenses/gpl-3.0/) that covers the project.
|
||||
In short, when you submit code changes, your submissions are understood to be
|
||||
under the same [GPLv3 License](https://choosealicense.com/licenses/gpl-3.0/) that
|
||||
covers the project.
|
||||
Feel free to contact the maintainers if that's a concern.
|
||||
|
||||
## Suggestions
|
||||
@@ -29,22 +32,27 @@ Feel free to contact the maintainers if that's a concern.
|
||||
Suggestions are welcome, be sure:
|
||||
|
||||
- it is not already being discussed in the [issue tracker](https://github.com/89luca89/distrobox/issues)
|
||||
- If it has and is marked as OPEN, go ahead and share your own thoughts about the topic!
|
||||
- If it has and is marked as CLOSED, please read the ticket and depending on whether the suggestion was accepted or not consider if it is worth opening a new issue or not.
|
||||
- If it has and is marked as OPEN, go ahead and share your own
|
||||
thoughts about the topic!
|
||||
- If it has and is marked as CLOSED, please read the ticket and depending on
|
||||
whether the suggestion was accepted or not consider if it is worth opening
|
||||
a new issue or not.
|
||||
- Consider if the suggestion is not too out of scope of the project.
|
||||
- Mark them with a [Suggestion] in the title
|
||||
|
||||
## Report bugs using Github's [issues](https://github.com/89luca89/distrobox/issues)
|
||||
|
||||
We use GitHub issues to track public bugs.
|
||||
Report a bug by [opening a new issue](); it's that easy!
|
||||
Report a bug by
|
||||
[opening a new issue](https://github.com/89luca89/distrobox/issues); it's that easy!
|
||||
|
||||
### Write bug reports with detail, background, and sample code
|
||||
|
||||
**A good bug report** should have:
|
||||
|
||||
- Check that the bug is not already discussed in the [issue tracker](https://github.com/89luca89/distrobox/issues)
|
||||
- See our [documentation](https://github.com/89luca89/distrobox/tree/main/docs) if there are some steps that could help you solve your issue
|
||||
- See our [documentation](https://github.com/89luca89/distrobox/tree/main/docs)
|
||||
if there are some steps that could help you solve your issue
|
||||
- Mark them with an [Error] in the title
|
||||
- A quick summary and/or background
|
||||
- Steps to reproduce
|
||||
@@ -52,28 +60,39 @@ Report a bug by [opening a new issue](); it's that easy!
|
||||
- Provide logs (terminal output, runs with verbose mode)
|
||||
- What you expected would happen
|
||||
- What actually happens
|
||||
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
|
||||
- Notes (possibly including why you think this might be happening, or stuff you
|
||||
tried that didn't work)
|
||||
|
||||
## Use a Consistent Coding Style
|
||||
|
||||
- use `shellcheck` to check for posix compliance and bashisms using:
|
||||
- `shellcheck -s sh -o all -Cnever -Sstyle -a -f gcc -x`
|
||||
- install from: [HERE](https://github.com/koalaman/shellcheck) following [this](https://github.com/koalaman/shellcheck#installing)
|
||||
- install from: [HERE](https://github.com/koalaman/shellcheck)
|
||||
following [this](https://github.com/koalaman/shellcheck#installing)
|
||||
- use `shfmt` to style the code using:
|
||||
- `shfmt -s`
|
||||
- install from [HERE](https://github.com/mvdan/sh) using `go install mvdan.cc/sh/v3/cmd/shfmt@latest`
|
||||
- Legibility of the code is more important than code golfing, try to be expressive in the code
|
||||
- Error checking is important! Ensure to LBYL (Look Before You Leap), check for variables and for code success exit codes
|
||||
- Don't hesitate to comment your code! We're placing high importance on this to maintain the code readable and understandeable
|
||||
- Update documentation to reflect your changes - Manual pages can be found in directory `docs`
|
||||
- Legibility of the code is more important than code golfing, try to be
|
||||
expressive in the code
|
||||
- Error checking is important! Ensure to LBYL (Look Before You Leap), check for
|
||||
variables and for code success exit codes
|
||||
- Don't hesitate to comment your code! We're placing high importance on this to
|
||||
maintain the code readable and understandeable
|
||||
- Update documentation to reflect your changes - Manual pages can be found in
|
||||
directory `docs`
|
||||
|
||||
If you are using Visual Studio Code, there are [plugins](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck) that include all this functionality and throw a warning if you're doing something wrong.
|
||||
If you are using Vim or Emacs there are plenty of linters and checkers that will integrate with the 2 tools listed above.
|
||||
If you are using Visual Studio Code, there are [plugins](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck)
|
||||
that include all this functionality and throw a warning if you're doing
|
||||
something wrong.
|
||||
If you are using Vim or Emacs there are plenty of linters and checkers that will
|
||||
integrate with the 2 tools listed above.
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under its GPLv3 License.
|
||||
By contributing, you agree that your contributions will be licensed under
|
||||
its GPLv3 License.
|
||||
|
||||
## References
|
||||
|
||||
This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)
|
||||
This document was adapted from the open-source contribution guidelines
|
||||
for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)
|
||||
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
### GNU GENERAL PUBLIC LICENSE
|
||||
# GNU GENERAL PUBLIC LICENSE
|
||||
|
||||
Version 3, 29 June 2007
|
||||
|
||||
@@ -8,7 +8,7 @@ Copyright (C) 2007 Free Software Foundation, Inc.
|
||||
Everyone is permitted to copy and distribute verbatim copies of this
|
||||
license document, but changing it is not allowed.
|
||||
|
||||
### Preamble
|
||||
## Preamble
|
||||
|
||||
The GNU General Public License is a free, copyleft license for
|
||||
software and other kinds of works.
|
||||
|
||||
@@ -67,7 +67,6 @@ Usage:
|
||||
distrobox-export --service syncthing.service [--extra-flags "flags"] [--delete] [--sudo]
|
||||
distrobox-export --bin /path/to/bin --export-path ~/.local/bin [--extra-flags "flags"] [--delete] [--sudo]
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
--app/-a: name of the application to export
|
||||
|
||||
+98
-51
@@ -11,10 +11,13 @@
|
||||
[](https://github.com/89luca89/distrobox/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
|
||||
[](https://github.com/89luca89/distrobox/issues?q=is%3Aissue+is%3Aopen+label%3A%22bug%22)
|
||||
|
||||
Use any Linux distribution inside your terminal. Enable both backward and forward compatibility with software and freedom to use whatever distribution you’re more comfortable with.
|
||||
Distrobox uses `podman` or `docker` to create containers using the Linux distribution of your choice.
|
||||
The created container will be tightly integrated with the host, allowing sharing of
|
||||
the HOME directory of the user, external storage, external USB devices and
|
||||
Use any Linux distribution inside your terminal. Enable both backward and forward
|
||||
compatibility with software and freedom to use whatever distribution you’re more
|
||||
comfortable with.
|
||||
Distrobox uses `podman` or `docker` to create containers using the Linux distribution
|
||||
of your choice.
|
||||
The created container will be tightly integrated with the host, allowing sharing
|
||||
of the HOME directory of the user, external storage, external USB devices and
|
||||
graphical apps (X11/Wayland), and audio.
|
||||
|
||||
---
|
||||
@@ -24,9 +27,9 @@ graphical apps (X11/Wayland), and audio.
|
||||
---
|
||||
|
||||
- [Distrobox](#distrobox)
|
||||
* [What it does](#what-it-does)
|
||||
- [What it does](#what-it-does)
|
||||
- [See it in action](#see-it-in-action)
|
||||
* [Why?](#why-)
|
||||
- [Why?](#why-)
|
||||
- [Aims](#aims)
|
||||
- [Installation](#installation)
|
||||
- [Uninstallation](#uninstallation)
|
||||
@@ -35,16 +38,16 @@ graphical apps (X11/Wayland), and audio.
|
||||
- [Host Distros](compatibility.md#host-distros)
|
||||
- [Containers Distros](compatibility.md#containers-distros)
|
||||
- [Usage](usage/usage.md)
|
||||
* [Outside the distrobox](#outside-the-distrobox)
|
||||
- [Outside the distrobox](#outside-the-distrobox)
|
||||
- [distrobox-create](usage/distrobox-create.md)
|
||||
- [distrobox-enter](usage/distrobox-enter.md)
|
||||
- [distrobox-list](usage/distrobox-list.md)
|
||||
- [distrobox-rm](usage/distrobox-rm.md)
|
||||
- [distrobox-stop](usage/distrobox-stop.md)
|
||||
* [Inside the distrobox](#inside-the-distrobox)
|
||||
- [Inside the distrobox](#inside-the-distrobox)
|
||||
- [distrobox-export](usage/distrobox-export.md)
|
||||
- [distrobox-init](usage/distrobox-init.md)
|
||||
* [Configure distrobox](#configure-distrobox)
|
||||
- [Configure distrobox](#configure-distrobox)
|
||||
- [Useful tips](useful_tips.md)
|
||||
- [Execute complex commands directly from distrobox-enter](useful_tips.md#execute-complex-commands-directly-from-distrobox-enter)
|
||||
- [Create a distrobox with a custom HOME directory](useful_tips.md#create-a-distrobox-with-a-custom-home-directory)
|
||||
@@ -84,14 +87,18 @@ graphical apps (X11/Wayland), and audio.
|
||||
|
||||
## What it does
|
||||
|
||||
Simply put it's a fancy wrapper around `podman` or `docker` to create and start containers highly integrated with the hosts.
|
||||
Simply put it's a fancy wrapper around `podman` or `docker` to create and start
|
||||
containers highly integrated with the hosts.
|
||||
|
||||
The distrobox environment is based on an OCI image.
|
||||
This image is used to create a 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, removable devices (like USB sticks), systemd journal, SSH agent, D-Bus,
|
||||
This image is used to create a 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, removable devices (like USB sticks),
|
||||
systemd journal, SSH agent, D-Bus,
|
||||
ulimits, /dev and the udev database, etc...
|
||||
|
||||
It implements the same concepts introduced by <https://github.com/containers/toolbox> but in a simplified way using POSIX sh and aiming at broader compatibility.
|
||||
It implements the same concepts introduced by <https://github.com/containers/toolbox>
|
||||
but in a simplified way using POSIX sh and aiming at broader compatibility.
|
||||
|
||||
All the props go to them as they had the great idea to implement this stuff.
|
||||
|
||||
@@ -102,38 +109,54 @@ It is divided into 6 commands:
|
||||
- `distrobox-list` - to list containers created with distrobox
|
||||
- `distrobox-rm` - to delete a container created with distrobox
|
||||
- `distrobox-stop` - to stop a running container created with distrobox
|
||||
- `distrobox-init` - it's the entrypoint of the container (not meant to be used manually)
|
||||
- `distrobox-export` - it is meant to be used inside the container, useful to export apps and services from the container to the host
|
||||
- `distrobox-init` - the entrypoint of the container (not meant to be used manually)
|
||||
- `distrobox-export` - it is meant to be used inside the container,
|
||||
useful to export apps and services from the container to the host
|
||||
|
||||
It also includes a little wrapper to launch commands with `distrobox COMMAND` instead of calling the single files.
|
||||
It also includes a little wrapper to launch commands with `distrobox COMMAND`
|
||||
instead of calling the single files.
|
||||
|
||||
### See it in action
|
||||
|
||||
Thanks to [castrojo](https://github.com/castrojo), you can see Distrobox in action in this explanatory video on his setup with Distrobox, Toolbx, Fedora Silverblue on his project [ublue](https://github.com/castrojo/ublue) (check it out!)
|
||||
Thanks to [castrojo](https://github.com/castrojo), you can see Distrobox in
|
||||
action in this explanatory video on his setup with Distrobox, Toolbx,
|
||||
Fedora Silverblue on his project [ublue](https://github.com/castrojo/ublue)
|
||||
(check it out!)
|
||||
|
||||
[](https://www.youtube.com/watch?v=Q2PrISAOtbY)
|
||||
|
||||
## Why
|
||||
|
||||
- Provide a mutable environment on an immutable OS, like Endless OS, Fedora Silverblue, OpenSUSE MicroOS or SteamOS3
|
||||
- Provide a locally privileged environment for sudoless setups (eg. company-provided laptops, security reasons, etc...)
|
||||
- To mix and match a stable base system (eg. Debian Stable, Ubuntu LTS, RedHat) with a bleeding-edge environment for development or gaming (eg. Arch, OpenSUSE Tumbleweed or Fedora with latest Mesa)
|
||||
- Leverage high abundance of curated distro images for docker/podman to manage multiple environments
|
||||
- Provide a mutable environment on an immutable OS, like Endless OS,
|
||||
Fedora Silverblue, OpenSUSE MicroOS or SteamOS3
|
||||
- Provide a locally privileged environment for sudoless setups
|
||||
(eg. company-provided laptops, security reasons, etc...)
|
||||
- To mix and match a stable base system (eg. Debian Stable, Ubuntu LTS, RedHat)
|
||||
with a bleeding-edge environment for development or gaming
|
||||
(eg. Arch, OpenSUSE Tumbleweed or Fedora with latest Mesa)
|
||||
- Leverage high abundance of curated distro images for docker/podman to
|
||||
manage multiple environments
|
||||
|
||||
Refer to the compatiblity list for an overview of supported host's distro [HERE](compatibility.md#host-distros) and container's distro [HERE](compatibility.md#containers-distros).
|
||||
Refer to the compatiblity list for an overview of supported host's distro
|
||||
[HERE](compatibility.md#host-distros) and container's distro [HERE](compatibility.md#containers-distros).
|
||||
|
||||
### Aims
|
||||
|
||||
This project aims to bring **any distro userland to any other distro** supporting podman or docker.
|
||||
It has been written in POSIX sh to be as portable as possible and not have problems with dependencies and glibc version's compatibility.
|
||||
This project aims to bring **any distro userland to any other distro**
|
||||
supporting podman or docker.
|
||||
It has been written in POSIX sh to be as portable as possible and not have
|
||||
problems with dependencies and glibc version's compatibility.
|
||||
|
||||
Refer [HERE](compatibility.md#supported-container-managers) for a list of supported container managers and minimum supported versions.
|
||||
Refer [HERE](compatibility.md#supported-container-managers) for a list of
|
||||
supported container managers and minimum supported versions.
|
||||
|
||||
It also aims to enter the container **as fast as possible**, every millisecond adds up if you use the container as your default environment for your terminal:
|
||||
It also aims to enter the container **as fast as possible**, every millisecond
|
||||
adds up if you use the container as your default environment for your terminal:
|
||||
|
||||
These are some sample results of `distrobox-enter` on the same container on my weak laptop from 2015 with 2 core cpu:
|
||||
These are some sample results of `distrobox-enter` on the same container on my
|
||||
weak laptop from 2015 with 2 core cpu:
|
||||
|
||||
```
|
||||
```sh
|
||||
Total time for 100 container enters:
|
||||
|
||||
~$ time (for i in {1..100}; do distrobox-enter --name fedora-toolbox-35 -- whoami; done)
|
||||
@@ -146,18 +169,25 @@ Mean:
|
||||
36.209s/100 = ~0.362ms mean time to enter the container
|
||||
```
|
||||
|
||||
I would like to keep it always below the [Doherty Treshold](https://lawsofux.com/doherty-threshold/) of 400ms.
|
||||
I would like to keep it always below the
|
||||
[Doherty Treshold](https://lawsofux.com/doherty-threshold/) of 400ms.
|
||||
|
||||
#### Security implications
|
||||
|
||||
Isolation and sandboxing is **not** the main aim of the project, on the conrary it aims to thightly integrate the container with the host.
|
||||
The container will have complete access to your home, pen drives and so on, so do not expect it to be highly sandboxed like a plain
|
||||
Isolation and sandboxing is **not** the main aim of the project, on the conrary
|
||||
it aims to thightly integrate the container with the host.
|
||||
The container will have complete access to your home, pen drives and so on,
|
||||
so do not expect it to be highly sandboxed like a plain
|
||||
docker/podman container or a flatpak.
|
||||
|
||||
⚠️ **BE CAREFUL**: if you use docker, the daemon runs as root by default, so **root inside the docker container can modify system stuff outside the container**, if you have security concern for this, **use podman that runs in rootless mode**.
|
||||
Rootless docker is still not working as intended and will be included in the future when it will be complete.
|
||||
⚠️ **BE CAREFUL**: if you use docker, the daemon runs as root by default, so
|
||||
**root inside the docker container can modify system stuff outside the container**,
|
||||
if you have security concern for this, **use podman that runs in rootless mode**.
|
||||
Rootless docker is still not working as intended and will be included in the future
|
||||
when it will be complete.
|
||||
|
||||
That said, it is in the works to implement some sort of decoupling with the host, as discussed here: [#28 Sandboxed mode](https://github.com/89luca89/distrobox/issues/28)
|
||||
That said, it is in the works to implement some sort of decoupling with the host,
|
||||
as discussed here: [#28 Sandboxed mode](https://github.com/89luca89/distrobox/issues/28)
|
||||
|
||||
---
|
||||
|
||||
@@ -187,7 +217,8 @@ Remove a distrobox
|
||||
|
||||
`distrobox rm test`
|
||||
|
||||
You can check [HERE for more advanced usage](usage/usage.md) and check a [comprehensive list of useful tips HERE](useful_tips.md)
|
||||
You can check [HERE for more advanced usage](usage/usage.md)
|
||||
and check a [comprehensive list of useful tips HERE](useful_tips.md)
|
||||
|
||||
# Configure Distrobox
|
||||
|
||||
@@ -220,56 +251,72 @@ Alternatively it is possible to specify preferences using ENV variables:
|
||||
|
||||
# Installation
|
||||
|
||||
Distrobox is packaged in the following distributions, if your distribution is on this list, you can refer to your repos for installation:
|
||||
Distrobox is packaged in the following distributions, if your distribution is
|
||||
on this list, you can refer to your repos for installation:
|
||||
|
||||
[](https://repology.org/project/distrobox/versions)
|
||||
|
||||
Thanks to the maintainers for their work: [M0Rf30](https://github.com/M0Rf30), [alcir](https://github.com/alcir), [dfaggioli](https://github.com/dfaggioli), [AtilaSaraiva](https://github.com/AtilaSaraiva)
|
||||
Thanks to the maintainers for their work: [M0Rf30](https://github.com/M0Rf30),
|
||||
[alcir](https://github.com/alcir), [dfaggioli](https://github.com/dfaggioli),
|
||||
[AtilaSaraiva](https://github.com/AtilaSaraiva)
|
||||
|
||||
Else, if you like to live your life dangerously, or you want the latest release, you can trust me and simply run this in your terminal:
|
||||
Else, if you like to live your life dangerously, or you want the latest release,
|
||||
you can trust me and simply run this in your terminal:
|
||||
|
||||
```
|
||||
```sh
|
||||
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh
|
||||
```
|
||||
|
||||
or if you want to select a custom directory to install without sudo:
|
||||
|
||||
```
|
||||
```sh
|
||||
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local
|
||||
```
|
||||
|
||||
Alternatively you can clone the project using `git clone` or using the latest release [HERE](https://github.com/89luca89/distrobox/releases/latest).
|
||||
Alternatively you can clone the project using `git clone` or using the latest
|
||||
release [HERE](https://github.com/89luca89/distrobox/releases/latest).
|
||||
|
||||
Enter the directory and run `./install`, by default it will attempt to install in `~/.local` but if you run the script as root, it will default to `/usr/local`. You can specify a custom directory with the `--prefix` flag such as `./install --prefix ~/.distrobox`.
|
||||
Enter the directory and run `./install`, by default it will attempt to install
|
||||
in `~/.local` but if you run the script as root, it will default to `/usr/local`.
|
||||
You can specify a custom directory with the `--prefix` flag
|
||||
such as `./install --prefix ~/.distrobox`.
|
||||
|
||||
Prefix explained: main distrobox files get installed to `${prefix}/bin` whereas the manpages get installed to `${prefix}/share/man`.
|
||||
Prefix explained: main distrobox files get installed to `${prefix}/bin` whereas
|
||||
the manpages get installed to `${prefix}/share/man`.
|
||||
|
||||
Check the [Host Distros](compatibility.md#host-distros) compatibility list for distro-specific instructions.
|
||||
Check the [Host Distros](compatibility.md#host-distros) compatibility list for
|
||||
distro-specific instructions.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Distrobox depends on a container manager to work, you can choose to install either podman or docker.
|
||||
Please look in the [Compatibility Table](compatibility.md#host-distros) for your distribution notes.
|
||||
Distrobox depends on a container manager to work, you can choose to install
|
||||
either podman or docker.
|
||||
Please look in the [Compatibility Table](compatibility.md#host-distros) for your
|
||||
distribution notes.
|
||||
|
||||
---
|
||||
|
||||
## Uninstallation
|
||||
|
||||
If you installed distrobox using the `install` script in the default install directory use this:
|
||||
If you installed distrobox using the `install` script in the default install
|
||||
directory use this:
|
||||
|
||||
```
|
||||
```sh
|
||||
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/uninstall | sudo sh
|
||||
```
|
||||
|
||||
or if you specified a custom path:
|
||||
|
||||
```
|
||||
```sh
|
||||
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/uninstall | sh -s -- --prefix ~/.local
|
||||
```
|
||||
|
||||
Else if cloned the project using `git clone` or using the latest archive release from [HERE](https://github.com/89luca89/distrobox/releases/latest),
|
||||
Else if cloned the project using `git clone` or using the latest archive release
|
||||
from [HERE](https://github.com/89luca89/distrobox/releases/latest),
|
||||
|
||||
enter the directory and run `./uninstall`, by default it will assume the install directory was `/usr/local` if ran as root or `~/.local`, you can specify another directory if needed with `./uninstall --prefix ~/.local`
|
||||
enter the directory and run `./uninstall`, by default it will assume the install
|
||||
directory was `/usr/local` if ran as root or `~/.local`,
|
||||
you can specify another directory if needed with `./uninstall --prefix ~/.local`
|
||||
|
||||
---
|
||||
|
||||
|
||||
+35
-21
@@ -10,14 +10,17 @@
|
||||
|
||||
# Compatibility
|
||||
|
||||
This project **does not need a dedicated image**. It can use any OCI images from docker-hub, quay.io, or any registry of your choice.
|
||||
This project **does not need a dedicated image**. It can use any OCI images from
|
||||
docker-hub, quay.io, or any registry of your choice.
|
||||
|
||||
Granted, they may not be as featureful as expected (some of them do not even have `which`, `mount`, `less` or `vi`)
|
||||
but that's all doable in the container itself after bootstrapping it.
|
||||
Granted, they may not be as featureful as expected (some of them do not even have
|
||||
`which`, `mount`, `less` or `vi`) but that's all doable in the container itself
|
||||
after bootstrapping it.
|
||||
|
||||
The main concern is having basic Linux utilities (`mount`), basic user management utilities (`usermod, passwd`), and `sudo` correctly set.
|
||||
The main concern is having basic Linux utilities (`mount`), basic user management
|
||||
utilities (`usermod, passwd`), and `sudo` correctly set.
|
||||
|
||||
### Supported container managers
|
||||
## Supported container managers
|
||||
|
||||
`distrobox` can run on either `podman` or `docker`
|
||||
|
||||
@@ -33,10 +36,12 @@ Follow the official installation guide here:
|
||||
- <https://docs.docker.com/engine/install>
|
||||
- <https://docs.docker.com/engine/install/linux-postinstall/>
|
||||
|
||||
### Host Distros
|
||||
## Host Distros
|
||||
|
||||
Distrobox has been successfully tested on:
|
||||
|
||||
<!-- markdownlint-capture -->
|
||||
<!-- markdownlint-disable -->
|
||||
| Distro | Version | Notes |
|
||||
| --- | --- | --- |
|
||||
| Alpine Linux | 3.14.3 | To setup rootless podman, look [HERE](https://wiki.alpinelinux.org/wiki/Podman) |
|
||||
@@ -56,29 +61,33 @@ Distrobox has been successfully tested on:
|
||||
| Void Linux | glibc | Systemd service export will not work. |
|
||||
| NixOS | 21.11 | Currently you must have your default shell set to Bash, if it is not, make sure you edit your configuration.nix so that it is. <br>Also make sure to mind your executable paths. Sometimes a container will not have nix paths, and sometimes it will not have its own paths. <br> Distrobox is available in Nixpkg collection (thanks [AtilaSaraiva](https://github.com/AtilaSaraiva)!)<<br>To setup Docker, look [HERE](https://nixos.wiki/wiki/Docker) <br>To setup Podman, look [HERE](https://nixos.wiki/wiki/Podman) and [HERE](https://gist.github.com/adisbladis/187204cb772800489ee3dac4acdd9947) |
|
||||
| Windows WSL2 | | __NOTE WSL2 support is preliminary, and there are many bugs present, any help in improving support is appreciated__ <br> Currently you must work around some incompatibility between WSL2 and Podman, namely [THIS](https://github.com/containers/podman/issues/12236). <br>Install into WSL2 any of the supported distributions in this list. <br> Ensure you have an entry in the `fstab` for the `/tmp` folder:<br> `echo 'tmpfs /tmp tmps defaults 0 0' >> /etc/fstab`.<br>Then reboot the WSL machine `wsl --shutdown` <br>Note that `distrobox export` is not supported on WSL2 and will not work. |
|
||||
<!-- markdownlint-restore -->
|
||||
|
||||
If your container is not able to connect to your host xserver, make sure to install `xhost` on the host machine
|
||||
and run `xhost +si:localuser:$USER`. If you wish to enable this functionality on future reboots add it to your `~/.xinitrc`
|
||||
If your container is not able to connect to your host xserver, make sure to
|
||||
install `xhost` on the host machine and run `xhost +si:localuser:$USER`.
|
||||
If you wish to enable this functionality on future reboots add it to your `~/.xinitrc`
|
||||
or somewhere else tailored to your use case where it would be ran on every startup.
|
||||
|
||||
List of distributions including distrobox in their repositories:
|
||||
|
||||
[](https://repology.org/project/distrobox/versions)
|
||||
|
||||
#### New Host Distro support
|
||||
### New Host Distro support
|
||||
|
||||
If your distro of choice is not on the list, open an issue requesting support for it,
|
||||
we can work together to check if it is possible to add support for it.
|
||||
If your distro of choice is not on the list, open an issue requesting support
|
||||
for it, we can work together to check if it is possible to add support for it.
|
||||
|
||||
Or just try using it anyway, if it works, open an issue
|
||||
and it will be added to the list!
|
||||
|
||||
---
|
||||
|
||||
### Containers Distros
|
||||
## Containers Distros
|
||||
|
||||
Distrobox guests tested successfully with the following container images:
|
||||
|
||||
<!-- markdownlint-capture -->
|
||||
<!-- markdownlint-disable -->
|
||||
| Distro | Version | Images |
|
||||
| --- | --- | --- |
|
||||
| AlmaLinux | 8 | docker.io/library/almalinux:8 |
|
||||
@@ -91,7 +100,7 @@ Distrobox guests tested successfully with the following container images:
|
||||
| CentOS | 7 | quay.io/centos/centos:7 |
|
||||
| CentOS Stream | 8<br>9 | quay.io/centos/centos:stream8<br>quay.io/centos/centos:stream9 |
|
||||
| RedHat (UBI) | 7<br>8 | registry.access.redhat.com/ubi7/ubi<br>registry.access.redhat.com/ubi7/ubi-init<br>registry.access.redhat.com/ubi8/ubi<br>registry.access.redhat.com/ubi8/ubi-init |
|
||||
| Debian | 8<br>9<br>10<br>11 | docker.io/library/debian:8<br>docker.io/library/debian:9<br>docker.io/library/debian:10<br>docker.io/library/debian:stable<br>docker.io/library/debian:stable-backports |
|
||||
| Debian | 7<br>8<br>9<br>10<br>11 | docker.io/debian/eol:wheezy<br>docker.io/library/debian:8<br>docker.io/library/debian:9<br>docker.io/library/debian:10<br>docker.io/library/debian:stable<br>docker.io/library/debian:stable-backports |
|
||||
| Debian | Testing | docker.io/library/debian:testing <br> docker.io/library/debian:testing-backports |
|
||||
| Debian | Unstable | docker.io/library/debian:unstable |
|
||||
| Neurodebian | nd100 | docker.io/library/neurodebian:nd100 |
|
||||
@@ -107,27 +116,32 @@ Distrobox guests tested successfully with the following container images:
|
||||
| Kali Linux | rolling | docker.io/kalilinux/kali-rolling:latest |
|
||||
| Void Linux | | ghcr.io/void-linux/void-linux:latest-full-x86_64 <br> ghcr.io/void-linux/void-linux:latest-full-x86_64-musl |
|
||||
| Gentoo Linux | rolling | You will have to [Build your own](distrobox_gentoo.md) to have a complete Gentoo docker image |
|
||||
<!-- markdownlint-restore -->
|
||||
|
||||
Note however that if you use a non-toolbox preconfigured image (e.g. images pre-baked to work with <https://github.com/containers/toolbox),> the **first** `distrobox-enter` you'll perform
|
||||
Note however that if you use a non-toolbox preconfigured image (e.g.
|
||||
images pre-baked to work with <https://github.com/containers/toolbox),>
|
||||
the **first** `distrobox-enter` you'll perform
|
||||
can take a while as it will download and install the missing dependencies.
|
||||
|
||||
A small time tax to pay for the ability to use any type of image.
|
||||
This will **not** occur after the first time, **subsequent enters will be much faster.**
|
||||
|
||||
NixOS is not a supported container distro, and there are currently no plans to bring support to it. If you are looking for unprivlaged NixOS environments, we suggest you look into [nix-shell](https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html).
|
||||
NixOS is not a supported container distro, and there are currently no plans to
|
||||
bring support to it. If you are looking for unprivlaged NixOS environments,
|
||||
we suggest you look into [nix-shell](https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html).
|
||||
|
||||
#### New Distro support
|
||||
### New Distro support
|
||||
|
||||
If your distro of choice is not on the list, open an issue requesting support for it,
|
||||
we can work together to check if it is possible to add support for it.
|
||||
If your distro of choice is not on the list, open an issue requesting support
|
||||
for it, we can work together to check if it is possible to add support for it.
|
||||
|
||||
Or just try using it anyway, if it works, open an issue
|
||||
and it will be added to the list!
|
||||
|
||||
#### Older distributions
|
||||
### Older distributions
|
||||
|
||||
For older distributions like CentOS 6, Debian 7, Ubuntu 12.04, compatibility is not
|
||||
assured.
|
||||
For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu 12.04,
|
||||
compatibility is not assured.
|
||||
|
||||
Their `libc` version is incompatible with kernel releases after `>=4.11`.
|
||||
A work around this is to use the `vsyscall=emulate` flag in the bootloader of the
|
||||
|
||||
@@ -5,14 +5,17 @@
|
||||
|
||||
# Create a dedicated distrobox container
|
||||
|
||||
Distrobox wants to be as generic as possible in supporting OCI images, but sometimes there could be some problems:
|
||||
Distrobox wants to be as generic as possible in supporting OCI images,
|
||||
but sometimes there could be some problems:
|
||||
|
||||
- The image you want to use is too old and the package manager mirrors are down
|
||||
- The image you want to use has not a supported package manager or no package manager at all
|
||||
- The image you want to use has not a supported package manager or no package
|
||||
manager at all
|
||||
|
||||
## Requirements
|
||||
|
||||
The only required programs that must be available in the container so that `distrobox-init` won't start the installation are:
|
||||
The only required programs that must be available in the container so that
|
||||
`distrobox-init` won't start the installation are:
|
||||
|
||||
- the $SHELL you use (bash, zsh, fish etc etc)
|
||||
- findutils
|
||||
@@ -23,7 +26,8 @@ The only required programs that must be available in the container so that `dist
|
||||
- libvte
|
||||
- util-linux (that provides the mount command)
|
||||
|
||||
If all those dependencies are met, then the `distrobox-init` will simply skip the installation process and work as expected.
|
||||
If all those dependencies are met, then the `distrobox-init`
|
||||
will simply skip the installation process and work as expected.
|
||||
|
||||
To test if all packages requirements are met just run this in the container:
|
||||
|
||||
|
||||
@@ -5,9 +5,10 @@
|
||||
|
||||
# Gentoo as a distrobox container
|
||||
|
||||
### Image
|
||||
## Image
|
||||
|
||||
You need to build your own image. The official resource is [here](https://github.com/gentoo/gentoo-docker-images#using-the-portage-container-in-a-multi-stage-build) but here is a simple Dockerfile:
|
||||
You need to build your own image. The official resource is [here](https://github.com/gentoo/gentoo-docker-images#using-the-portage-container-in-a-multi-stage-build)
|
||||
but here is a simple Dockerfile:
|
||||
|
||||
``` Dockerfile
|
||||
FROM registry.hub.docker.com/gentoo/portage:latest
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
- [Distrobox](README.md)
|
||||
* [Featured articles](#featured-articles)
|
||||
* [Podcasts](#podcasts)
|
||||
- [Featured articles](#featured-articles)
|
||||
- [Podcasts](#podcasts)
|
||||
|
||||
---
|
||||
|
||||
@@ -12,7 +12,9 @@
|
||||
- [Using Distrobox To Augment The Package Selection On Clear Linux - Phoronix](https://www.phoronix.com/scan.php?page=news_item&px=Distrobox-Clear-Linux)
|
||||
- [Benchmark: benefits of Clear Linux containers (distrobox) - Phoronix](https://www.phoronix.com/forums/forum/phoronix/latest-phoronix-articles/1305326-clear-linux-container-performance-continues-showing-sizable-gains)
|
||||
- [Distrobox - A great item in the Linux toolbelt - phmurphy's blog](https://phmurphy.com/posts/distrobox-toolbelt/)
|
||||
- Running Other Linux Distros with Distrobox on Fedora Linux - bandithijo's blog: [ORIGINAL](https://bandithijo.github.io/blog/menjalankan-distro-linux-lain-dengan-distrobox-di-fedora-linux) or [TRANSLATED](https://bandithijo-github-io.translate.goog/blog/menjalankan-distro-linux-lain-dengan-distrobox-di-fedora-linux?_x_tr_sl=id&_x_tr_tl=en&_x_tr_hl=it&_x_tr_pto=wapp)
|
||||
- Running Other Linux Distros with Distrobox on Fedora Linux - bandithijo's blog:
|
||||
[ORIGINAL](https://bandithijo.github.io/blog/menjalankan-distro-linux-lain-dengan-distrobox-di-fedora-linux)
|
||||
or [TRANSLATED](https://bandithijo-github-io.translate.goog/blog/menjalankan-distro-linux-lain-dengan-distrobox-di-fedora-linux?_x_tr_sl=id&_x_tr_tl=en&_x_tr_hl=it&_x_tr_pto=wapp)
|
||||
- [Day-to-day differences between Fedora Silverblue and Ubuntu - castrojo's blog](https://www.ypsidanger.com/day-to-day-advantages-of-fedora-silverblue/)
|
||||
|
||||
## Podcasts
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
- [Distrobox](../README.md)
|
||||
* [Execute a command on the Host](execute_commands_on_host.md)
|
||||
* [The easy one](#the-easy-one)
|
||||
* [The not so easy one](#the-not-so-easy-one)
|
||||
* [Integrate host with container seamlessly](#integrate-host-with-container-seamlessly)
|
||||
- [Execute a command on the Host](execute_commands_on_host.md)
|
||||
- [The easy one](#the-easy-one)
|
||||
- [The not so easy one](#the-not-so-easy-one)
|
||||
- [Integrate host with container seamlessly](#integrate-host-with-container-seamlessly)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
- [Distrobox](../README.md)
|
||||
* [Integrate VSCode and Distrobox](integrate_vscode_distrobox.md)
|
||||
* [The easy one](#the-easy-one)
|
||||
* [The not so easy one](#the-not-so-easy-one)
|
||||
- [Integrate VSCode and Distrobox](integrate_vscode_distrobox.md)
|
||||
- [The easy one](#the-easy-one)
|
||||
- [The not so easy one](#the-not-so-easy-one)
|
||||
- [First step, install it](#first-step--install-it)
|
||||
- [Second step, extensions](#second-step--extensions)
|
||||
- [Third step, podman wrapper](#third-step--podman-wrapper)
|
||||
- [Fourth step, configure the container](#fourth-step--configure-the-container)
|
||||
* [Final Result](#final-result)
|
||||
- [Final Result](#final-result)
|
||||
|
||||
---
|
||||
|
||||
@@ -32,7 +32,8 @@ For example using an Arch Linux container:
|
||||
user@arch-distrobox:~$
|
||||
```
|
||||
|
||||
Download the deb file [HERE](https://github.com/VSCodium/vscodium/releases), or in Arch case just install
|
||||
Download the deb file
|
||||
[HERE](https://github.com/VSCodium/vscodium/releases), or in Arch case just install
|
||||
|
||||
```shell
|
||||
user@arch-distrobox:~$ sudo pacman -S code
|
||||
@@ -73,8 +74,8 @@ Now we want to install VSCode [Remote Container extension](https://marketplace.v
|
||||
|
||||
### Third step, podman wrapper
|
||||
|
||||
Being in a Flatpak, we will need access to host's `podman` (or `docker`) to be able to use the containers.
|
||||
Place this in your `~/.local/bin/podman-host`
|
||||
Being in a Flatpak, we will need access to host's `podman` (or `docker`) to be
|
||||
able to use the containers. Place this in your `~/.local/bin/podman-host`
|
||||
|
||||
```shell
|
||||
#!/bin/bash
|
||||
@@ -84,7 +85,9 @@ if [ "$1" == "exec" ]; then
|
||||
shift
|
||||
script='
|
||||
result_command="podman exec"
|
||||
for i in $(printenv | grep "=" | grep -Ev " |\"" | grep -Ev "^(HOST|HOSTNAME|HOME|PATH|SHELL|USER|_)"); do
|
||||
for i in $(printenv | grep "=" | grep -Ev " |\"" |
|
||||
grep -Ev "^(HOST|HOSTNAME|HOME|PATH|SHELL|USER|_)"); do
|
||||
|
||||
result_command=$result_command --env="$i"
|
||||
done
|
||||
|
||||
@@ -101,7 +104,8 @@ set it to the path of `podman-exec`, like in the example
|
||||
|
||||
|
||||
|
||||
This will give a way to execute host's container manager from within the flatpak app.
|
||||
This will give a way to execute host's container manager from within the
|
||||
flatpak app.
|
||||
|
||||
### Fourth step, configure the container
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
- [Distrobox](../README.md)
|
||||
* [Run latest GNOME and KDE using distrobox](run_latest_gnome_kde_on_distrobox.md)
|
||||
- [Run latest GNOME and KDE using distrobox](run_latest_gnome_kde_on_distrobox.md)
|
||||
- [Using a stable-release distribution](#using-a-stable-release-distribution)
|
||||
* [Initializing the distrobox](#initializing-the-distrobox)
|
||||
* [Running Latest GNOME](#running-latest-gnome)
|
||||
- [Generate session file](#generate-session-file)
|
||||
* [Running Latest KDE](#running-latest-kde)
|
||||
- [Generate session file](#generate-session-file-1)
|
||||
- [Initializing the distrobox](#initializing-the-distrobox)
|
||||
- [Running Latest GNOME](#running-latest-gnome)
|
||||
- [Generate session file - GNOME](#generate-session-file-gnome)
|
||||
- [Running Latest KDE](#running-latest-kde)
|
||||
- [Generate session file - KDE](#generate-session-file-kde)
|
||||
- [Add a couple of fixes](#add-a-couple-of-fixes)
|
||||
- [Using apps from host](#using-apps-from-host)
|
||||
|
||||
@@ -13,15 +13,17 @@
|
||||
|
||||
# Using a stable-release distribution
|
||||
|
||||
Lots of people prefer to run a distribution following a stable-LTS release cycle like Debian, UbuntuLTS or
|
||||
CentOS family (Almalinux, Rocky Linux). This ensures great stability on one hand, but package staling on the other.
|
||||
Lots of people prefer to run a distribution following a stable-LTS release cycle
|
||||
like Debian, UbuntuLTS or CentOS family (Almalinux, Rocky Linux).
|
||||
This ensures great stability on one hand, but package staling on the other.
|
||||
|
||||
One way to counter this effect is to use a pet-container managed by Distrobox to run packages from much newer distributions
|
||||
without giving up on core base os stability.
|
||||
One way to counter this effect is to use a pet-container managed by Distrobox
|
||||
to run packages from much newer distributions without giving up on core base os stability.
|
||||
|
||||
## Initializing the distrobox
|
||||
|
||||
For this experiment we'll use Fedora Rawhide as our distrobox, and Centos 8 Stream as our host, so:
|
||||
For this experiment we'll use Fedora Rawhide as our distrobox, and Centos 8 Stream
|
||||
as our host, so:
|
||||
|
||||
```shell
|
||||
distrobox create --name fedora-rawhide --image registry.fedoraproject.org/fedora:rawhide
|
||||
@@ -35,8 +37,8 @@ distrobox enter fedora-rawhide
|
||||
|
||||
## Running Latest GNOME
|
||||
|
||||
First we need to change a couple of bits in the distrobox container to make host's systemd session
|
||||
accessible from within the host:
|
||||
First we need to change a couple of bits in the distrobox container to make host's
|
||||
systemd session accessible from within the host:
|
||||
|
||||
```shell
|
||||
~$ distrobox enter fedora-rawhide
|
||||
@@ -52,14 +54,15 @@ user@fedora-rawhide:~$ sudo dnf groupinstall GNOME
|
||||
|
||||
And let's grab a coffee while it finishes :-)
|
||||
|
||||
After the `dnf` process finishes, we have GNOME installed in our container, now how do we
|
||||
use it?
|
||||
After the `dnf` process finishes, we have GNOME installed in our container,
|
||||
now how do we use it?
|
||||
|
||||
### Generate session file
|
||||
### Generate session file - GNOME
|
||||
|
||||
First in the host we need a reliable way to fix the permissions problem of the `/tmp/.X11-unix` directory.
|
||||
This directory should either belong to `root` or `$USER`. But in a rootless container, host's `root` is not
|
||||
mapped inside the container so we need to change the ownership from `root` to `$USER` each time.
|
||||
First in the host we need a reliable way to fix the permissions problem of the
|
||||
`/tmp/.X11-unix` directory. This directory should either belong to `root` or
|
||||
`$USER`. But in a rootless container, host's `root` is not mapped inside the
|
||||
container so we need to change the ownership from `root` to `$USER` each time.
|
||||
|
||||
Let's add:
|
||||
|
||||
@@ -69,11 +72,11 @@ chown -R $USER:$USER /tmp/.X11-unix
|
||||
|
||||
to `/etc/profile.d/fix_tmp.sh` file.
|
||||
|
||||
This is needed for the XWayland session to work properly which right now is necessary to run gnome-shell
|
||||
even on wayland.
|
||||
This is needed for the XWayland session to work properly which right now is
|
||||
necessary to run gnome-shell even on wayland.
|
||||
|
||||
Then we need to add a desktop file for the session on the host's file system, so that it appears
|
||||
on your login manager (Be it SSDM or GDM)
|
||||
Then we need to add a desktop file for the session on the host's file system,
|
||||
so that it appears on your login manager (Be it SSDM or GDM)
|
||||
|
||||
```shell
|
||||
[Desktop Entry]
|
||||
@@ -98,7 +101,8 @@ Centos.
|
||||
|
||||
## Running Latest KDE
|
||||
|
||||
We can do the same with KDE also, let's first set up the host's systemd session sharing with the container:
|
||||
We can do the same with KDE also, let's first set up the host's systemd session
|
||||
sharing with the container:
|
||||
|
||||
```shell
|
||||
~$ distrobox enter fedora-rawhide
|
||||
@@ -112,10 +116,10 @@ Then we can proceed to install KDE in the container:
|
||||
user@fedora-rawhide:~$ sudo dnf groupinstall KDE
|
||||
```
|
||||
|
||||
### Generate session file
|
||||
### Generate session file - KDE
|
||||
|
||||
We need to add a desktop file for the session on the host's file system, so that it appears
|
||||
on your login manager (Be it SSDM or GDM)
|
||||
We need to add a desktop file for the session on the host's file system,
|
||||
so that it appears on your login manager (Be it SSDM or GDM)
|
||||
|
||||
```shell
|
||||
[Desktop Entry]
|
||||
@@ -131,9 +135,10 @@ This file should be placed under `/usr/share/wayland-sessions/distrobox-plasma.d
|
||||
|
||||
To make KDE work we need a couple more fixes to run both on the host and in the container.
|
||||
|
||||
First in the host we need a reliable way to fix the permissions problem of the `/tmp/.X11-unix` directory.
|
||||
This directory should either belong to `root` or `$USER`. But in a rootless container, host's `root` is not
|
||||
mapped inside the container so we need to change the ownership from `root` to `$USER` each time.
|
||||
First in the host we need a reliable way to fix the permissions problem of the
|
||||
`/tmp/.X11-unix` directory. This directory should either belong to `root` or
|
||||
`$USER`. But in a rootless container, host's `root` is not mapped inside the
|
||||
container so we need to change the ownership from `root` to `$USER` each time.
|
||||
|
||||
Let's add:
|
||||
|
||||
@@ -143,8 +148,9 @@ chown -R $USER:$USER /tmp/.X11-unix
|
||||
|
||||
to `/etc/profile.d/fix_tmp.sh` file.
|
||||
|
||||
We also need to add a process in autostart on which Plasma shell relies on a process called `kactivitymanagerd`.
|
||||
Not having host's systemd at disposal we can start it simply adding it to the ~/.profile file, add:
|
||||
We also need to add a process in autostart on which Plasma shell relies on a
|
||||
process called `kactivitymanagerd`. Not having host's systemd at disposal we
|
||||
can start it simply adding it to the ~/.profile file, add:
|
||||
|
||||
```shell
|
||||
if [ -f /usr/libexec/kactivitymanagerd ]; then
|
||||
@@ -164,6 +170,6 @@ Centos.
|
||||
|
||||
# Using apps from host
|
||||
|
||||
Now that we're in a container session, we may want to still use some of the host's apps.
|
||||
Refer to [THIS](execute_commands_on_host.md) to create handlers and wrappers to use
|
||||
the complete selection of host's apps and binaries inside the container.
|
||||
Now that we're in a container session, we may want to still use some of the host's
|
||||
apps. Refer to [THIS](execute_commands_on_host.md) to create handlers and wrappers
|
||||
to use the complete selection of host's apps and binaries inside the container.
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
### Create the distrobox
|
||||
<!-- markdownlint-disable MD010 -->
|
||||
# Create the distrobox
|
||||
|
||||
distrobox-create takes care of creating the container with input name and image.
|
||||
The created container will be tightly integrated with the host, allowing sharing of
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
### Enter the distrobox
|
||||
<!-- markdownlint-disable MD010 -->
|
||||
# Enter the distrobox
|
||||
|
||||
distrobox-enter takes care of entering the container with the name specified.
|
||||
Default command executed is your SHELL, but you can specify different shells or
|
||||
@@ -31,7 +32,6 @@ Options:
|
||||
|
||||
This is used to enter the distrobox itself. Personally, I just create multiple profiles in my `gnome-terminal` to have multiple distros accessible.
|
||||
|
||||
|
||||
The `--additional-flags` or `-a` is useful to modify default command when executing in the container.
|
||||
For example:
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
### Application and service exporting
|
||||
<!-- markdownlint-disable MD010 -->
|
||||
# Application and service exporting
|
||||
|
||||
distrobox-export takes care of exporting an app a binary or a service from the container
|
||||
to the host.
|
||||
@@ -46,7 +47,6 @@ Usage:
|
||||
distrobox-export --service syncthing [--extra-flags "flags"] [--delete] [--sudo]
|
||||
distrobox-export --bin /path/to/bin --export-path ~/.local/bin [--extra-flags "flags"] [--delete] [--sudo]
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
--app/-a: name of the application to export
|
||||
@@ -70,7 +70,7 @@ App export example:
|
||||
distrobox-export --app abiword
|
||||
|
||||
This tool will simply copy the original `.desktop` files along with needed icons,
|
||||
add the prefix `/usr/local/bin/distrobox-enter -n distrobox_name -e ... ` to the commands to run, and
|
||||
add the prefix `/usr/local/bin/distrobox-enter -n distrobox_name -e ...` to the commands to run, and
|
||||
save them in your home to be used directly from the host as a normal app.
|
||||
|
||||
Service export example:
|
||||
@@ -83,7 +83,6 @@ prefixing the various `ExecStart ExecStartPre ExecStartPost ExecReload ExecStop
|
||||
|
||||
Binary export example:
|
||||
|
||||
|
||||
distrobox-export --bin /usr/bin/code --extra-flags "--foreground" --export-path $HOME/.local/bin
|
||||
|
||||
In the case of exporting binaries, you will have to specify **where** to export it (`--export-path`) and the tool will create
|
||||
@@ -95,7 +94,6 @@ your `env` or project.
|
||||
|
||||
|
||||
|
||||
|
||||
NOTE: some electron apps such as vscode and atom need additional flags to work from inside the
|
||||
container, use the `--extra-flags` option to provide a series of flags, for example:
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
### Init the distrobox (not to be launched manually)
|
||||
<!-- markdownlint-disable MD010 -->
|
||||
# Init the distrobox (not to be launched manually)
|
||||
|
||||
distrobox-init is the entrypoint of a created distrobox.
|
||||
Note that this HAS to run from inside a distrobox, will not work if you run it
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
### List containers
|
||||
<!-- markdownlint-disable MD010 -->
|
||||
# List containers
|
||||
|
||||
distrobox-list lists available distroboxes. It detects them and lists them separately
|
||||
from the rest of normal podman or docker containers.
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
### Remove containers
|
||||
<!-- markdownlint-disable MD010 -->
|
||||
# Remove containers
|
||||
|
||||
distrobox-rm delete one of the available distroboxes.
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
### Stop containers
|
||||
<!-- markdownlint-disable MD010 -->
|
||||
# Stop containers
|
||||
|
||||
distrobox-rm delete one of the available distroboxes.
|
||||
|
||||
|
||||
+2
-2
@@ -1,10 +1,10 @@
|
||||
- [Distrobox](../README.md)
|
||||
* [Outside the distrobox](#outside-the-distrobox)
|
||||
- [Outside the distrobox](#outside-the-distrobox)
|
||||
- [distrobox-create](distrobox-create.md)
|
||||
- [distrobox-enter](distrobox-enter.md)
|
||||
- [distrobox-list](distrobox-list.md)
|
||||
- [distrobox-rm](distrobox-rm.md)
|
||||
- [distrobox-stop](distrobox-stop.md)
|
||||
* [Inside the distrobox](#inside-the-distrobox)
|
||||
- [Inside the distrobox](#inside-the-distrobox)
|
||||
- [distrobox-export](distrobox-export.md)
|
||||
- [distrobox-init](distrobox-init.md)
|
||||
|
||||
+57
-41
@@ -25,20 +25,22 @@
|
||||
|
||||
## Execute complex commands directly from distrobox-enter
|
||||
|
||||
Sometimes it is necessary to execure complex commands from a distrobox enter, like multiple concatenated commands using variables
|
||||
declared **inside** the container.
|
||||
Sometimes it is necessary to execure complex commands from a distrobox enter,
|
||||
like multiple concatenated commands using variables declared **inside** the container.
|
||||
|
||||
For example:
|
||||
|
||||
`distrobox enter test -- bash -l -c '"echo \$HOME && whoami"'`
|
||||
|
||||
Note the use of **single quotes around double quotes**, this is necessary so that quotes are preserved inside the arguments.
|
||||
Also note the **dollar escaping** needed so that $HOME is not evaluated at the time of the command launch, but directly
|
||||
Note the use of **single quotes around double quotes**, this is necessary so that
|
||||
quotes are preserved inside the arguments. Also note the **dollar escaping** needed
|
||||
so that $HOME is not evaluated at the time of the command launch, but directly
|
||||
inside the container.
|
||||
|
||||
## Create a distrobox with a custom HOME directory
|
||||
|
||||
`distrobox-create` supports the use of the `--home` flag, as specified in the usage [HERE](./usage/distrobox-create.md)
|
||||
`distrobox-create` supports the use of the `--home` flag, as specified in the
|
||||
usage [HERE](./usage/distrobox-create.md)
|
||||
|
||||
Simply use:
|
||||
|
||||
@@ -46,7 +48,8 @@ Simply use:
|
||||
|
||||
## Mount additional volumes in a distrobox
|
||||
|
||||
`distrobox-create` supports the use of the `--volume` flag, as specified in the usage [HERE](./usage/distrobox-create.md)
|
||||
`distrobox-create` supports the use of the `--volume` flag, as specified in the
|
||||
usage [HERE](./usage/distrobox-create.md)
|
||||
|
||||
Simply use:
|
||||
|
||||
@@ -62,7 +65,8 @@ If you want a different one you can use:
|
||||
|
||||
## Duplicate an existing distrobox
|
||||
|
||||
It can be useful to just duplicate an already set up environment, to do this, `distrobox-create` supports the use of the
|
||||
It can be useful to just duplicate an already set up environment, to do this,
|
||||
`distrobox-create` supports the use of the
|
||||
`--clone` flag, as specified in the usage [HERE](./usage/distrobox-create.md)
|
||||
|
||||
Simply use:
|
||||
@@ -71,8 +75,8 @@ Simply use:
|
||||
|
||||
## Export to the host
|
||||
|
||||
Distrobox supports exporting to the host either binaries, applications or systemd services.
|
||||
[Head over the usage page to have an explanation and examples.](usage/distrobox-export.md)
|
||||
Distrobox supports exporting to the host either binaries, applications or systemd
|
||||
services. [Head over the usage page to have an explanation and examples.](usage/distrobox-export.md)
|
||||
|
||||
## Execute commands on the host
|
||||
|
||||
@@ -80,11 +84,15 @@ You can check this little post about [executing commands on the host.](posts/exe
|
||||
|
||||
## Enable SSH X-Forwarding when SSH-ing in a distrobox
|
||||
|
||||
SSH X-forwarding by default will not work because the container hostname is different from the host's one.
|
||||
You can create a distrobox with will have the same hostname as the host by creating it with the following
|
||||
init-hook:
|
||||
SSH X-forwarding by default will not work because the container hostname is
|
||||
different from the host's one.
|
||||
You can create a distrobox with will have the same hostname as the host by
|
||||
creating it with the following init-hook:
|
||||
|
||||
`distrobox-create --name test --image your-choosen-image:tag --init-hooks '"$(uname -n)" > /etc/hostname'`
|
||||
```sh
|
||||
distrobox-create --name test --image your-choosen-image:tag \
|
||||
--init-hooks '"$(uname -n)" > /etc/hostname'`
|
||||
```
|
||||
|
||||
This will ensure SSH X-Forwarding will work when SSH-ing inside the distrobox:
|
||||
|
||||
@@ -92,21 +100,24 @@ This will ensure SSH X-Forwarding will work when SSH-ing inside the distrobox:
|
||||
|
||||
## Use distrobox to install different flatpaks from the host
|
||||
|
||||
By default distrobox will integrate with host's flatpak directory if present: `/var/lib/flatpak` and obviously
|
||||
with the $HOME one.
|
||||
By default distrobox will integrate with host's flatpak directory if present:
|
||||
`/var/lib/flatpak` and obviously with the $HOME one.
|
||||
|
||||
If you want to have a separate system remote between host and container, you can create your distrobox with
|
||||
the followint init-hook:
|
||||
If you want to have a separate system remote between host and container,
|
||||
you can create your distrobox with the followint init-hook:
|
||||
|
||||
`distrobox-create --name test --image your-choosen-image:tag --init-hooks 'umount /var/lib/flatpak'`
|
||||
```sh
|
||||
distrobox-create --name test --image your-choosen-image:tag \
|
||||
--init-hooks 'umount /var/lib/flatpak'`
|
||||
```
|
||||
|
||||
After that you'll be able to have separate flatpaks between host and distrobox.
|
||||
You can procede to export them using `distrobox-export` (for distrobox 1.2.14+)
|
||||
|
||||
## Using podman inside a distrobox
|
||||
|
||||
If `distrobox` is using `podman` as the container engine, you can use `podman socket` to
|
||||
control host's podman from inside a `distrobox`, just use:
|
||||
If `distrobox` is using `podman` as the container engine, you can use
|
||||
`podman socket` to control host's podman from inside a `distrobox`, just use:
|
||||
|
||||
`podman --remote`
|
||||
|
||||
@@ -127,7 +138,8 @@ you should be good to go.
|
||||
|
||||
## Using init system inside a distrobox
|
||||
|
||||
You can use an init system inside the container on supported images. Example of such images are:
|
||||
You can use an init system inside the container on supported images.
|
||||
Example of such images are:
|
||||
|
||||
- docker.io/almalinux/8-init
|
||||
- registry.access.redhat.com/ubi7/ubi-init
|
||||
@@ -137,7 +149,8 @@ You can use such feature using:
|
||||
|
||||
`distrobox create -i docker.io/almalinux/8-init --init --name test`
|
||||
|
||||
Note however that in this mode, you'll not be able to access host's processes from within the container.
|
||||
Note however that in this mode, you'll not be able to access host's processes
|
||||
from within the container.
|
||||
|
||||
Example use:
|
||||
|
||||
@@ -148,25 +161,25 @@ user@test:~$ sudo systemctl enable --now sshd
|
||||
|
||||
user@test:~$ sudo systemctl status sshd
|
||||
● sshd.service - OpenSSH server daemon
|
||||
Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
|
||||
Loaded: loaded (sshd.service; enabled; vendor preset: enabled)
|
||||
Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
|
||||
Docs: man:sshd(8)
|
||||
man:sshd_config(5)
|
||||
Main PID: 291 (sshd)
|
||||
|
||||
```
|
||||
|
||||
## Using distrobox as main cli
|
||||
|
||||
In case you want (like me) to use your container as the main CLI environment, it comes
|
||||
handy to use `gnome-terminal` profiles to create a dedicated setup for it:
|
||||
In case you want (like me) to use your container as the main CLI environment,
|
||||
it comes handy to use `gnome-terminal` profiles to create a dedicated setup for it:
|
||||
|
||||
|
||||
|
||||
Personally, I just bind `Ctrl-Alt-T` to the Distrobox profile and `Super+Enter` to the Host profile.
|
||||
Personally, I just bind `Ctrl-Alt-T` to the Distrobox profile and `Super+Enter`
|
||||
to the Host profile.
|
||||
|
||||
For other terminals, there are similar features (profiles) or you can set up a dedicated shortcut to
|
||||
launch a terminal directly in the distrobox
|
||||
For other terminals, there are similar features (profiles) or you can set up a
|
||||
dedicated shortcut to launch a terminal directly in the distrobox
|
||||
|
||||
## Improve distrobox-enter performance
|
||||
|
||||
@@ -179,10 +192,11 @@ this will improve a lot `podman`'s command performances.
|
||||
|
||||
## Slow creation on podman and image size getting bigger with distrobox-create
|
||||
|
||||
For rootless podman 3.4.0 and upward, adding this to your `~/.config/containers/storage.conf` file
|
||||
will improve container creation speed and fix issues with images getting bigger when using rootless containers.
|
||||
For rootless podman 3.4.0 and upward, adding this to your `~/.config/containers/storage.conf`
|
||||
file will improve container creation speed and fix issues with images getting
|
||||
bigger when using rootless containers.
|
||||
|
||||
```
|
||||
```conf
|
||||
[storage]
|
||||
driver = "overlay"
|
||||
|
||||
@@ -190,13 +204,15 @@ driver = "overlay"
|
||||
mount_program = "/usr/bin/fuse-overlayfs"
|
||||
```
|
||||
|
||||
Note that this is necessary only on Kernel version older than `5.11` . From version `5.11` onwards
|
||||
native `overlayfs` is supported and reports noticeable gains in performance as explained [HERE](https://www.redhat.com/sysadmin/podman-rootless-overlay)
|
||||
Note that this is necessary only on Kernel version older than `5.11` .
|
||||
From version `5.11` onwards native `overlayfs` is supported and reports noticeable
|
||||
gains in performance as explained [HERE](https://www.redhat.com/sysadmin/podman-rootless-overlay)
|
||||
|
||||
## Container save and restore
|
||||
|
||||
To save, export and reuse an already configured container, you can leverage `podman save` or `docker save` and `podman import` or `docker import`
|
||||
to create snapshots of your environment.
|
||||
To save, export and reuse an already configured container, you can leverage
|
||||
`podman save` or `docker save` and `podman import` or `docker import` to
|
||||
create snapshots of your environment.
|
||||
|
||||
---
|
||||
|
||||
@@ -204,14 +220,14 @@ To save a container to an image:
|
||||
|
||||
with podman:
|
||||
|
||||
```
|
||||
```sh
|
||||
podman container commit -p distrobox_name image_name_you_choose
|
||||
podman save image_name_you_choose:latest | gzip > image_name_you_choose.tar.gz
|
||||
```
|
||||
|
||||
with docker:
|
||||
|
||||
```
|
||||
```sh
|
||||
docker container commit -p distrobox_name image_name_you_choose
|
||||
docker save image_name_you_choose:latest | gzip > image_name_you_choose.tar.gz
|
||||
```
|
||||
@@ -223,19 +239,19 @@ This will create a tar.gz of the container of your choice at that exact moment.
|
||||
Now you can backup that archive or transfer it to another host, and to restore it
|
||||
just run
|
||||
|
||||
```
|
||||
```sh
|
||||
podman load < image_name_you_choose.tar.gz
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
```sh
|
||||
docker load < image_name_you_choose.tar.gz
|
||||
```
|
||||
|
||||
And create a new container based on that image:
|
||||
|
||||
```
|
||||
```sh
|
||||
distrobox-create --image image_name_you_choose:latest --name distrobox_name
|
||||
distrobox-enter --name distrobox_name
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user