diff --git a/docs/Agent/installation/Ansible_based_installation.md b/docs/Agent/installation/Ansible_based_installation.md deleted file mode 100644 index e71ed95fe2..0000000000 --- a/docs/Agent/installation/Ansible_based_installation.md +++ /dev/null @@ -1 +0,0 @@ -# Ansible based installation diff --git a/docs/Agent/installation/ansible_based_installation.md b/docs/Agent/installation/ansible_based_installation.md new file mode 100644 index 0000000000..545ecbd990 --- /dev/null +++ b/docs/Agent/installation/ansible_based_installation.md @@ -0,0 +1,37 @@ +# Ansible based installation + +In the following: we describe how to install Pbench Agent using an ANSIBLE playbook. + +:::{note} +The same Pbench Agent version must be installed on all the test systems that participate in a benchmark run, there is no support for mixed installations. +::: + +## Setup + +1. Make sure that you have the ANSIBLE package installed. + +2. Install the `pbench.agent` ANSIBLE collection from Ansible Galaxy. + + ```console + ansible-galaxy collection install pbench.agent + ``` + +3. Tell ansible where to find these roles. + + ```console + export ANSIBLE_ROLES_PATH=$HOME/.ansible/collections/ansible_collections/pbench/agent/roles:$ANSIBLE_ROLES_PATH + ``` + +4. Create an inventory file (`~/.config/Inventory/myhosts.inv`) naming the hosts on which you wish to install Pbench Agent and the location of the config file. Example [inventory file](assets/myhosts.inv). + +:::{note} +if you're planning to push performance data to a 0.69 Pbench Server, you need to specify the server's private RSA key. Example [inventory file](assets/0.69_myhosts.inv). +::: + +5. Use the [example playbook](https://github.com/distributed-system-analysis/pbench/blob/main/agent/ansible/playbooks/pbench_agent_install.yml) or reference it to customize your own. + +6. Run the playbook. + + ```console + ansible-playbook -i ~/.config/Inventory/myhosts.inv pbench_agent_install.yml + ``` diff --git a/docs/Agent/installation/assets/0.69_myhosts.inv b/docs/Agent/installation/assets/0.69_myhosts.inv new file mode 100644 index 0000000000..b3e1376e9a --- /dev/null +++ b/docs/Agent/installation/assets/0.69_myhosts.inv @@ -0,0 +1,11 @@ +[servers] + + + + +[servers:vars] +# where to get the key +pbench_key_url = + +# where to get the config file +pbench_config_url = diff --git a/docs/Agent/installation/assets/myhosts.inv b/docs/Agent/installation/assets/myhosts.inv new file mode 100644 index 0000000000..89c6c80f60 --- /dev/null +++ b/docs/Agent/installation/assets/myhosts.inv @@ -0,0 +1,8 @@ +[servers] + + + + +[servers:vars] +# where to get the config file +pbench_config_url = diff --git a/docs/Agent/installation/index.rst b/docs/Agent/installation/index.rst index 6941c4e8d1..c0067749eb 100644 --- a/docs/Agent/installation/index.rst +++ b/docs/Agent/installation/index.rst @@ -8,5 +8,5 @@ Choose any one of the following approaches to setup `Pbench Agent` pbench-containers rpm_based_installation - Ansible_based_installation + ansible_based_installation diff --git a/docs/Agent/installation/pbench-containers.md b/docs/Agent/installation/pbench-containers.md index 93033f4fd7..df9625c569 100644 --- a/docs/Agent/installation/pbench-containers.md +++ b/docs/Agent/installation/pbench-containers.md @@ -1,2 +1,23 @@ -# Pbench containers - \ No newline at end of file +# Pbench Agent Container + +Pbench Agent is available as container images on [Quay.io](https://quay.io/organization/pbench). This makes Pbench Agent a distro-independent solution and it could also be used in any containerized ecosystem. + +**Want to build container images from sources?** +Follow [README](https://github.com/distributed-system-analysis/pbench/blob/main/agent/containers/images/README.md) + +Running Pbench Agent container is as simple as +```console +podman run quay.io/pbench/pbench-agent-all-centos-8 +``` +Depending on the use cases one has to run these containers with privileged mode, host network, pid, ipc, mount required volumes, etc. + +Example: +```console +podman run --name pbench --rm -ti --privileged --ipc=host --net=host --pid=host -e HOST=/host -e NAME=pbench -e IMAGE=quay.io/pbench/pbench-agent-all-centos-8 -v /run:/run -v /var/log:/var/log -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -v /:/host quay.io/pbench/pbench-agent-all-centos-8 +``` + +:::{note} +The volumes and config shown in the command snippet above may vary depending on users needs. +::: + +Possibilities are endless, please give it a try . diff --git a/docs/Agent/installation/rpm_based_installation.md b/docs/Agent/installation/rpm_based_installation.md index 0454b7723c..89f7bd27af 100644 --- a/docs/Agent/installation/rpm_based_installation.md +++ b/docs/Agent/installation/rpm_based_installation.md @@ -1 +1,43 @@ # RPM based installation + +The Pbench Agent requires the installation of some generic bits, but it also +requires some localization. It needs to know where to send the results for +storage and analysis, and it needs to be able to authenticate to the results +server. + +The generic bits are packaged as an RPM, available from +[COPR](https://copr.fedorainfracloud.org/coprs/ndokos). +Pbench Agent is built for all major releases of +Fedora, RHEL, CentOS and openSUSE. + +In the following, we describe how to install Pbench Agent using an RPM. + +## Setup + +1. Enable required repos. + + ```console + dnf copr enable ndokos/pbench-0.72 + dnf copr enable ndokos/pbench + ``` + + :::{note} + - We release Pbench Agent RPMs under the `ndokos` COPR account with repos following the pattern `pbench-`. + - There are some RPMs that are shared between versions (e.g. pbench-sysstat). We maintain those in [ndokos/pbench](https://copr.fedorainfracloud.org/coprs/ndokos/pbench) repo. + - On a RHEL-based system enable the subscription manager and enable the `EPEL` repo. + ::: + +2. Install Pbench Agent package + + ```console + dnf install pbench-agent + ``` + +3. Restart terminal/shell session so that all environment varibales and PATH variables are updated + + or + + ```console + source /etc/profile.d/pbench-agent.sh + ``` + diff --git a/docs/Agent/user-guide/index.rst b/docs/Agent/user-guide/index.rst index 9f9a669fb4..a76aecadd8 100644 --- a/docs/Agent/user-guide/index.rst +++ b/docs/Agent/user-guide/index.rst @@ -6,4 +6,5 @@ User Guide getting_started UserGuide - man_page \ No newline at end of file + man_page + guides/end-to-end-workflow \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 079b117f0f..46d77f6faa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,15 @@ Pbench website is hosted on gh-pages and readthedocs pages(`/docs`) are also hos ## Readthedocs setup -`$ pip3 install -r requirement.txt` -`$ make clean` -`$ make html` -> **Note:** Above command will build your readthedocs page in `_build/html` dir. +```console +$ pip3 install -r requirements.txt +$ make clean +$ make html +``` + +> **Note:** Above command will build your static readthedocs page/website in `_build/html` dir. + +## Some important links + +- [online markdown editor](https://pandao.github.io/editor.md/en.html) +- [myst-parser](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) is a plugin used to build our markdown documentation. diff --git a/docs/conf.py b/docs/conf.py index a33b1d8a0f..a1471a380e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,6 +43,7 @@ "sphinx.ext.autosectionlabel", "sphinx_design", "myst_parser", + "sphinx_copybutton", ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/requirements.txt b/docs/requirements.txt index 1c2b2e9cf0..527bf097b9 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,5 @@ -sphinx-design +myst-parser +sphinx-copybutton sphinx-rtd-theme -myst-parser \ No newline at end of file +sphinx-design +