kelvin/warewulf
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(docs): New documentation

Browse Source 
Convert docs to mkdocs, move back into repo, publish to repo
This commit is contained in:
Brian Clemens
2022-09-15 21:00:17 +09:00
committed by GitHub
parent 8c0710e412
commit 04ee8cc967
34 changed files with 2482 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
userdocs/contributing/contributing.rst Normal file
View File

@@ -0,0 +1,110 @@
============
Contributing
============
Warewulf is an open source project, meaning we have the challenge of limited resources. We are grateful for any support that you can offer. Helping other users, raising issues, helping write documentation, or contributing code are all ways to help!
Join the community
==================
This is a huge endeavor, and your help would be greatly appreciated! Post to online communities about Warewulf, and request that your distribution vendor, service provider, and system administrators include Warewulf for you!
Warewulf on Slack
-----------------
Many of our users come to Slack for quick help with an issue. You can find us at `HPCng <https://join.slack.com/t/hpcng/shared_invite/zt-k9atb2dj-rnlPjSh5Os3Ks6vlDEOyAA>`_.
Raise an Issue
==============
For general bugs/issues, you can open an issue `at the GitHub repo <https://github.com/hpcng/warewulf/issues/new>`_. However, if you find a security related issue/problem, please email HPCng directly at `security@hpcng.org <mailto:security@hpcng.org>`_. More information about the HPCng security policies and procedures can be found `here <https://hpcng.org/security-policy>`_.
Contribute to the code
======================
We use the traditional `GitHub Flow <https://guides.github.com/introduction/flow>`_ to develop. This means that you fork the main repo, create a new branch to make changes, and submit a pull request (PR) to the master branch.
Check out our official `CONTRIBUTING.md <https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md>`_ document, which also includes a `code of conduct <https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md#code-of-conduct>`_.
Step 1. Fork the repo
---------------------
To contribute to Warewulf, you should obtain a GitHub account and fork the `Warewulf <https://github.com/hpcng/warewulf>`_ repository. Once forked, clone your fork of the repo to your computer. (Obviously, you should replace ``your-username`` with your GitHub username.)
.. code-block:: bash
git clone https://github.com/your-username/warewulf.git
cd warewulf
Step 2. Checkout a new branch
-----------------------------
`Branches <https://guides.github.com/introduction/flow>`_` are a way of
isolating your features from the main branch. Given that we’ve just cloned the
repo, we will probably want to make a new branch from master in which to work on
our new feature. Lets call that branch ``new-feature``:
.. code-block:: bash
git checkout master
git checkout -b new-feature
.. note::
You can always check which branch you are in by running ``git branch``.
Step 3. Make your changes
-------------------------
On your new branch, go nuts! Make changes, test them, and when you are happy commit the changes to the branch:
.. code-block:: bash
git add file-changed1 file-changed2...
git commit -m "what changed?"
This commit message is important - it should describe exactly the changes that you have made. Good commit messages read like so:
.. code-block:: bash
git commit -m "changed function getConfig in functions.go to output csv to fix #2"
git commit -m "updated docs about shell to close #10"
The tags ``close #10`` and ``fix #2`` are referencing issues that are posted on the upstream repo where you will direct your pull request. When your PR is merged into the master branch, these messages will automatically close the issues, and further, they will link your commits directly to the issues they intend to fix. This will help future maintainers understand your contribution, or (hopefully not) revert the code back to a previous version if necessary.
Step 4. Push your branch to your fork
-------------------------------------
When you are done with your commits, you should push your branch to your fork (and you can also continuously push commits here as you work):
.. code-block:: bash
git push origin new-feature
Note that you should always check the status of your branches to see what has been pushed (or not):
.. code-block:: bash
git status
Step 5. Submit a Pull Request
-----------------------------
Once you have pushed your branch, then you can go to your fork (in the web GUI on GitHub) and `submit a Pull Request <https://help.github.com/articles/creating-a-pull-request>`_. Regardless of the name of your branch, your PR should be submitted to the ``main`` branch. Submitting your PR will open a conversation thread for the maintainers of Warewulf to discuss your contribution. At this time, the continuous integration that is linked with the code base will also be executed. If there is an issue, or if the maintainers suggest changes, you can continue to push commits to your branch and they will update the Pull Request.
Step 6. Keep your branch in sync
--------------------------------
Cloning the repo will create an exact copy of the Warewulf repository at that moment. As you work, your branch may become out of date as others merge changesinto the upstream master. In the event that you need to update a branch, you will need to follow the next steps:
.. code-block:: bash
# add a new remote named "upstream"
git remote add upstream https://github.com/hpcng/warewulf.git
# or another branch to be updated
git checkout master
git pull upstream master
# to update your fork
git push origin master
git checkout new-feature
git merge master

