From d3c54092a9fa06c5424d36fe14321179d1c8fdbb Mon Sep 17 00:00:00 2001 From: Aline Manera Date: Wed, 4 Dec 2019 22:50:49 -0500 Subject: [PATCH] Update docs Signed-off-by: Aline Manera --- docs/Makefile.am | 38 ++++----- docs/README.md | 84 +++++++++++++------- docs/README.md.tmpl | 156 +++++++++++++++++++++++++++++++++++++ docs/deps.md.tmpl | 17 ---- docs/fedora-deps.md | 17 ---- docs/opensuse-leap-deps.md | 17 ---- docs/ubuntu-deps.md | 17 ---- 7 files changed, 226 insertions(+), 120 deletions(-) create mode 100644 docs/README.md.tmpl delete mode 100644 docs/deps.md.tmpl delete mode 100644 docs/fedora-deps.md delete mode 100644 docs/opensuse-leap-deps.md delete mode 100644 docs/ubuntu-deps.md diff --git a/docs/Makefile.am b/docs/Makefile.am index 01c67b0f2..e2ca05980 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -20,32 +20,22 @@ docdir = $(datadir)/kimchi/doc EXTRA_DIST = \ - deps.md.tmpl \ + README.md.tmpl \ $(NULL) +FEDORA_DEV_DEPS=$(shell grep "^[^\#;]" ../fedora-dev-deps.list) +FEDORA_RUNTIME_DEPS=$(shell grep "^[^\#;]" ../fedora-runtime-deps.list) +UBUNTU_DEV_DEPS=$(shell grep "^[^\#;]" ../ubuntu-dev-deps.list) +UBUNTU_RUNTIME_DEPS=$(shell grep "^[^\#;]" ../ubuntu-runtime-deps.list) +OPENSUSE_DEV_DEPS=$(shell grep "^[^\#;]" ../opensuse-leap-dev-deps.list) +OPENSUSE_RUNTIME_DEPS=$(shell grep "^[^\#;]" ../opensuse-leap-runtime-deps.list) + all: - @for os_distro in ubuntu fedora opensuse-leap; do \ - case $$os_distro in \ - ubuntu) \ - PKG_MGNT_TOOL="apt install -y"; \ - ;; \ - fedora) \ - PKG_MGNT_TOOL="dnf install -y"; \ - ;; \ - opensuse-leap) \ - PKG_MGNT_TOOL="zypper install -y"; \ - ;; \ - *) \ - PKG_MGNT_TOOL="error"; \ - ;; \ - esac; \ - echo $${PKG_MGNT_TOOL}; \ - DEV_DEPS=`grep "^[^#;]" ../$${os_distro}-dev-deps.list` ;\ - RUNTIME_DEPS=`grep "^[^#;]" ../$${os_distro}-runtime-deps.list` ;\ - sed -e "s|[@]DISTRO[@]|$${os_distro^^}|g" \ - -e "s|[@]PKG_MGNT_TOOL[@]|$${PKG_MGNT_TOOL}|g" \ - -e "s|[@]DEV_DEPS[@]|`echo $${DEV_DEPS}`|g" \ - -e "s|[@]RUNTIME_DEPS[@]|`echo $${RUNTIME_DEPS}`|g" deps.md.tmpl > $${os_distro}-deps.md ;\ - done + sed -e "s|[@]FEDORA_DEV_DEPS[@]|$(FEDORA_DEV_DEPS)|g" \ + -e "s|[@]FEDORA_RUNTIME_DEPS[@]|$(FEDORA_RUNTIME_DEPS)|g" \ + -e "s|[@]UBUNTU_DEV_DEPS[@]|`echo $(UBUNTU_DEV_DEPS)`|g" \ + -e "s|[@]UBUNTU_RUNTIME_DEPS[@]|`echo $(UBUNTU_RUNTIME_DEPS)`|g" \ + -e "s|[@]OPENSUSE_DEV_DEPS[@]|`echo $(OPENSUSE_DEV_DEPS)`|g" \ + -e "s|[@]OPENSUSE_RUNTIME_DEPS[@]|`echo $(OPENSUSE_RUNTIME_DEPS)`|g" README.md.tmpl > README.md ; dist_doc_DATA = $(wildcard *.md) $(wildcard *.png) $(NULL) diff --git a/docs/README.md b/docs/README.md index d77843f78..557be0693 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,8 +12,7 @@ * [Usage](#usage) * [Contributing to Kimchi Project](#contributing-to-kimchi-project) -What is Kimchi? -=============== +# What is Kimchi? Kimchi is an HTML5 based management tool for KVM. It is designed to make it as easy as possible to get started with KVM and create your first guest. @@ -23,49 +22,80 @@ Kimchi runs as a [Wok](https://github.com/kimchi-project/wok/wiki) plugin. Kimchi manages KVM guests through libvirt. The management interface is accessed over the web using a browser that supports HTML5. -Getting Started -=============== +# Getting Started The latest packages available can be found at https://github.com/kimchi-project/kimchi/releases/latest If you prefer to install Kimchi from source code, follow the steps below! -Install Dependencies --------------------- +## Install Dependencies + First of all, make sure to [Wok](https://github.com/kimchi-project/wok/#getting-started) installed in your system. To add Kimchi plugin, please make sure to have all the dependencies installed before starting up the wokd service. -* [RHEL/Fedora systems](/docs/fedora-deps.md) -* [Debian/Ubuntu systems](/docs/ubuntu-deps.md) -* [openSUSE systems](/docs/opensuse-leap-deps.md) +### Fedora + +**Development Dependencies** + + sudo -H pip3 install -r requirements-dev.txt + sudo dnf install -y gcc make autoconf automake git python3-pip python3-requests python3-mock gettext-devel rpm-build libxslt gcc-c++ python3-devel python3-pep8 python3-pyflakes rpmlint python3-pyyaml + +**Runtime Dependencies** + + sudo -H pip3 install -r requirements-FEDORA.txt + sudo dnf install -y python3-configobj python3-lxml python3-magic python3-paramiko python3-ldap spice-html5 novnc qemu-kvm python3-libvirt python3-pyparted python3-ethtool python3-pillow python3-cherrypy python3-pam python3-libguestfs libvirt libvirt-daemon-config-network iscsi-initiator-utils libguestfs-tools sos nfs-utils + +## Ubuntu + +**Development Dependencies** + + sudo -H pip3 install -r requirements-dev.txt + sudo apt install -y gcc make autoconf automake git python3-pip python3-requests python3-mock gettext pkgconf xsltproc python3-dev pep8 pyflakes python3-yaml libnl-route-3-dev + +**Runtime Dependencies** + + # Install libnl-route-3-dev in order to install ethtool using pip + sudo apt install libnl-route-3-dev + + sudo -H pip3 install -r requirements-UBUNTU.txt + sudo apt install -y python3-configobj python3-lxml python3-magic python3-paramiko python3-ldap spice-html5 novnc qemu-kvm python3-libvirt python3-parted python3-guestfs python3-pil python3-cherrypy3 python3-pam libvirt0 libvirt-daemon-system libvirt-clients nfs-common sosreport open-iscsi libguestfs-tools libnl-route-3-dev + +## openSUSE LEAP + +**Development Dependencies** + + sudo -H pip3 install -r requirements-dev.txt + sudo zypper install -y gcc make autoconf automake git python3-pip python3-requests python3-mock gettext-tools rpm-build libxslt-tools gcc-c++ python3-devel python3-pep8 python3-pyflakes rpmlint python3-PyYAML python3-distro + +**Runtime Dependencies** + + sudo -H pip3 install -r requirements-OPENSUSE-LEAP.txt + sudo zypper install -y python3-configobj python3-lxml python3-magic python3-paramiko python3-ldap spice-html5 novnc qemu-kvm python3-libvirt-python python-parted python3-ethtool python3-Pillow python3-CherryPy python3-python-pam python3-ipaddr python3-libguestfs libvirt libvirt-daemon-config-network open-iscsi guestfs-tools nfs-client -Build and Install ------------------ +## Build and Install - For openSUSE: - $ ./autogen.sh --with-spice-html5 + # For openSUSE: + ./autogen.sh --with-spice-html5 - Otherwise: - $ ./autogen.sh --system + # Otherwise: + ./autogen.sh --system - $ make + make # Optional if running from the source tree - $ sudo make install + sudo make install -Testing -------- +## Testing - $ make check-local - $ sudo make check + make check-local + sudo make check After all tests are executed, a summary will be displayed containing any errors/failures which might have occurred. -Usage ------ +## Usage Connect your browser to https://localhost:8001. You should see a screen like: @@ -98,8 +128,7 @@ To create a template, you need an ISO or image file on your host or use a remote If you are willing to use your own ISO, please copy it to out of box storage pool (default path is: /var/lib/kimchi/isos). -Troubleshooting ---------------- +## Troubleshooting #### Server access Please, check [Wok configuration](https://github.com/kimchi-project/wok/#troubleshooting) @@ -116,13 +145,12 @@ Please, check the NFS export path permission is configured like below: 2. Set libvirt user and kvm group for export path, in order to make sure all mapped user can get into the mount point. -Contributing to Kimchi Project -============================== +# Contributing to Kimchi Project There are a lof of ways to contribute to the Kimchi Project: * Issues can be reported at [Github](https://github.com/kimchi-project/kimchi/issues) * Patches are always welcome! Please, follow [these instructions](https://github.com/kimchi-project/kimchi/wiki/How-to-Contribute) - on how to send patches to the mailing list (kimchi-devel@ovirt.org). + on how to send patches to the mailing list (kimchi-devel@ovirt.org) or submit a pull request. Find more information about Wok Project at https://github.com/kimchi-project/kimchi/wiki diff --git a/docs/README.md.tmpl b/docs/README.md.tmpl new file mode 100644 index 000000000..034e434a2 --- /dev/null +++ b/docs/README.md.tmpl @@ -0,0 +1,156 @@ +* [What is Kimchi?](#what-is-kimchi) +* [Browser Support](https://github.com/kimchi-project/wok/#browser-support) + * [Desktop Browser Support](https://github.com/kimchi-project/wok/#desktop-browser-support) + * [Mobile Browser Support](https://github.com/kimchi-project/wok/#mobile-browser-support) +* [Linux Support](https://github.com/kimchi-project/wok/#linux-support) +* [Getting started](#getting-started) + * [Install Dependencies](#install-dependencies) + * [Build and Install](#build-and-install) + * [Starting up Wok](https://github.com/kimchi-project/wok/#starting-up-wok) + * [Troubleshooting](#troubleshooting) + * [Testing](#testing) + * [Usage](#usage) +* [Contributing to Kimchi Project](#contributing-to-kimchi-project) + +# What is Kimchi? + +Kimchi is an HTML5 based management tool for KVM. It is designed to make it as +easy as possible to get started with KVM and create your first guest. + +Kimchi runs as a [Wok](https://github.com/kimchi-project/wok/wiki) plugin. + +Kimchi manages KVM guests through libvirt. The management interface is accessed +over the web using a browser that supports HTML5. + +# Getting Started + +The latest packages available can be found at https://github.com/kimchi-project/kimchi/releases/latest + +If you prefer to install Kimchi from source code, follow the steps below! + +## Install Dependencies + +First of all, make sure to [Wok](https://github.com/kimchi-project/wok/#getting-started) +installed in your system. +To add Kimchi plugin, please make sure to have all the dependencies installed +before starting up the wokd service. + +### Fedora + +**Development Dependencies** + + sudo -H pip3 install -r requirements-dev.txt + sudo dnf install -y @FEDORA_DEV_DEPS@ + +**Runtime Dependencies** + + sudo -H pip3 install -r requirements-FEDORA.txt + sudo dnf install -y @FEDORA_RUNTIME_DEPS@ + +## Ubuntu + +**Development Dependencies** + + sudo -H pip3 install -r requirements-dev.txt + sudo apt install -y @UBUNTU_DEV_DEPS@ + +**Runtime Dependencies** + + # Install libnl-route-3-dev in order to install ethtool using pip + sudo apt install libnl-route-3-dev + + sudo -H pip3 install -r requirements-UBUNTU.txt + sudo apt install -y @UBUNTU_RUNTIME_DEPS@ + +## openSUSE LEAP + +**Development Dependencies** + + sudo -H pip3 install -r requirements-dev.txt + sudo zypper install -y @OPENSUSE_DEV_DEPS@ + +**Runtime Dependencies** + + sudo -H pip3 install -r requirements-OPENSUSE-LEAP.txt + sudo zypper install -y @OPENSUSE_RUNTIME_DEPS@ + +## Build and Install + + # For openSUSE: + ./autogen.sh --with-spice-html5 + + # Otherwise: + ./autogen.sh --system + + make + + # Optional if running from the source tree + sudo make install + +## Testing + + make check-local + sudo make check + +After all tests are executed, a summary will be displayed containing any +errors/failures which might have occurred. + +## Usage + +Connect your browser to https://localhost:8001. You should see a screen like: + +![Wok Login Screen](/docs/wok-login.png) + +By default, wok uses PAM to authenticate users so you can log in with the same username +and password that you would use to log in to the machine itself. Once logged in +you will see a screen like: + +![Kimchi Guest View](/docs/kimchi-guests.png) + +This shows you the list of running guests including a live screenshot of +the guest session. You can use the action buttons to shutdown the guests +or connect to the display in a new window. + +To create a new guest, click on the "+" button in the upper right corner. +In Kimchi, all guest creation is done through templates. + +You can view or modify templates by clicking on the Templates link in the +top navigation bar. + +The template screen looks like: + +![Kimchi Template View](/docs/kimchi-templates.png) + +From this view, you can change the parameters of a template or create a +new template using the "+" button in the upper right corner. + +To create a template, you need an ISO or image file on your host or use a remote one. +If you are willing to use your own ISO, please copy it to out of box storage +pool (default path is: /var/lib/kimchi/isos). + +## Troubleshooting + +#### Server access +Please, check [Wok configuration](https://github.com/kimchi-project/wok/#troubleshooting) +if you are getting problems to access Wok server. + +#### NFS storage pool +Please, check the NFS export path permission is configured like below: + +1. Export path need to be squashed as kvm gid and libvirt uid: + /my_export_path *(all_squash,anongid=, anonuid=,rw,sync) + + So that root user can create volume with right user/group. + +2. Set libvirt user and kvm group for export path, in order to make sure all +mapped user can get into the mount point. + +# Contributing to Kimchi Project + +There are a lof of ways to contribute to the Kimchi Project: + +* Issues can be reported at [Github](https://github.com/kimchi-project/kimchi/issues) +* Patches are always welcome! Please, follow [these instructions](https://github.com/kimchi-project/kimchi/wiki/How-to-Contribute) + on how to send patches to the mailing list (kimchi-devel@ovirt.org) or submit a pull request. + +Find more information about Wok Project at https://github.com/kimchi-project/kimchi/wiki diff --git a/docs/deps.md.tmpl b/docs/deps.md.tmpl deleted file mode 100644 index be5465979..000000000 --- a/docs/deps.md.tmpl +++ /dev/null @@ -1,17 +0,0 @@ -@DISTRO@ dependencies for Kimchi -================================ - -* [Build Dependencies](#development-dependencies) -* [Runtime Dependencies](#runtime-dependencies) - -Development Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-dev.txt - $ sudo @PKG_MGNT_TOOL@ @DEV_DEPS@ - -Runtime Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-@DISTRO@.txt - $ sudo @PKG_MGNT_TOOL@ @RUNTIME_DEPS@ diff --git a/docs/fedora-deps.md b/docs/fedora-deps.md deleted file mode 100644 index cb6f937f1..000000000 --- a/docs/fedora-deps.md +++ /dev/null @@ -1,17 +0,0 @@ -FEDORA dependencies for Kimchi -================================ - -* [Build Dependencies](#development-dependencies) -* [Runtime Dependencies](#runtime-dependencies) - -Development Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-dev.txt - $ sudo dnf install -y gcc make autoconf automake git python3-pip python3-requests python3-mock gettext-devel rpm-build libxslt gcc-c++ python3-devel python3-pep8 python3-pyflakes rpmlint python3-pyyaml - -Runtime Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-FEDORA.txt - $ sudo dnf install -y python3-configobj python3-lxml python3-magic python3-paramiko python3-ldap spice-html5 novnc qemu-kvm python3-libvirt python3-pyparted python3-ethtool python3-pillow python3-cherrypy python3-pam python3-libguestfs libvirt libvirt-daemon-config-network iscsi-initiator-utils libguestfs-tools sos nfs-utils diff --git a/docs/opensuse-leap-deps.md b/docs/opensuse-leap-deps.md deleted file mode 100644 index 88586ed2e..000000000 --- a/docs/opensuse-leap-deps.md +++ /dev/null @@ -1,17 +0,0 @@ -OPENSUSE-LEAP dependencies for Kimchi -================================ - -* [Build Dependencies](#development-dependencies) -* [Runtime Dependencies](#runtime-dependencies) - -Development Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-dev.txt - $ sudo zypper install -y gcc make autoconf automake git python3-pip python3-requests python3-mock gettext-tools rpm-build libxslt-tools gcc-c++ python3-devel python3-pep8 python3-pyflakes rpmlint python3-PyYAML python3-distro - -Runtime Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-OPENSUSE-LEAP.txt - $ sudo zypper install -y python3-configobj python3-lxml python3-magic python3-paramiko python3-ldap spice-html5 novnc qemu-kvm python3-libvirt-python python-parted python3-ethtool python3-Pillow python3-CherryPy python3-python-pam python3-ipaddr python3-libguestfs libvirt libvirt-daemon-config-network open-iscsi guestfs-tools nfs-client diff --git a/docs/ubuntu-deps.md b/docs/ubuntu-deps.md deleted file mode 100644 index b2a3191ba..000000000 --- a/docs/ubuntu-deps.md +++ /dev/null @@ -1,17 +0,0 @@ -UBUNTU dependencies for Kimchi -================================ - -* [Build Dependencies](#development-dependencies) -* [Runtime Dependencies](#runtime-dependencies) - -Development Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-dev.txt - $ sudo apt install -y gcc make autoconf automake git python3-pip python3-requests python3-mock gettext pkgconf xsltproc python3-dev pep8 pyflakes python3-yaml libnl-route-3-dev - -Runtime Dependencies --------------------- - - $ sudo -H pip3 install -r requirements-UBUNTU.txt - $ sudo apt install -y python3-configobj python3-lxml python3-magic python3-paramiko python3-ldap spice-html5 novnc qemu-kvm python3-libvirt python3-parted python3-guestfs python3-pil python3-cherrypy3 python3-pam libvirt0 libvirt-daemon-system libvirt-clients nfs-common sosreport open-iscsi libguestfs-tools libnl-route-3-dev