run command on any linux distribution, transparently using docker containers
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
runon/README.md

260 lines
6.3 KiB

2 years ago
RUNON - Run your commands in any systems
========================================
home: https://git.grandou.net/gilles/runon
Quick HOWTO
-----------
$ grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="Debian GNU/Linux 10 (buster)"
$ 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"
$ runon debian9 grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="Debian GNU/Linux 9 (stretch)"
$ runon centos7 xclock
[xclock launched!]
Install
-------
Installation is only tested on Debian 10, even though it should work
straightforward on any equivalent system.
## Docker Install
sudo apt install docker
Check that your user is part of `docker` group:
sudo adduser <user> docker
If needed, you need to logout and login again for the new group to
become active.
2 years ago
## manual install
cd <tools>
git clone https://git.grandou.net/gilles/runon
local install, in your `~/local/bin` (or wherever directory which is in your
2 years ago
PATH):
cd <runon>
./install local
2 years ago
or
2 years ago
./install local <your_bin_path>
2 years ago
system install, for all users:
2 years ago
cd <runon>
sudo ./install system
2 years ago
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.:
./install local -u
./install local -u <dir>
sudo ./install system -u
2 years ago
2 years ago
## some convenient links
you can create soft links to `runos` to simplify calls:
cd /usr/local/bin
ln -s runon centos7
now calling `centos7 ...` is equivalent to call `runos centos7 ...`:
centos7 xclock
2 years ago
Usage
-----
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, ...)
* X support to run graphical applications
## Basic usage
runon [options] <osname> <command>
runon -h
## 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`.
* `-u` forces the container image to be updated, useful if the
distribution has been updated and you want to use it. Otherwise,
if a container has been already built, it will be used directly
without doing any network access.
* `-c <configfile>` uses a custom config file, useful to try new
distribution without breaking your running config.
## Interactive shell
Just run:
runon <osname>
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
^C
(centos8) gilles@host:~$ exit
exit
gilles@host:~$
Configuration
-------------
Configuration is done in `runon.conf` file, which describes supported
distribution in .INI format.
## Example config
```
[DEFAULT]
environment =
HOME
USER
DISPLAY
debian_chroot=${osname}
binds =
/etc/passwd:ro
/etc/group:ro
/etc/shadow:ro
/tmp/.X11-unix:ro
/home/${user}
[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
```
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.
## Config entries
* `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.
* `pkginstall` the dockerfile command used to install a package, likely
to be standard for all `deb` and `rpm` based distributions. In the
command `{}` is replaced by the package name.
* `packages` the list of packages to install. Feel free to add the ones
you need for your commands (likely news system libs, new tools, ...)
* `binds` the list of files and directories from the host system to
expose in the container system. you might want to add `/opt` or other
shared directories. See below for a description of `binds` entries
* `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.
Some substitution happens upon reading the configuration:
* `${user}` the current username
* `${osname}` the executed distribution.
## Binds
Each `binds` line can have one of the following formats:
<hostpath>
<hostpath>:<mode>
<hostpath>:<containerpath>
<hostpath>:<containerpath>:<mode>
with:
* `<hostpath>` is the filename or the dirname of the path you want
to expose
* `<containerpath>` is the pathname inside the container, by default
it's the same path.
* `<mode>` can be `rw`, read-write (by default), or `ro`, read-only.
## Environment
Each `environment` line define a Environment Variable which is set
in the container upon execution.
Each line can have one of the following formats:
<envvar>
<envvar>=<value>
If no value is given, the host value is passed into the container.