128
userdocs/contributing/development-environment-kvm.rst Normal file
View File

@@ -0,0 +1,128 @@
=============================
Development Environment (KVM)
=============================
Create CentOS 7 development virtual machine under KVM
=====================================================
.. code-block:: bash
# KVM is running on server called master1 which is not my desktop
ssh -X master1
# On master1 server
wget -P /global/downloads/centos http://mirror.mobap.edu/centos/7.8.2003/isos/x86_64/CentOS-7-x86_64-Everything-2003.iso
qemu-img create -o preallocation=metadata -f qcow2 /global/images/centos-7.qcow2 32G
# install wwdev Centos 7 development VM
sudo virt-install --virt-type kvm --name centos7-wwdev --ram 8192 \
--disk /global/images/centos-7.qcow2,format=qcow2 \
--network network=default \
--graphics vnc,listen=0.0.0.0 --noautoconsole \
--os-type=linux --os-variant=rhel7.0 \
--location=/global/downloads/centos/CentOS-7-x86_64-Everything-2003.iso
# Complete installation using virt-manager
# To start virt-manager on non-local server
ssh -X master1
sudo -E virt-manager
# Login to VM and install @development group and go language
ssh root@wwdev
# Disable selinux by modifying /etc/sysconfig/selinux
vi /etc/sysconfig/selinux
SELINUX=disabled
# disable firewall
systemctl stop firewalld
systemctl disable firewalld
Turn off default network dhcp on server master1
===============================================
.. code-block:: bash
# shutdown all VMs
sudo virsh net-destroy default
sudo virsh net-edit default
# remove dhcp lines from XML
sudo virsh net-start default
Build and install warewulf on wwdev
===================================
.. code-block:: bash
ssh wwdev
# Fedora prerequisites
sudo dnf -y install tftp-server tftp
sudo dnf -y install dhcp
sudo dnf -y install ipmitool
sudo dnf install singularity
sudo dnf install gpgme-devel
sudo dnf install libassuan.x86_64 libassuan-devel.x86_64
sudo dnf golang
sudo dnf nfs-utils
# Centos prerequisites
sudo yum -y install tftp-server tftp
sudo yum -y install dhcp
sudo yum -y install ipmitool
sudo yum install http://repo.ctrliq.com/packages/rhel7/ctrl-release.rpm
sudo yum install singularityplus
sudo yum install gpgme-devel
sudo yum install libassuan.x86_64 libassuan-devel.x86_64
sudo yum install https://packages.endpoint.com/rhel/7/os/x86_64/endpoint-repo-1.7-1.x86_64.rpm
sudo yum install golang
sudo yum install nfs-utils
# Install Warewulf and dependencies
git clone https://github.com/hpcng/warewulf.git
cd warewulf
make all
sudo make install
# Configure the controller
Edit the file /etc/warewulf/warewulf.conf and ensure that you've ser the approprite configuration parameters
# Configure system service automatically
sudo wwctl configure dhcp # Create the default dhcpd.conf file and start/enable service
sudo wwctl configure tftp # Install the base tftp/PXE boot files and start/enable service
sudo wwctl configure nfs # Configure the exports and create an fstab in the default system overlay
sudo wwctl configure ssh # Build the basic ssh keys to be included by the default system overlay
# Pull and build the VNFS container and kernel
sudo wwctl container import docker://warewulf/centos-8 centos-8 --setdefault
sudo wwctl kernel import build $(uname -r) --setdefault
# Set up the default node profile
sudo wwctl profile set default -K $(uname -r) -C centos-7
sudo wwctl profile set default --netdev eth0 -M WW_server_subnet_mask -G WW_server_ip
sudo wwctl profile list
# Add a node and build node specific overlays
sudo wwctl node add n0000.cluster --netdev eth0 -I n0000_ip --discoverable
sudo wwctl node list -a n0000
# Review Warewulf overlays
sudo wwctl overlay list -l
sudo wwctl overlay list -ls
sudo wwctl overlay edit default /etc/hello_world.ww
sudo wwctl overlay build -a
# Start the Warewulf daemon
sudo wwctl ready
sudo wwctl server start
sudo wwctl server status
Boot your node and watch the bash and the output of the Warewulfd process

