From 9ab94f38ad8ead2ddd01a3821dd456780e4e1c7d Mon Sep 17 00:00:00 2001 From: Timothée Ravier Date: Jan 12 2022 14:56:36 +0000 Subject: [PATCH 1/4] build & preview: Update with latest version from template --- diff --git a/build.sh b/build.sh index f4ecfe4..ed6fd2f 100755 --- a/build.sh +++ b/build.sh @@ -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 @@ elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then 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 "" diff --git a/preview.sh b/preview.sh index cbbccef..4270107 100755 --- a/preview.sh +++ b/preview.sh @@ -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 From a1b12896f9fab6993639427d190887d88b9c7c3d Mon Sep 17 00:00:00 2001 From: Timothée Ravier Date: Jan 12 2022 14:57:19 +0000 Subject: [PATCH 2/4] *.yml: Minor styling fixes --- diff --git a/docs/antora.yml b/docs/antora.yml index aec3236..e47d647 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -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. diff --git a/site.yml b/site.yml index 4a460e2..6fba1d3 100644 --- a/site.yml +++ b/site.yml @@ -1,4 +1,4 @@ -site: +site: title: Local Preview - Fedora server informations start_page: fedora-server::index.adoc content: @@ -14,11 +14,11 @@ ui: 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 diff --git a/wg/antora.yml b/wg/antora.yml index 843d5de..89e129d 100644 --- a/wg/antora.yml +++ b/wg/antora.yml @@ -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. From 1e611eb843329fdf68730a2952121865e3a10aa4 Mon Sep 17 00:00:00 2001 From: Timothée Ravier Date: Jan 12 2022 15:03:06 +0000 Subject: [PATCH 3/4] End of line whitespace cleanup --- diff --git a/docs/modules/ROOT/pages/virtualization-install.adoc b/docs/modules/ROOT/pages/virtualization-install.adoc index eef727e..61d0bac 100644 --- a/docs/modules/ROOT/pages/virtualization-install.adoc +++ b/docs/modules/ROOT/pages/virtualization-install.adoc @@ -6,7 +6,7 @@ Fredrik Arneving; Peter Boy; Jan Kuparinen **** 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 @@ QEMU / KVM require hardware virtualization support. The first thing to do is to ---- […]# 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 @@ https://example.com:9090 ---- 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 @@ Some administrators may prefer the command line for easy scripting. Adjust size […]# 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 @@ Modify libvirt default 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 @@ dns=dnsmasq 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 ---- diff --git a/wg/modules/ROOT/pages/docs/product-requirements-document.adoc b/wg/modules/ROOT/pages/docs/product-requirements-document.adoc index b2c08e0..adf4221 100644 --- a/wg/modules/ROOT/pages/docs/product-requirements-document.adoc +++ b/wg/modules/ROOT/pages/docs/product-requirements-document.adoc @@ -9,7 +9,7 @@ This document provides an overview of what Fedora Server Edition is, the goals a == 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 is a real-world incarnation of the https://docs.fedoraproject.org/ 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 @@ The server operating system market is mature and yet, constantly evolving. The t 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 @@ Fedora Server has so many genuine advantages that it is hard to list them all. T == 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 @@ Fedora Server Edition offers a highly flexible and adoptable multi-purpose serve * 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 @@ Aside from the adoption and development of the Fedora Server platform, we have a === 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,7 +78,7 @@ The Fedora Server will need to address the following use-cases: === 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" @@ -144,15 +144,15 @@ Supported installation methods: * 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) From 48528e9668036bd7248d6c5e7e3f2898b0eb75f8 Mon Sep 17 00:00:00 2001 From: Timothée Ravier Date: Jan 12 2022 15:03:36 +0000 Subject: [PATCH 4/4] Fix "section title out of sequence: expected level" warnings Fixes: ``` [14:58:39.162] WARN (asciidoctor): section title out of sequence: expected level 2, got level 3 file: /antora/docs/modules/ROOT/pages/virtualization-install.adoc:134 source: /antora (refname: main , start path: docs) [14:58:39.274] WARN (asciidoctor): section title out of sequence: expected level 1, got level 2 file: /antora/wg/modules/ROOT/pages/wg-communicating.adoc:17 source: /antora (refname: main , start path: wg) [14:58:39.322] WARN (asciidoctor): section title out of sequence: expected level 3, got level 4 file: /antora/wg/modules/ROOT/pages/docs/product-requirements-document.adoc:83 source: /antora (refname: main , start path: wg) [14:58:39.323] WARN (asciidoctor): section title out of sequence: expected level 3, got level 4 file: /antora/wg/modules/ROOT/pages/docs/product-requirements-document.adoc:89 source: /antora (refname: main , start path: wg) [14:58:39.326] WARN (asciidoctor): section title out of sequence: expected level 3, got level 4 file: /antora/wg/modules/ROOT/pages/docs/product-requirements-document.adoc:95 source: /antora (refname: main , start path: wg) [14:58:39.327] WARN (asciidoctor): section title out of sequence: expected level 3, got level 4 file: /antora/wg/modules/ROOT/pages/docs/product-requirements-document.adoc:102 source: /antora (refname: main , start path: wg) ``` --- diff --git a/docs/modules/ROOT/pages/virtualization-install.adoc b/docs/modules/ROOT/pages/virtualization-install.adoc index 61d0bac..e6bf6d5 100644 --- a/docs/modules/ROOT/pages/virtualization-install.adoc +++ b/docs/modules/ROOT/pages/virtualization-install.adoc @@ -131,7 +131,7 @@ Local DNS systemd-resolved introduced with Fedora 33 fails to work with libvirt 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] diff --git a/wg/modules/ROOT/pages/docs/product-requirements-document.adoc b/wg/modules/ROOT/pages/docs/product-requirements-document.adoc index adf4221..d2e9057 100644 --- a/wg/modules/ROOT/pages/docs/product-requirements-document.adoc +++ b/wg/modules/ROOT/pages/docs/product-requirements-document.adoc @@ -80,26 +80,26 @@ The Fedora Server will need to address the following use-cases: 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 diff --git a/wg/modules/ROOT/pages/wg-communicating.adoc b/wg/modules/ROOT/pages/wg-communicating.adoc index 0ff0e22..1a35055 100644 --- a/wg/modules/ROOT/pages/wg-communicating.adoc +++ b/wg/modules/ROOT/pages/wg-communicating.adoc @@ -14,7 +14,7 @@ The Fedora Server Edition Working Group uses various resources * 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