diff --git a/README.md b/README.md index 449af6b..74b5b4e 100644 --- a/README.md +++ b/README.md @@ -6,24 +6,31 @@ licensed under GPL-2.0. home: https://git.grandou.net/gilles/runon +Runon is a frontend to podman allowing to run seamlessly any application in +any linux based operating system, including graphical applications, while +keeping the host user environment. + +the v1 legacy runon branch was based on docker. Current versions are now +relying on podman. + Quick HOWTO ----------- $ grep ^PRETTY_NAME /etc/os-release - PRETTY_NAME="Debian GNU/Linux 10 (buster)" + PRETTY_NAME="Debian GNU/Linux 12 (bookworm)" $ runon centos7 grep ^PRETTY_NAME /etc/os-release PRETTY_NAME="CentOS Linux 7 (Core)" $ runon ubuntu20.04 grep ^PRETTY_NAME /etc/os-release - PRETTY_NAME="Ubuntu 20.04.2 LTS" + PRETTY_NAME="Ubuntu 20.04.6 LTS" $ runon debian9 grep ^PRETTY_NAME /etc/os-release PRETTY_NAME="Debian GNU/Linux 9 (stretch)" - $ runon centos7 xclock - [xclock launched!] + $ runon rocky9 xterm + [xterm launched!] Install @@ -31,67 +38,101 @@ Install Installation has been tested on: -* Debian 10 (buster) -* Ubuntu 20.04 (Focal) +* Debian 11 (bullseye) +* Debian 12 (bookworm) +* RockyLinux 9.3 (Blue Onyx) However it should work straightforward on any equivalent system. -### Docker Install +### Podman Install - sudo apt install docker - sudo systemctl enable --now docker +If not already installed, just run as root the suitable command for your system: -Check that your are member of `docker` group: + apt install podman + dnf install podman - sudo adduser docker +To check that podman is correctly installed, just try: -If needed, you need to logout and login again for the new group to -become active. + $ podman run -it hello-world + Resolved "hello-world" as an alias (/etc/containers/registries.conf.d/shortnames.conf) + Trying to pull docker.io/library/hello-world:latest... + Getting image source signatures + Copying blob 719385e32844 done + Copying config 9c7a54a9a4 done + Writing manifest to image destination + Storing signatures + + Hello from Docker! + This message shows that your installation appears to be working correctly. + [...] + +If your encounter an error like this one: + + Error: writing blob: adding layer with blob "sha256:3331450fb84fde695e565405a554d5cf213a33826da197b29aabde08be012f8b": Error processing tar file(exit status 1): potentially insufficient UIDs or GIDs available in user namespace (requested 0:42 for /etc/gshadow): Check /etc/subuid and /etc/subgid: lchown /etc/gshadow: invalid argument + +it's likely that your user account has been create a while ago on a legacy +distribution release and has no support for `subuid` and `subgid`. You can +fix it easily with these commands: + + sudo usermod --add-subgids 10000-75535 $USER + sudo usermod --add-subuids 10000-75535 $USER + podman system migrate + podman pull + +If you're running on a Debian system, there is a good explanation of the above problem in `/usr/share/doc/podman/README.Debian`. ### Python Dependencies - sudo apt install python3-docker python3-dockerpty python3-xdg +There is no specific dependency, you just need to insure to have: + +* a Python release 3.6 or better +* the python `venv` module +* the python `pip` module + ### manual install cd git clone https://git.grandou.net/gilles/runon -local install, in your `~/local/bin` (or wherever directory which is in your -PATH): +local install, in your `~/.local/bin` cd - ./install local + ./install -or +If you plan to work `runon` development, you can +pass `--dev` to install links to your current git clone: - ./install local + ./install --dev -system install, for all users: +each user can have its own configuration in `~/.config/runon/runon.conf`. - cd - sudo ./install system +You can keep your configuration in several places, the 1st one which is +find is used: + +* `runon.yaml` in the current directory +* `.runon.yaml` in the current directory +* `~/.config/runon/runon.yaml` +* `~/.config/runon/runon.default.yaml`, the configuration file installed by + default -each user can have its own configuration in `~/.config/runon/runon.conf` -if needed. ### uninstall -simply pass `-u` to install command you have used, eg.: +To uninstall, just run: + + ./uninstall - ./install local -u - ./install local -u - sudo ./install system -u ### some convenient links you can create soft links to `runos` to simplify calls: - runos centos7 -l + runos -l centos7 now calling `centos7 ...` is equivalent to call `runos centos7 ...`: - centos7 xclock + centos7 xterm Usage @@ -101,7 +142,8 @@ With the default configuration, a seamless environment is set up, allowing to transparently run commands in various environments, while keeping: -* user environment (uid, gid, password, home directory, ...) +* user environment (uid, gid, home directory, ...) +* password less sudo support * X support to run graphical applications ### Basic usage @@ -112,11 +154,7 @@ keeping: ### available options -* `-v` verbose output, this is really usefull when running new - containers for the first time, as the initial docker build can be - quite long (several minutes) especially with slow internet link. - If the command seems to be stalled, don't hesitate to interrupt it - (with `CTRL-C`) and to restart it with `-v`. +* `-v` verbose output, display information on the current startup step * `-u` forces the container image to be updated, useful if the distribution has been updated and you want to use it. Otherwise, @@ -126,6 +164,38 @@ keeping: * `-c ` uses a custom config file, useful to try new distribution without breaking your running config. +* `-l` create an executable link with the `osname` name. you can after + run the command with `osname [...]` instead of `runos osname [...]` + +### Listing available distributions: + +Just run: + + $ runon list + Available distributions: + centos7 + debian10 + debian11 + debian12 + debian9 + rocky8 + rocky9 + ubuntu20.04 + ubuntu22.04 + +This lists all `osname` present in your current configuration file. + +### Editing configuration: + +you can easily open the current configuration file with: + + $ runon edit + +If you open the `runon.default.yaml` file, take care to save your changes in +a new `runon.yaml` file to avoid the default one, which could be overwritten +next time you install or update `runon`. + + ### Interactive shell Just run: @@ -134,84 +204,98 @@ Just run: while start an insteractive shell in the container system: - gilles@host:~$ runon centos8 - (centos8) gilles@host:~$ cat /etc/os-release - NAME="CentOS Linux" - VERSION="8" - ID="centos" - ID_LIKE="rhel fedora" - VERSION_ID="8" - PLATFORM_ID="platform:el8" - PRETTY_NAME="CentOS Linux 8" - ANSI_COLOR="0;31" - CPE_NAME="cpe:/o:centos:centos:8" - HOME_URL="https://centos.org/" - BUG_REPORT_URL="https://bugs.centos.org/" - CENTOS_MANTISBT_PROJECT="CentOS-8" - CENTOS_MANTISBT_PROJECT_VERSION="8" - (centos8) gilles@host:~$ id - uid=1000(gilles) gid=1000(gilles) groups=1000(gilles) - (centos8) gilles@host:~$ sudo id - [sudo] password for gilles: - uid=0(root) gid=0(root) groups=0(root) - (centos8) gilles@host:~$ xclock + $ runon ubuntu22.04 + (ubuntu22.04) gilles@host:~$ cat /etc/os-release + PRETTY_NAME="Ubuntu 22.04.3 LTS" + NAME="Ubuntu" + VERSION_ID="22.04" + VERSION="22.04.3 LTS (Jammy Jellyfish)" + VERSION_CODENAME=jammy + ID=ubuntu + ID_LIKE=debian + HOME_URL="https://www.ubuntu.com/" + SUPPORT_URL="https://help.ubuntu.com/" + BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" + PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" + UBUNTU_CODENAME=jammy + (ubuntu22.04) gilles@host:~$ xclock ^C - (centos8) gilles@host:~$ exit + (ubuntu22.04) gilles@host:~$ exit exit - gilles@host:~$ + +To help differentiate the environment on are running on, you can add this +snippet to your `.bashrc`: + + # container + if [ -n "$container" ]; then + PS1="($container) $PS1" + fi + +This now displays your `runon` name on your bash prompt. Configuration ------------- -Configuration is done in `runon.conf` file, which describes supported -distribution in .INI format. +Configuration is done in `runon.yaml` file, which describes supported +distribution in YAML format. ### Example config ``` -[DEFAULT] -environment = - HOME - USER - DISPLAY - debian_chroot=${osname} +rh_base: &rh_base + dockerfile: + - RUN dnf install -y sudo + - RUN echo "Defaults lecture = never" >> /etc/sudoers + - RUN echo "ALL ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers + - RUN dnf group install -y "Development Tools" + pkginstall: + "RUN dnf install -y {}" + packages: + - xterm + - vim-X11 + - git + - python3 + - bash-completion + binds: + - /etc/timezone:ro + - /etc/localtime:ro + - "{home}" + environment: + - USER + - DISPLAY + - TERM + - container={osname} +centos7: + <<: *rh_base + image: docker.io/centos:7 + dockerfile: + - RUN yum install -y sudo + - RUN echo "Defaults lecture = never" >> /etc/sudoers + - RUN echo "ALL ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers + - RUN yum group install -y "Development Tools" + pkginstall: + "RUN yum install -y {}" -binds = - /etc/passwd:ro - /etc/group:ro - /etc/shadow:ro - /tmp/.X11-unix:ro - /home/${user} +rocky8: + <<: *rh_base + image: docker.io/rockylinux:8 -[centos8] -dockerfile = - FROM centos:8 - RUN yum install dnf-plugins-core -y - RUN yum config-manager --set-enabled powertools -y - RUN yum install sudo -y - RUN echo "Defaults lecture = never" >> /etc/sudoers - RUN echo "ALL ALL=(ALL) ALL" >> /etc/sudoers -pkginstall = RUN yum install {} -y -packages = ksh csh xterm xorg-x11-apps xkeyboard-config git - -[debian9] -dockerfile = - FROM debian:9 - RUN apt-get update - RUN apt-get -y install sudo - RUN echo "Defaults lecture = never" >> /etc/sudoers -pkginstall = RUN apt-get -y install {} -packages = ksh csh xterm x11-apps libgtk-3-0 build-essential git +rocky9: + <<: *rh_base + image: docker.io/rockylinux:9 ``` -Each section `[osname]` defines a distribution which can be used by runon. -The `[DEFAULT]` section defines default values which is used if not -overriden in individual section. +Each entry which contains an `image:` field defines a distribution which can +be used by runon. In the above example the other entries are used as templates +for real entries. + ### Config entries +* `image` the base image used to build the container. + * `dockerfile` the base content of dockerfile which will be used to generate the running environment. There is usually no need to diverge from the ones given in example. @@ -230,12 +314,15 @@ overriden in individual section. * `environment` the list of environment variables you want to pass or set in the container system. See below for a description -Lines starting with `#` or `;` are comments. +Lines starting with `#` or are comments. Some substitution happens upon reading the configuration: -* `${user}` the current username -* `${osname}` the executed distribution. +* `{osname}` the executed distribution. +* `{user}` the current username +* `{uid}` the current UID +* `{home}` the user's home directory + ### Binds