PR#71: Minor cleanups - fedora-server

fedora-server

#71 Minor cleanups

Merged 2 years ago by copperi. Opened 2 years ago by siosm.

Unknown source cleanups into main

Fix "section title out of sequence: expected level" warnings

Timothée Ravier • 2 years ago

48528e9

End of line whitespace cleanup

Timothée Ravier • 2 years ago

1e611eb

*.yml: Minor styling fixes

Timothée Ravier • 2 years ago

a1b1289

build & preview: Update with latest version from template

Timothée Ravier • 2 years ago

9ab94f3

build.sh

file modified

+13 -8

		`@@ -3,25 +3,30 @@`
		`image="docker.io/antora/antora"`
		`cmd="--html-url-extension-style=indexify site.yml"`

		`- if [ "$(uname)" = "Darwin" ]; then`
		`+ if [ "$(uname)" == "Darwin" ]; then`
		`# Running on macOS.`
		`# Let's assume that the user has the Docker CE installed`
		`# which doesn't require a root password.`
		`echo ""`
		`echo "This build script is using Docker container runtime to run the build in an isolated environment."`
		`echo ""`
		`- docker run --rm -it -v "$(pwd):/antora" $image $cmd`
		`+ docker run --rm -it -v $(pwd):/antora $image $cmd`

		`- elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then`
		`+ elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then`
		`# Running on Linux.`
		`- # Check whether podman is available, else fall back to docker`
		`+ # there isn't an antora/aarch64 container, antora can be installed locally`
		`+ # Check whether podman is available, else faill back to docker`
		`# which requires root.`

		`- if [ -f /usr/bin/podman ]; then`
		`+ if [ -f /usr/local/bin/antora ]; then`
		`+ /usr/local/bin/antora $cmd`
		+ elif [[ `uname -m` == "aarch64" ]]; then
		+ echo "no antora/aarch64 container try just \`npm install -g @antora/cli @antora/site-generator-default\`"
		`+ elif [ -f /usr/bin/podman ]; then`
		`echo ""`
		`echo "This build script is using Podman to run the build in an isolated environment."`
		`echo ""`
		`- podman run --rm -it -v "$(pwd):/antora:z" $image $cmd`
		`+ podman run --rm -it -v $(pwd):/antora:z $image $cmd`

		`elif [ -f /usr/bin/docker ]; then`
		`echo ""`
		`@@ -29,13 +34,13 @@`
		`echo ""`

		`if groups \| grep -wq "docker"; then`
		`- docker run --rm -it -v "$(pwd):/antora:z" $image $cmd`
		`+ docker run --rm -it -v $(pwd):/antora:z $image $cmd`
		`else`
		`echo ""`
		`echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password."`
		`echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/."`
		`echo ""`
		`- sudo docker run --rm -it -v "$(pwd):/antora:z" $image $cmd`
		`+ sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd`
		`fi`
		`else`
		`echo ""`

docs/antora.yml

file modified

+12 -6

		`@@ -1,14 +1,20 @@`
		`# Name will be mostly visible in the URL. Treat it as an identifier.`
		`- # Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page)`
		`- name: fedora-server # <---- PLEASE MODIFY`
		`+ # Tip: If you want to use the local preview scripts that come with this`
		`+ # repository, please change this value in the site.yml file as well. (under`
		`+ # site/start_page)`
		`+ name: fedora-server`

		`- # Title will be visible on the page.`
		`- title: Fedora Server Documentation # <---- PLEASE MODIFY`
		`+ # Title will be visible on the page.`
		`+ title: Fedora Server Documentation`

		`- # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.`
		`+ # If you don't plan to have multiple versions of the docs (for example, to`
		`+ # document multiple versions of some software), you can ignore this field.`
		`+ # Otherwise, change "master" to a specific version.`
		`version: master`

		`- # We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise.`
		`+ # We encourage you to name the index page as "index.adoc". If you absolutely`
		`+ # have to use a different name, please reflect it here. You can ignore this`
		`+ # field otherwise.`
		`start_page: ROOT:index.adoc`

		`# This lists all the menu definitions of your component.`

docs/modules/ROOT/pages/virtualization-install.adoc

file modified

