gilles/runon
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

README update for 2.0.0

Browse Source
This commit is contained in:
Gilles Grandou 2023-12-04 21:49:44 +01:00
parent d4df0a1abd
commit c3d3ad26ce
1 changed files with 185 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

283
README.md
View File

@ -6,24 +6,31 @@ licensed under GPL-2.0.
home: https://git.grandou.net/gilles/runon 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 Quick HOWTO
----------- -----------
$ grep ^PRETTY_NAME /etc/os-release $ 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 $ runon centos7 grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="CentOS Linux 7 (Core)" PRETTY_NAME="CentOS Linux 7 (Core)"
$ runon ubuntu20.04 grep ^PRETTY_NAME /etc/os-release $ 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 $ runon debian9 grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="Debian GNU/Linux 9 (stretch)" PRETTY_NAME="Debian GNU/Linux 9 (stretch)"
$ runon centos7 xclock $ runon rocky9 xterm
[xclock launched!] [xterm launched!]
Install Install
@ -31,67 +38,101 @@ Install
Installation has been tested on: Installation has been tested on:
* Debian 10 (buster) * Debian 11 (bullseye)
* Ubuntu 20.04 (Focal) * Debian 12 (bookworm)
* RockyLinux 9.3 (Blue Onyx)
However it should work straightforward on any equivalent system. However it should work straightforward on any equivalent system.
### Docker Install ### Podman Install
sudo apt install docker If not already installed, just run as root the suitable command for your system:
sudo systemctl enable --now docker
Check that your are member of `docker` group: apt install podman
dnf install podman
sudo adduser <user> docker To check that podman is correctly installed, just try:
If needed, you need to logout and login again for the new group to $ podman run -it hello-world
become active. 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 ### 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 ### manual install
cd <tools> cd <tools>
git clone https://git.grandou.net/gilles/runon git clone https://git.grandou.net/gilles/runon
local install, in your `~/local/bin` (or wherever directory which is in your local install, in your `~/.local/bin`
PATH):
cd <runon> cd <runon>
./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 <your_bin_path> ./install --dev
system install, for all users: each user can have its own configuration in `~/.config/runon/runon.conf`.
cd <runon> You can keep your configuration in several places, the 1st one which is
sudo ./install system 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 ### uninstall
simply pass `-u` to install command you have used, eg.: To uninstall, just run:
./uninstall
./install local -u
./install local -u <dir>
sudo ./install system -u
### some convenient links ### some convenient links
you can create soft links to `runos` to simplify calls: 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 ...`: now calling `centos7 ...` is equivalent to call `runos centos7 ...`:
centos7 xclock centos7 xterm
Usage Usage
@ -101,7 +142,8 @@ With the default configuration, a seamless environment is set up,
allowing to transparently run commands in various environments, while allowing to transparently run commands in various environments, while
keeping: keeping:
* user environment (uid, gid, password, home directory, ...) * user environment (uid, gid, home directory, ...)
* password less sudo support
* X support to run graphical applications * X support to run graphical applications
### Basic usage ### Basic usage
@ -112,11 +154,7 @@ keeping:
### available options ### available options
* `-v` verbose output, this is really usefull when running new * `-v` verbose output, display information on the current startup step
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`.
* `-u` forces the container image to be updated, useful if the * `-u` forces the container image to be updated, useful if the
distribution has been updated and you want to use it. Otherwise, distribution has been updated and you want to use it. Otherwise,
@ -126,6 +164,38 @@ keeping:
* `-c <configfile>` uses a custom config file, useful to try new * `-c <configfile>` uses a custom config file, useful to try new
distribution without breaking your running config. 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 ### Interactive shell
Just run: Just run:
@ -134,84 +204,98 @@ Just run:
while start an insteractive shell in the container system: while start an insteractive shell in the container system:
gilles@host:~$ runon centos8 $ runon ubuntu22.04
(centos8) gilles@host:~$ cat /etc/os-release (ubuntu22.04) gilles@host:~$ cat /etc/os-release
NAME="CentOS Linux" PRETTY_NAME="Ubuntu 22.04.3 LTS"
VERSION="8" NAME="Ubuntu"
ID="centos" VERSION_ID="22.04"
ID_LIKE="rhel fedora" VERSION="22.04.3 LTS (Jammy Jellyfish)"
VERSION_ID="8" VERSION_CODENAME=jammy
PLATFORM_ID="platform:el8" ID=ubuntu
PRETTY_NAME="CentOS Linux 8" ID_LIKE=debian
ANSI_COLOR="0;31" HOME_URL="https://www.ubuntu.com/"
CPE_NAME="cpe:/o:centos:centos:8" SUPPORT_URL="https://help.ubuntu.com/"
HOME_URL="https://centos.org/" BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
BUG_REPORT_URL="https://bugs.centos.org/" PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
CENTOS_MANTISBT_PROJECT="CentOS-8" UBUNTU_CODENAME=jammy
CENTOS_MANTISBT_PROJECT_VERSION="8" (ubuntu22.04) gilles@host:~$ xclock
(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
^C ^C
(centos8) gilles@host:~$ exit (ubuntu22.04) gilles@host:~$ exit
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
------------- -------------
Configuration is done in `runon.conf` file, which describes supported Configuration is done in `runon.yaml` file, which describes supported
distribution in .INI format. distribution in YAML format.
### Example config ### Example config
``` ```
[DEFAULT] rh_base: &rh_base
environment = dockerfile:
HOME - RUN dnf install -y sudo
USER - RUN echo "Defaults lecture = never" >> /etc/sudoers
DISPLAY - RUN echo "ALL ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
debian_chroot=${osname} - 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 = rocky8:
/etc/passwd:ro <<: *rh_base
/etc/group:ro image: docker.io/rockylinux:8
/etc/shadow:ro
/tmp/.X11-unix:ro
/home/${user}
[centos8] rocky9:
dockerfile = <<: *rh_base
FROM centos:8 image: docker.io/rockylinux:9
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
``` ```
Each section `[osname]` defines a distribution which can be used by runon. Each entry which contains an `image:` field defines a distribution which can
The `[DEFAULT]` section defines default values which is used if not be used by runon. In the above example the other entries are used as templates
overriden in individual section. for real entries.
### Config entries ### Config entries
* `image` the base image used to build the container.
* `dockerfile` the base content of dockerfile which will be used to * `dockerfile` the base content of dockerfile which will be used to
generate the running environment. There is usually no need to diverge generate the running environment. There is usually no need to diverge
from the ones given in example. 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 * `environment` the list of environment variables you want to pass or
set in the container system. See below for a description 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: 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 ### Binds