Merge branch 'main' of ssh://pagure.io/fedora-server

README.md

@@ -21,7 +21,7 @@ Note: Replace master with main on all occations on above document:
 To build and preview docs, run:
 
 ```
-$ ./build.sh && ./preview.sh
+$ ./docsbuilder.sh
 ```
 
 The result will be available at http://localhost:8080

docs/modules/ROOT/nav.adoc

@@ -19,6 +19,7 @@
 ** xref:virtualization/vm-install-cloudimg-centos9.adoc[Creating a virtual machine using a distribution's Cloud base image]
 ** xref:virtualization/vm-management-cockpit.adoc[Managing virtual machines with Cockpit]
 ** xref:virtualization/nested-virtualization.adoc[Setting up Nested Virtualization]
+** xref:virtualization/vm-install-diskimg-proxmox.adoc[Installing Fedora Server Edition as a virtual machine using Proxmox Virtual Environment]
 
 * xref:containerization/index.adoc[Containerization]
 ** xref:containerization/systemd-nspawn-setup.adoc[Setting up Systemd Nspawn Container]

docs/modules/ROOT/pages/virtualization/vm-install-diskimg-proxmox.adoc

@@ -0,0 +1,167 @@
+= Installing Fedora Server Edition as a Virtual Machine using Proxmox Virtual Environment
+Paul Maconi
+:page-authors: {author}, {author_2}
+:revnumber: F41
+:revdate: 2024-11-02
+
+:page-aliases: pages/virtualization-vm-install-fedoraserver-cockpit.adoc
+
+// Before publishing on main site, comment out
+// the warning. Comment in again when start to update.
+//[WARNING]
+//====
+//**You are in the Fedora Server documentation staging area!**
+//
+//These documents are not approved yet and may be incomplete and/or incorrect. You would probably prefer to study the https://docs.stg.fedoraproject.org/en-US/fedora-server/[published documentation].
+
+// *Status of this document*: Updated to f41.
+//====
+
+
+[abstract]
+This document outlines a method for installing Fedora Server from the qcow2 image as a virtual machine in the Proxmox Virtual Environment, henceforth simply Proxmox. VMs can be spun up very quickly after importing the disk image, saving much time and frustration. The setup used when writing this document may not match what yours, so certain details like file paths for the disk images may vary.  
+
+
+== Why Fedora Server on Proxmox
+
+Proxmox is an open source server virtualization management solution based on QEMU/KVM and LXC with a web interface for managing most aspects of the VM workflow. It is also popular with homelab enthusiasts. The Fedora Server disk image shortcuts the provisioning process by providing a pre-installed disk image that boots straight into the final setup menu. You can have a fresh Fedora Server VM provisioned in just a couple of minutes using this method.
+
+== Brief summary for experienced Proxmox users
+
+Here are the key details if you're already familiar with creating virtual machines in Proxmox.
+
+* The VM does not need installation media (ISO) mounted.
+* The VM must be in BIOS mode (SeaBIOS) with a VirtIO SCSI Single controller. Be sure to enable the Qemu Agent if you plan on using it.
+* This document omits the initial disk creation because we import the disk image later in the process.
+** `qm disk import [vm_number] [image_name.qcow2] [target_storage] --format qcow2`
+* You must attach the disk and ensure it is selected in the boot order under `options` for the VM before you try to boot the system.
+
+== Procedure
+
+Note: This document assumes that you have ssh access to a Proxmox node and that you have already downloaded the Fedora Server qcow2 disk image. It also assumes centralized storage on an NFS mount, but your storage configuration may differ if you use local LVM storage or Ceph. We provided screenshots for each step of the VM configuration process, but the overall procedure comes from the link:https://pve.proxmox.com/wiki/Migrate_to_Proxmox_VE#Import_Disk[Proxmox Wiki].
+
+=== Locate the image file and upload it to Proxmox
+
+Before we create the VM, we will need to find and upload our disk image to the Proxmox node. In the screenshot below you can see that we explored the system to determine that it is using centralized NFS storage mounted at /mnt/pve/nfs-kraken, and we made a directory at some point called osimages to contain our disk images.
+
+Once we sorted out the path, we uploaded the file via scp into the Proxmox node. `scp [image_filename] root@[node_name]:/path/to/images/[image_filename]`
+
+image::virtualization/vm-proxmox-01.png[Upload Image File]
+
+=== Verify the image is in place
+
+While not completely necessary, we logged back in to the Proxmox node and verified that the file had actually uploaded to the target directory. We'll come back to this path later when it is time to import the disk image to a VM.
+
+image::virtualization/vm-proxmox-02.png[Locate Image File]
+
+=== VM Creation: General
+
+Click on the `Create VM` button in the Proxmox UI, and the VM creation wizard should start. Select a node and give the VM a name. Note the VM ID. We will need this later. Click `Next`.
+
+image::virtualization/vm-proxmox-03.png[VM General]
+
+=== VM Creation: OS
+
+We will not need to use an ISO to install the system, so change the radio button to `Do not use any media` and click `Next`.
+
+image::virtualization/vm-proxmox-04.png[VM OS]
+
+=== VM Creation: System
+
+We get a handful of options to play with on this screen.
+
+* The `Machine` is whatever you prefer. `q35` presents hardware in the PCIe topology, while `i440fx` will give you the older PCI topology. 
+
+* The `BIOS` option needs to be `SeaBIOS` because the disk image will not boot under `UEFI`. 
+
+* The `SCSI Controller` option should be set as `VirtIO SCSI Single`. The default option `LSI 53C895A` would not boot the disk image. 
+
+* Also, remember to enable the `Qemu Agent` option if you intend to use it. You can safely enable this option if you are unsure. 
+
+Click `Next`.
+
+image::virtualization/vm-proxmox-05.png[VM System]
+
+=== VM Creation: Disks
+
+Click the little trash can to the left of the disk it pre-populates for you. We will be importing the disk image as our primary disk. Click `Next`.
+
+image::virtualization/vm-proxmox-06.png[VM Disks]
+
+=== VM Creation: CPU
+
+Set the CPU settings as you need them. The test cluster used when writing this documentation had identical processors across the cluster, so `host` was safe to use while still enabling live migration. Click `Next`.
+
+image::virtualization/vm-proxmox-07.png[VM CPU]
+
+=== VM Creation: Memory
+
+Set the memory the amount you want assigned to the VM. Click `Next`.
+
+image::virtualization/vm-proxmox-08.png[VM Memory]
+
+=== VM Creation: Network
+
+Select the network details. The test article had an Open vSwitch configured with VLAN port groups. `VirtIO (paravirtualized)` should yield the best performance. Click `Next`.
+
+image::virtualization/vm-proxmox-09.png[VM Network]
+
+=== VM Creation: Confirm
+
+The wizard should end with a summary of the hardware settings. Click `Finish` to create the VM.
+
+image::virtualization/vm-proxmox-10.png[VM Confirm]
+
+=== VM Disk Import
+
+Now that the VM itself has been built, we need to log in to the Proxmox node via the console feature or via SSH to import the disk image we uploaded earlier.
+
+* Log in to the Proxmox node
+
+* Navigate to the directory where you uploaded the disk image earlier. 
+
+** This test article has storage mounted at /mnt/pve/nfs-kraken/osimages/, but your path will be different.
+
+* Use the qm disk import command to import your disk image.
+
+** `qm disk import [vm_number] [image_name.qcow2] [target_storage] --format qcow2`
+
+*** [vm_number] is the vm number of the vm you just created in the previous steps.
+
+*** [image_name.qcow2] is the file name of your Fedora Server image that you uploaded earlier.
+
+*** [target_storage] is the storage volume where you want the disk image for the vm stored. For this test article, I told Proxmox to continue using a volume named `nfs-kraken`.
+
+*** The format may vary depending on where you are storing the VM. The test articule uses an NFS mount, and qcow2 formatted images are preferred in this usage scenario.
+
+image::virtualization/vm-proxmox-11.png[VM Disk Import Start]
+
+When the import process finishes you should get a success message like the one show in the image below. This process was done on a storage array with rotational hard disks, and it still only took a few seconds to complete.
+
+image::virtualization/vm-proxmox-12.png[VM Disk Import End]
+
+=== VM Configuration: Disk
+
+Now that the disk is part of the VM, we can go back to the hardware tab, highlight the new unused disk, and click edit. You shouldn't need to change anything and can safely just click `Add`.
+
+image::virtualization/vm-proxmox-13.png[VM Configuration: Disk]
+
+=== VM Configuration: Boot Order
+
+The final step before powering on the VM is to navigate to the VM's `Options` tab, click on `Boot Order`, and ensure that the imported disk, typically `scsi0`, is selected for boot. Note that in the following screenshot, the other boot options are disabled and `scsi0` is moved to the top of the list. 
+
+image::virtualization/vm-proxmox-14.png[VM Configuration: Boot Order]
+
+=== VM Console: First Boot
+
+Now we're ready open up the console and boot the VM for the first time. You should see the normal GRUB boot loader and kernel messages stream across the console until you are presented with the final setup menu. 
+
+image::virtualization/vm-proxmox-15.png[VM Console: First Boot]
+
+=== End Result
+
+After you complete this process the VM is running just as if you had booted off of the ISO and went through the full server install process, only now it only takes a fraction of the time!
+
+=== Next Steps
+
+Be sure to check out the tasks in the general xref:installation/postinstallation-tasks.adoc[post-installation guide] for virtual machines as well. 

preview.pid

@@ -0,0 +1 @@
+17997

wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc

@@ -1,26 +1,26 @@
-= Setting up a local authoring envireonment
+= Setting up a local authoring environment
 The Fedora Server Edition working group; Peter Boy (pboy); Stephen Daley (mowest)
 :page-authors: {author}, {author_2}, {author_3}
 // :revnumber: F37-F38
 :revdate: 2023-04-23
 
-Fedora Server documentation is at: https://pagure.io/fedora-server/. 
+Fedora Server documentation is at: https://pagure.io/fedora-server/.
 
-It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Andorra) and must not be changed. 
+It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Andorra) and must not be changed.
 