+14 -14

		`@@ -6,7 +6,7 @@`
		`****`
		`Author: Peter Boy (pboy) \| Creation Date: 2021-03-31 \| Last update: N/A \| Affected Fedora Version(s): 33,34`
		`****`
		`- Qemu-kvm in combination with Libvirt management toolkit is the standard virtualization methodology in Fedora. This includes a local virtual network for protected communication between the virtual guest systems with each other and with the host.`
		`+ Qemu-kvm in combination with Libvirt management toolkit is the standard virtualization methodology in Fedora. This includes a local virtual network for protected communication between the virtual guest systems with each other and with the host.`

		`== Preparation`

		`@@ -15,9 +15,9 @@`
		`----`
		`[…]# egrep --color 'vmx\|svm' /proc/cpuinfo`
		`----`
		`- The command will return one line per cpu core if virtualization is enabled. If not, you should first check in the BIOS whether virtualization is disabled.`
		`+ The command will return one line per cpu core if virtualization is enabled. If not, you should first check in the BIOS whether virtualization is disabled.`

		`- Libvirt stores its data including the image files of the virtual hard disk(s) for the guest systems in /var/lib/libvirt. If you adhere to the default partitioning concept, the libvirt application data is stored in its own logical volume that you have to create in advance. You need to specify the size of the storage area, a unique name, and the accommodating VG (fedora_fedora in case of default partitioning). In the new logical volume, create an xfs file system and mount at /var/lib/libvirt.`
		`+ Libvirt stores its data including the image files of the virtual hard disk(s) for the guest systems in /var/lib/libvirt. If you adhere to the default partitioning concept, the libvirt application data is stored in its own logical volume that you have to create in advance. You need to specify the size of the storage area, a unique name, and the accommodating VG (fedora_fedora in case of default partitioning). In the new logical volume, create an xfs file system and mount at /var/lib/libvirt.`

		`=== Cockpit`

		`@@ -28,9 +28,9 @@`
		`----`
		`If there is no valid public certificate installed so far, a browser warning appears and you have to accept an exception for the self-signed certificate. The subsequent login can use either the root account or an unprivileged administrative user account.`

		`- In Cockpit select "Storage" in the left navigation column and then the target volume group in the device list at the top of the right column of the opening window. The center content area changes to show the selected volume group at the top and a list of existing logical volumes below it that may be empty for now.`
		`+ In Cockpit select "Storage" in the left navigation column and then the target volume group in the device list at the top of the right column of the opening window. The center content area changes to show the selected volume group at the top and a list of existing logical volumes below it that may be empty for now.`

		`- To create a logical volume select "Create logical volume" next to the 'Logical volumes' section title. In the form that opens, fill in the name of the new logical volume at the top, e.g. in this case 'libvirt'. Leave the usage field as 'File system' and adjust the size at the bottom, e.g. 500 GiB. Then create the LV.`
		`+ To create a logical volume select "Create logical volume" next to the 'Logical volumes' section title. In the form that opens, fill in the name of the new logical volume at the top, e.g. in this case 'libvirt'. Leave the usage field as 'File system' and adjust the size at the bottom, e.g. 500 GiB. Then create the LV.`

		`In the 'Logical volumes' list, a new line appears with the LV name, libvirt in this example, as part of the device part on the right side. Expand that line and select 'format' on the right side. In the form that opens, fill in the name of the new file system, e.g. in this case 'libvirt', and the mount point, /var/lib/libvirt in this case. Leave the other fields at their default values. Select 'Format' and Cockpit will handle everything else.`

		`@@ -46,7 +46,7 @@`
		`[…]# mkdir -p /var/lib/libvirt`
		`[…]# vim /etc/fstab`
		`/dev/mapper/fedora_fedora-root / xfs defaults 0 0`
		`- /dev/mapper/fedora_fedora-libvirt /var/lib/libvirt xfs defaults 0 0`
		`+ /dev/mapper/fedora_fedora-libvirt /var/lib/libvirt xfs defaults 0 0`
		`[…]# mount -a`
		`----`

		`@@ -118,25 +118,25 @@`
		`</network>`
		`----`

		`- Activate the modified configuration`
		`+ Activate the modified configuration`
		`[source,bash]`
		`----`
		`- […]# virsh net-destroy default`
		`- […]# virsh net-start default`
		`+ […]# virsh net-destroy default`
		`+ […]# virsh net-start default`
		`----`

		`== Converting the Hosts DNS Configuration`

		`- Local DNS systemd-resolved introduced with Fedora 33 fails to work with libvirt network configuration so far. As a consequence, DNS-split for forwarding internal name queries to libvirt DNS does not work. As for guest VM’s, however, their local DNS capabilities are not affected. Hence, the host cannot resolve the names of the VMs, but conversely, the VMs can resolve to each other and to the host.`
		`+ Local DNS systemd-resolved introduced with Fedora 33 fails to work with libvirt network configuration so far. As a consequence, DNS-split for forwarding internal name queries to libvirt DNS does not work. As for guest VM’s, however, their local DNS capabilities are not affected. Hence, the host cannot resolve the names of the VMs, but conversely, the VMs can resolve to each other and to the host.`

		`As far as the latter is sufficient, no adjustment and no conversion are required. With the former, systemd-resolved must be disabled and replaced by NetworkManager's dnsmasq plugin.`

		`- ==== Configuration of NetworkManager's dnsmasq plugin`
		`+ === Configuration of NetworkManager's dnsmasq plugin`

		`Activate dnsmasq plugin`
		`[source,bash]`
		`----`
		`- […]# vim /etc/NetworkManager/conf.d/00-use-dnsmasq.conf`
		`+ […]# vim /etc/NetworkManager/conf.d/00-use-dnsmasq.conf`
		`# /etc/NetworkManager/conf.d/00-use-dnsmasq.conf`
		`#`
		`# This enabled the dnsmasq plugin.`
		`@@ -146,11 +146,11 @@`
		`Define the local domain and DNS service`
		`[source,bash]`
		`----`
		`- […]# vim /etc/NetworkManager/dnsmasq.d/00-example-lan.conf`
		`+ […]# vim /etc/NetworkManager/dnsmasq.d/00-example-lan.conf`
		`# /etc/NetworkManager/dnsmasq.d/00-example-lan.conf`
		`#`
		`# This file directs dnsmasq to forward any request to resolve`
		`- # names under the .example.lan domain to 192.168.122.1, the`
		`+ # names under the .example.lan domain to 192.168.122.1, the`
		`# local libvirt DNS server.`
		`server=/example.lan/192.168.122.1`
		`----`