147
userdocs/contributing/development-environment-vbox.rst Normal file
View File

@@ -0,0 +1,147 @@
====================================
Development Environment (VirtualBox)
====================================
I have VirtualBox running on my desktop.
1. Create a NAT Network (a private vlan) to be used for the Warewlf Server and compute nodes inside the VirtualBox. Make sure to turnoff DHCP service within this NAT Network.
.. code-block:: console
# On the host with VirtualBox execute below. In my example using 10.0.8.0/24 as the private vlan for my experiment with Warewulf
VBoxManage natnetwork add --netname wwnatnetwork --network "10.0.8.0/24" --enable --dhcp off
2. Create a Centos 7 development Virtual machine (wwdev) to be used as the Warewulf Server. Enable two Network adapters one with a standard NAT and SSH port mapping such that you can access this VM from the host machine. Assign the second network adapter to the NAT Network created in step #1. Assign sufficient memory (e.g: 4GB) to the VM.
.. code-block:: console
# Download a Centos7 or SL7 ISO and mount it to the optical drive to boot and install OS for the wwdev VM.
# Attach Network adapter #1 of the wwdev VM to the standard NAT via VM Settings -> Network option.
# By default VirtualBox puts the Network Adapter into 10.0.2.0/24 network and assigns 10.0.2.15 IP address.
# Also add a rule to the port forwarding table under the standard NAT configuration to allow SSH
# from localhost (127.0.0.1) some high port e.g 2222 to the guest IP 10.0.2.15 port 22 such that
# you can SSH from your host/desktop to the wwdev VM.
# Next attach the second Network adapter #2 to the NAT Network and you should be able to choose
# the 'wwnatnetwork' created above in step #1 from the drop down list.
3. Build and install warewulf on wwdev
.. code-block:: console
# Login to wwdev VM and install @development group and go language
ssh localhost -p 2222 #(should prompt for a user account password on wwdev VM)
# Disable selinux by modifying /etc/sysconfig/selinux
vi /etc/sysconfig/selinux
SELINUX=disabled
# Disable firewall
systemctl stop firewalld
systemctl disable firewalld
# Centos prerequisites
sudo yum -y install tftp-server tftp
sudo yum -y install dhcp
sudo yum -y install ipmitool
sudo yum install http://repo.ctrliq.com/packages/rhel7/ctrl-release.rpm
sudo yum install singularityplus
sudo yum install gpgme-devel
sudo yum install libassuan.x86_64 libassuan-devel.x86_64
# Upgrade git to v2+
sudo yum install https://packages.endpoint.com/rhel/7/os/x86_64/endpoint-repo-1.7-1.x86_64.rpm
sudo yum install git
sudo yum install golang
sudo yum install nfs-utils
# Install Warewulf and dependencies
git clone https://github.com/hpcng/warewulf.git
cd warewulf
make all
sudo make install
# Static assign an IP to adapter #2 which is in the wwnatnetwork.
$ Edit the file /etc/sysconfig/networking-scripts/ifcfg-enp0s9 # adapter name at the end might be different for you
# Add lines like to below to assign an ip in 10.0.8.0/24 wwnatnetwork, I choose 10.0.8.4
BOOTPROTO=static
ONBOOT=yes
NAME=enp0s9
DEVICE=enp0s9
IPADDR=10.0.8.4
NETMASK=255.255.255.0
GATEWAY=10.0.8.1
# Bring the enp0s9 interface online and verify ip assignment
# Configure the Warewulf controller
$ Edit the file /etc/warewulf/warewulf.conf and ensure that you've set the approprite configuration parameters.
# My conf file looks like below:
ipaddr: 10.0.8.4
netmask: 255.255.255.0
warewulf:
port: 9873
secure: true
update interval: 60
dhcp:
enabled: true
range start: 10.0.8.150
range end: 10.0.8.200
template: default
systemd name: dhcpd
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
nfs:
systemd name: nfs-server
exports:
- /home
- /var/warewulf
# Configure system service automatically
sudo wwctl configure dhcp --persist # Create the default dhcpd.conf file and start/enable service
sudo wwctl configure tftp --persist # Install the base tftp/PXE boot files and start/enable service
sudo wwctl configure nfs --persist # Configure the exports and create an fstab in the default system overlay
sudo wwctl configure ssh --persist # Build the basic ssh keys to be included by the default system overlay
# Pull and build the VNFS container and kernel
sudo wwctl container import docker://warewulf/centos-7 centos-7 --setdefault
sudo wwctl kernel import build $(uname -r) --setdefault
# Set up the default node profile
sudo wwctl profile set default -K $(uname -r) -C centos-7
sudo wwctl profile set default --netdev eth0 -M 255.255.255.0 -G 10.0.8.4
sudo wwctl profile list
# Add a node and build node specific overlays
# IP address of my nodes start from 150 as set in the warewulf.conf file above
sudo wwctl node add n0000.cluster --netdev eth0 -I 10.0.8.150 --discoverable
sudo wwctl node list -a n0000
# Review Warewulf overlays
sudo wwctl overlay list -l
sudo wwctl overlay list -ls
sudo wwctl overlay edit default /etc/hello_world.ww
sudo wwctl overlay build -a
# Start the Warewulf daemon
sudo wwctl ready
sudo wwctl server start
sudo wwctl server status
4. Create a new guest VM instance inside the VirtualBox to be the warewulf client/compute node. Under the system configuration make sure to select the optical and network options only for the boot order. The default iPXE used by VirtualBox does not come with bzImage capability which is needed for warewulf. Download the ipxe.iso available at ipxe.org and mount the ipxe.iso to the optical drive. Enable one Network adapter for this VM and assign it to the NAT Network created in step #1 above.
.. code-block:: console
# Download ipxe.so available at http://boot.ipxe.org/ipxe.iso
# VM Settings -> System disable Floppy, Hard Disk from Boot order. Enable Optical and Network options.
# VM Settings -> Storage and mount the above download ipxe.so to the Optical Drive.
# VM Settings -> Network Enable adapter #1, attach to 'Nat Network' and choose 'wwnatnetwork' from the drop down list.
Boot your node and watch the console and the output of the Warewulfd process

11
userdocs/contributing/documentation.rst Normal file
View File

@@ -0,0 +1,11 @@
=============
Documentation
=============
We (like almost all open source software providers) have a documentation dilemma… We tend to focus on the code features and functionality before working on documentation. And there is very good reason for this: we want to share the love so nobody feels left out!
You can contribute to the documentation by `raising an issue to suggest an improvement <https://github.com/hpcng/warewulf-web/issues/new>`_ or by sending a `pull request <https://github.com/hpcng/warewulf-web/compare>`_ on `our repository <https://github.com/hpcng/warewulf-web>`_.
The current documentation is generated with `Docusaurus <https://v2.docusaurus.io/docs/>`_.
For more information on using Git and GitHub to create a pull request suggesting additions and edits to the docs, see the `section on contributing to the code <contributing>`_. The procedure is identical for contributions to the documentation and the code base.