-It has 2 permanent branches: „main“ for the published content and „stg“ for planning, development, and discussion. Temporarily, additional branches may also be present.
+It has 2 permanent branches: "main" for the published content and "stg" for planning, development, and discussion. Temporarily, additional branches may also be present.
 
 For up- and download you can use either https or ssh. For people with FAS account ssh may be more convenient.
 
-The workflow folllow the Fedora docs project „[https://docs.fedoraproject.org/en-US/fedora-docs/contributing/git/ Git for docs writers]“. Each contributor should create a fork of the repository for themselves. Contributions are uploaded to the fork and then transferred to the authoritative version via a pull request. This opens up the possibility for others to comment and initiate a broader discussion.
+The workflow folllow the Fedora docs project "[https://docs.fedoraproject.org/en-US/fedora-docs/contributing/git/ Git for docs writers]". Each contributor should create a fork of the repository for themselves. Contributions are uploaded to the fork and then transferred to the authoritative version via a pull request. This opens up the possibility for others to comment and initiate a broader discussion.
 
-=== Writing tools
+== Writing tools
 
-You can use any ASCII editor to work on the documentation files. 
+You can use any ASCII editor to work on the documentation files.
 
-A particularly useful OSS Asciidoc editor is https://asciidocfx.com[AsciidocFX]. It is a Java program, very easy to install, and provides both an integrated directory access, a toolbar with the most common AsciiDoc formatting similar to a Word editor and an integrated instant preview. 
+A particularly useful OSS Asciidoc editor is https://asciidocfx.com[AsciidocFX]. It is a Java program, very easy to install, and provides both an integrated directory access, a toolbar with the most common AsciiDoc formatting similar to a Word editor and an integrated instant preview.
 
-=== Creating a new documentation article
+== Creating a new documentation article
 
 An xref:attachment$srv-template.adoc[annotated template] is available to make things easier. Download it and save it in the appropriate directory with a new name.
 
@@ -43,22 +43,22 @@ All file names are in lower case.
 
 == Preparations
 
-1. *Create a local subdirectory* where the files of the documentation should be stored, and make it to your default. We use fedora-server-docs in your home throughout this guide
+1. *Create a local subdirectory* where the files of the documentation should be stored, and make it your default. We use fedora-server-docs in your home directory throughout this guide
 +
-  […]$  mkdir ~/fedora-server-docs
-  […]$  cd       ~/fedora-server-docs
- 
- 2. Still in your default working directory, *clone fedora-server* repository
- +
-   […]$ git clone https://git@pagure.io/fedora-server.git -o upstream 
- +
- Git will copy the complete server repo including all branches, specifically „main“ and „stg“ mentioned above,  into a local repo on your local workstation (into _.git/_ located in your default directory).
- +
- Git does „tag“ the cloned repo  as remote repo „*upstream*“. 
- +
- At the same time it checks out the default branch „''main''“  into your ''working directory'' (i.e. ~/fedora-server-docs in the above example). Therefore, when the operation terminates, you will find in your current default directory, which is now your ''working directory'', some files, e.g. README.md, build.sh and preview.sh and a directory docs. The latter contains the content.
- +
- If you leave off „./“ at the end, git creates another directory in your default directory with the name of the repository, i.e. fedora-server. And this directory is then the "_working directory_" to the repository. This can be useful if you want to keep track of different fedora docs projects in one directory.
+  […]$ mkdir ~/fedora-server-docs
+  […]$ cd    ~/fedora-server-docs
+
+2. Still in your default working directory, *clone fedora-server* repository
++
+  […]$ git clone https://git@pagure.io/fedora-server.git -o upstream
++
+Git will copy the complete server repo including all branches, specifically "main" and "stg" mentioned above, into a local repo on your local workstation (into _.git/_ located in your default directory).
++
+Git does "tag" the cloned repo as remote repo "*upstream*".
++
+At the same time it checks out the default branch "''main''" into your ''working directory'' (i.e. ~/fedora-server-docs in the above example). Therefore, when the operation terminates, you will find in your current default directory, which is now your ''working directory'', some files, e.g. README.md, docsbuilder.sh and preview.sh and a directory docs. The latter contains the content.
++
+If you leave off "./" at the end, git creates another directory in your default directory with the name of the repository, i.e. fedora-server. And this directory is then the "_working directory_" to the repository. This can be useful if you want to keep track of different fedora docs projects in one directory.
 
 3. In your browser go to https://pagure.io/fedora-server/, log in and *create a Fork*. Once you have done it, the button will read _View fork_. Switch to your fork and click on Clone and you will see 2 addresses you can use to clone (copy) the content to your local default directory
 +
@@ -79,19 +79,19 @@ You can use https as well. For users with a FAS account ssh is usually the bette
   upstream	https://git@pagure.io/fedora-server.git (fetch)
   upstream	https://git@pagure.io/fedora-server.git (push)
 +
-In your workflow you will update your local version to the latest versions of the server repository by „pulling“ the content from „upstream“ and upload your modifications and additions by „pushing“ it to origin, i.e. to your fork. You will than create a „pull requuest“, i.e. pick up your modifications and additions from your fork and integrate it into the generic repository („origin“). This enables co-writers to review our work and comment on it.
+In your workflow you will update your local version to the latest versions of the server repository by "pulling" the content from "upstream" and upload your modifications and additions by "pushing" it to origin, i.e. to your fork. You will than create a "pull request", i.e. pick up your modifications and additions from your fork and integrate it into the generic repository ("origin"). This enables co-writers to review our work and comment on it.
 
-5. In your working directory create the *built und preview*
+5. In your working directory build the local version and start the preview tool.
 +
-  […]$ ./build.sh  &&  ./preview.sh
-  
-6, Back to your browser enter the *local preview address*': _localhost:8080_
-*
-You should see a local preview of the current Server documentation
+  […]$ ./docsbuilder.sh
 
-=== Working on content ===
+6. Back in your browser enter the *local preview address*': _localhost:8080_
++
+* You should see a local preview of the current Server documentation
 
-1. Check, if you are on the branch to intend to work on
+== Working on content
+
+1. Check if you are on the branch you intend to work on
 +
   […]$ git branch
   main
@@ -104,21 +104,23 @@ You should see a local preview of the current Server documentation
 Git will adjust and modify the content of your working directory accordingly!
 
 3. Before your begin to work update your working directory
-  […]$ git commit  -m „<YOUR COMMIT MESSAGE>“
-  
++
+  […]$ git commit -m "<YOUR COMMIT MESSAGE>"
+
 4. Modify content
 
 5. Update preview and check:
-  […]$ ./build.sh  &&  ./preview.sh
++
+  […]$ ./docsbuilder.sh
 +
 Preview in your browser using the address _'localhost:8080_
 
-6. Repeat step 4 & 5 as required. 
+6. Repeat step 4 & 5 as required.
 
 
-=== Save Your Work 
+== Save Your Work
 
-Commit your work locally and then push it into your fork „_origin_“.
+Commit your work locally and then push it into your fork "_origin_".
 
 1. Check status
 +
@@ -129,12 +131,11 @@ Commit your work locally and then push it into your fork „_origin_“.
   […]$ git add <FILENAME>
 
 3. Commit locally
-  […]$ git commit  -m „<YOUR COMMIT MESSAGE>“
-
-4. Transfer to your fork of fedora server repository
 +
-  […]$ git push origin  [main|stg]
-  
-5. In your browser open https://pagure.io/fedora-server, login, switch to your fork, and create a pull request.
+  […]$ git commit -m "<YOUR COMMIT MESSAGE>"
 
+4. Transfer your fork of fedora server to the repository
++
+  […]$ git push origin [main|stg]
 
+5. In your browser open https://pagure.io/fedora-server, login, switch to your fork and create a pull request.