preview.sh

file modified

-10

		`@@ -1,15 +1,5 @@`
		`#!/bin/sh`

		`-`
		`- echo ""`
		`- echo "The preview is available at http://localhost:8080"`
		`- echo ""`
		`- echo "Spaces:"`
		`- echo " * User Documentation .. http://localhost:8080/fedora-server/ #(default)"`
		`- echo " * Working Group pages.. http://localhost:8080/server-working-group/"`
		`- echo ""`
		`- echo ""`
		`-`
		`if [ "$(uname)" = "Darwin" ]; then`
		`# Running on macOS.`
		`# Let's assume that the user has the Docker CE installed`

site.yml

file modified

+5 -5

		`@@ -1,4 +1,4 @@`
		`- site:`
		`+ site:`
		`title: Local Preview - Fedora server informations`
		`start_page: fedora-server::index.adoc`
		`content:`
		`@@ -14,11 +14,11 @@`
		`url: https://asamalik.fedorapeople.org/ui-bundle.zip`
		`snapshot: true`
		`default_layout: with_menu`
		`- output:`
		`- clean: true`
		`+ output:`
		`+ clean: true`
		`dir: ./public`
		`- destinations:`
		`- - provider: archive`
		`+ destinations:`
		`+ - provider: archive`
		`runtime:`
		`fetch: true`
		`cache_dir: ./cache`

wg/antora.yml

file modified

+12 -6

		`@@ -1,14 +1,20 @@`
		`# Name will be mostly visible in the URL. Treat it as an identifier.`
		`- # Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page)`
		`- name: server-working-group # <---- PLEASE MODIFY`
		`+ # Tip: If you want to use the local preview scripts that come with this`
		`+ # repository, please change this value in the site.yml file as well. (under`
		`+ # site/start_page)`
		`+ name: server-working-group`

		`- # Title will be visible on the page.`
		`- title: Fedora Server Working Group # <---- PLEASE MODIFY`
		`+ # Title will be visible on the page.`
		`+ title: Fedora Server Working Group`

		`- # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.`
		`+ # If you don't plan to have multiple versions of the docs (for example, to`
		`+ # document multiple versions of some software), you can ignore this field.`
		`+ # Otherwise, change "master" to a specific version.`
		`version: master`

		`- # We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise.`
		`+ # We encourage you to name the index page as "index.adoc". If you absolutely`
		`+ # have to use a different name, please reflect it here. You can ignore this`
		`+ # field otherwise.`
		`start_page: ROOT:index.adoc`

		`# This lists all the menu definitions of your component.`

