add README
This commit is contained in:
237
README.md
Normal file
237
README.md
Normal file
@ -0,0 +1,237 @@
|
||||
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
|
||||
|
||||
|
||||
## manual install
|
||||
|
||||
cd <tools>
|
||||
git clone https://git.grandou.net/gilles/runon
|
||||
|
||||
local install, in you `~/bin` (or wherever directory which is in your
|
||||
PATH):
|
||||
|
||||
cd ~/bin
|
||||
ln -s ~/tools/runon/runon
|
||||
|
||||
mkdir ~/.config/runon
|
||||
cp <tools>/runon/runon.conf ~/.config/runon/
|
||||
|
||||
system install, for all users, as `root`:
|
||||
|
||||
mkdir /etc/runon
|
||||
cp <tools>/run/runon /usr/local/bin/runon
|
||||
cp <tools>/run/runon.conf /etc/runon/
|
||||
|
||||
each user can have its own configuration in `~/.config/runon/runon.conf`.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user