wg/modules/ROOT/pages/docs/product-requirements-document.adoc

file modified

+17 -17

		`@@ -9,7 +9,7 @@`

		`== Fedora Server Vision`

		`- Fedora Server is a real-world incarnation of the https://docs.fedoraproject.org/en-US/project/[Fedora Project's vision] for organizations, individual users, and developers to develop, deploy, and maintain applications and services – freely, autonomously, and under their own control.`
		`+ Fedora Server is a real-world incarnation of the https://docs.fedoraproject.org/en-US/project/[Fedora Project's vision] for organizations, individual users, and developers to develop, deploy, and maintain applications and services – freely, autonomously, and under their own control.`

		`== Fedora Server Mission`

		`@@ -17,9 +17,9 @@`

		`Fedora Server provides a stable, flexible, and universally-adaptable base for the everyday provisioning of services and applications by organizations and individuals, based on the latest technology and is available quickly after the upstream releases.`

		`- As a developer or system integrator, you gain an eye on the server of the future.`
		`+ As a developer or system integrator, you gain an eye on the server of the future.`

		`- Fedora Server is also a platform for developers and system integrators, which provides an implementation of the latest server technology for exploring and evaluating.`
		`+ Fedora Server is also a platform for developers and system integrators, which provides an implementation of the latest server technology for exploring and evaluating.`

		`== Market Opportunity`

		`@@ -27,11 +27,11 @@`

		`Fedora Server, being a leading-edge Linux distribution, is the ideal place for developers, system administrators and DevOps specialists to keep up-to-date with these low-level technologies. Fedora Server provides the opportunity to explore these features and provide a stable place to deploy applications, both new and legacy.`

		`- Fedora Server provides a stable foundation, with balanced resource utilization, yet delivering the latest technologies giving administrators every day exposure to the latest tooling as soon as it is usable.`
		`+ Fedora Server provides a stable foundation, with balanced resource utilization, yet delivering the latest technologies giving administrators every day exposure to the latest tooling as soon as it is usable.`

		`== Why use Fedora Server?`

		`- Fedora Server has so many genuine advantages that it is hard to list them all. The nine most important ones are:`
		`+ Fedora Server has so many genuine advantages that it is hard to list them all. The nine most important ones are:`

		`* The twice-yearly, release cycle allows for the inclusion of the latest versions of system and application software almost immediately. Users and system administrators are empowered to swiftly respond to new market options and changing or expanding customer requirements.`
		`* A sophisticated release and quality assurance process enables a high level of reliability and stability, despite the fast release cycle. This achieves an excellent balance between ‘bleeding edge’ and maturity for use in mainstream deployments.`
		`@@ -45,7 +45,7 @@`

		`== Server Edition Objectives`

		`- Fedora Server Edition offers a highly flexible and adoptable multi-purpose server platform, usable at every scale.`
		`+ Fedora Server Edition offers a highly flexible and adoptable multi-purpose server platform, usable at every scale.`

		`* A platform for important infrastructure tasks and basic services (DNS, DHCP, FreeIPA, and others)`
		`* A platform for various important, dedicated server applications (file/storage server, database server, user-developed web applications, etc.)`
		`@@ -55,11 +55,11 @@`
		`* Infrastructure to allow efficiently managing many servers as a single unit. The product only commits to producing basic tools, but the infrastructure will allow more advanced tools to be created.`
		`* An operating platform capable to run any combination of forementioned services all according to very different needs of users rsp system administrators (multipurpose feature).`

		`- Fedora Server can be used as a standalone server that runs an application or service as well as a member of a cluster in a data center. As a result of strict adherence to open standards, it natively cooperates with different server technologies and implementations.`
		`+ Fedora Server can be used as a standalone server that runs an application or service as well as a member of a cluster in a data center. As a result of strict adherence to open standards, it natively cooperates with different server technologies and implementations.`

		`=== Additional Overall Objectives`

		`- Aside from the adoption and development of the Fedora Server platform, we have additional goals that are fundamental in any case:`
		`+ Aside from the adoption and development of the Fedora Server platform, we have additional goals that are fundamental in any case:`

		`* Security-minded: secure by design - extending into TPM support, disk encryption enablement`
		`* Community-driven: Intense feedback about product direction and potential improvements. This is separate from “bug reports” in that we hope to engage the audience and receive detailed feedback about use cases, desired features, developing trends in cloud management, etc. We encourage more patches and contributions that will help improve the Server Edition, and Fedora in general.`
		`@@ -68,7 +68,7 @@`

		`=== Use Cases`

		`- The Fedora Server will need to address the following use-cases:`
		`+ The Fedora Server will need to address the following use-cases:`

		`* On premise server for small and medium-sized enterprises hosting mail service, calendar, and branch specific (probably containerized) software – either single node deployment or multi-node deployment with automatic failover`
		`* Dedicated SOHO server, ‘bare metal’ rented from a remote provider and under its own full control, offering various services. Public access through VMs for security reasons.`
		`@@ -78,28 +78,28 @@`

		`=== User Profiles`

		`- We will use a set of personas to describe our target users and their respective needs. We list the typical personas by brief title and a short list of key characteristics.`
		`+ We will use a set of personas to describe our target users and their respective needs. We list the typical personas by brief title and a short list of key characteristics.`

		`- ===== System Administrator "Macgyver"`
		`+ ==== System Administrator "Macgyver"`

		`* Administrator with limited hardware and personnel resources to work with`
		`* Requires simple automation to cope with repetitive tasks`
		`* Needs to be able to do “a lot with a little”`

		`- ===== DevOps Engineer/Administrator`
		`+ ==== DevOps Engineer/Administrator`

		`* Focus is on time-to-deploy and time-to-recover as opposed to uptime`
		`* Value is achieved by delivering the latest capabilities fastest`
		`* Needs to be able to deliver quickly to PaaS, SaaS and bare-metal servers`

		`- ===== Application Developer`
		`+ ==== Application Developer`

		`* Needs a platform with API and ABI stability guarantees`
		`* Focus will be on minimizing risk when making changes`
		`* Needs latest technology in virtualization and containerization`
		`* Likes a platform similar to the workstation`

		`- ===== Decision Maker`
		`+ ==== Decision Maker`

		`* Makes purchasing decisions and directs technology choices`
		`* Interacts with upstream FOSS communities to identify potential value`
		`@@ -144,15 +144,15 @@`
		`* Manual install without a supporting infrastructure (e.g. the very first Linux server).`
		`* Existing servers should be upgradable to new releases with minimal involvement by the admin.`

		`- Users will be able to obtain these images from the Fedora Project website and mirror networks.`
		`+ Users will be able to obtain these images from the Fedora Project website and mirror networks.`

		`=== Documentation`

		`- Fedora Server Edition documentation will be made available in a dedicated section of the Fedora documentation project. For selected topics, we strive for integration into the generic Fedora documentation.`
		`+ Fedora Server Edition documentation will be made available in a dedicated section of the Fedora documentation project. For selected topics, we strive for integration into the generic Fedora documentation.`

		`== About this Document`

		`- This document resulted from a broad discussion of the Fedora Server Edition working group. Contributors include:`
		`+ This document resulted from a broad discussion of the Fedora Server Edition working group. Contributors include:`

		`* Alexander Bokovoy`
		`* Peter Boy (editor)`

wg/modules/ROOT/pages/wg-communicating.adoc

file modified

+1 -1

		`@@ -14,7 +14,7 @@`
		`* Blog: http://fedoramagazine.org/`
		`* Tickets: https://pagure.io/fedora-server`

		`- === Meetings`
		`+ == Meetings`
		* The Server working group meets twice-monthly every 1st and 3rd Wednesday at 17:00 UTC in #fedora-meeting on irc.libera.chat. Please, check your local time using e.g. `date -d '2021-11-17 17:00UTC'`
		`* Each meeting is announced in the Fedora Project Calendar: https://calendar.fedoraproject.org/server/`
		`* The agenda is announced on the server mailing list server@lists.fedoraproject.org and available from the ticket system at https://pagure.io/fedora-server/report/Meeting`