Re: [pve-devel] [RFC PATCH docs-common 01/13] installation-media: move page from pve-docs here
Thanks for the review!
On Fri, Apr 19, 2024 at 12:51:07PM +0200, Aaron Lauterer wrote:
>
>
> On 2024-04-19 11:05, Christoph Heiss wrote:
> > Small adaptions were necessary; mostly a s/{pve}/{product}/g and
> > replacing the ISO URL with the {iso-url} variable.
>
> except there are still plenty of `{pve}`s in there?
Oh right, that is a leftover from splitting the patch into to separate
commits. I'll remove that with the next revision. Sorry for the
confusion.
>
> another thing looking at this patch, how do we handle product specifics?
> having a ton of variables that are set according to the product, might be
> cumbersome.
>
> Most likely something like `ifdef:product-pve` and so forth would be useful.
Depending on the amount of specifics, that's were splitting sections out
into partials (into proxmox-docs-common) and then including them into
the main page (in the product-specific docs) come into play.
E.g. the installer page is a good example where I tried to apply this
pattern. Some things like the installer flow and advanced options are
sharable, there are still some sections that are specific to e.g. PVE.
As for e.g. the `{pve}` macro, there is now simply a `{product}` (and
`{product-short}` macro, which already handles most other, trivial
differences.
But overall, that is definitely a point to discuss further and improve
upon incrementally as pages/sections are moved and pain points are
discovered, IMO.
>
> some situations I spotted where we would probably need it in this patched
> marked below:
All of these should be fixed up/adapted in the next patch in the series.
I've split them into two for review sake, where the first is a 1:1 copy
and the next patch then adapts it.
[..]
> > +
> > +ifdef::wiki[]
> > +Boot your Server from the USB Flash Drive
> > +~
> > +
> > +Connect the USB flash drive to your server and make sure that booting from
> > USB
> > +is enabled (check your servers firmware settings). Then follow the steps
> > in the
> > +xref:chapter_installation[installation wizard].
>
> Aligning chapter references will also be some work, especially if we want to
> keep old direct links still working.
That's a very good point, thanks for noticing!
I'll definitely keep note of that, but probably would deal with that as
we come to that.
>
> > +
> > +endif::wiki[]
> > --
> > 2.44.0
> >
> >
> >
> > ___
> > pve-devel mailing list
> > pve-devel@lists.proxmox.com
> > https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
> >
> >
___
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
Re: [pve-devel] [RFC PATCH docs-common 01/13] installation-media: move page from pve-docs here
On 2024-04-19 11:05, Christoph Heiss wrote:
Small adaptions were necessary; mostly a s/{pve}/{product}/g and
replacing the ISO URL with the {iso-url} variable.
except there are still plenty of `{pve}`s in there?
another thing looking at this patch, how do we handle product specifics?
having a ton of variables that are set according to the product, might
be cumbersome.
Most likely something like `ifdef:product-pve` and so forth would be useful.
some situations I spotted where we would probably need it in this
patched marked below:
Signed-off-by: Christoph Heiss
---
installation-media.adoc | 132
1 file changed, 132 insertions(+)
create mode 100644 installation-media.adoc
diff --git a/installation-media.adoc b/installation-media.adoc
new file mode 100644
index 000..a1c9402
--- /dev/null
+++ b/installation-media.adoc
@@ -0,0 +1,132 @@
+[[installation_prepare_media]]
+Prepare Installation Media
+--
+ifdef::wiki[]
+:pve-toplevel:
+endif::wiki[]
+
+Download the installer ISO image from:
{website}en/downloads/proxmox-virtual-environment/iso
^actual download link for each product
+
+The {pve} installation media is a hybrid ISO image. It works in two ways:
+
+* An ISO image file ready to burn to a CD or DVD.
+
+* A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
+
+Using a USB flash drive to install {pve} is the recommended way because it is
+the faster option.
+
+Prepare a USB Flash Drive as Installation Medium
+
+
+The flash drive needs to have at least 1 GB of storage available.
+
+NOTE: Do not use UNetbootin. It does not work with the {pve} installation
image.
+
+IMPORTANT: Make sure that the USB flash drive is not mounted and does not
+contain any important data.
+
+
+Instructions for GNU/Linux
+~~
+
+On Unix-like operating system use the `dd` command to copy the ISO image to the
+USB flash drive. First find the correct device name of the USB flash drive (see
+below). Then run the `dd` command.
+
+
+# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ
^ useful example, though this one could also be helped with by putting
the 've_' part into the glob as well
+
+
+NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
+input filename ('if') path.
+
+CAUTION: Be very careful, and do not overwrite the wrong disk!
+
+
+Find the Correct USB Device Name
+
+There are two ways to find out the name of the USB flash drive. The first one
is
+to compare the last lines of the `dmesg` command output before and after
+plugging in the flash drive. The second way is to compare the output of the
+`lsblk` command. Open a terminal and run:
+
+
+# lsblk
+
+
+Then plug in your USB flash drive and run the command again:
+
+
+# lsblk
+
+
+A new device will appear. This is the one you want to use. To be on the extra
+safe side check if the reported size matches your USB flash drive.
+
+
+Instructions for macOS
+~~
+
+Open the terminal (query Terminal in Spotlight).
+
+Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
+for example:
+
+
+# hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
+
+
+TIP: macOS tends to automatically add '.dmg' to the output file name.
+
+To get the current list of devices run the command:
+
+
+# diskutil list
+
+
+Now insert the USB flash drive and run this command again to determine which
+device node has been assigned to it. (e.g., /dev/diskX).
+
+
+# diskutil list
+# diskutil unmountDisk /dev/diskX
+
+
+NOTE: replace X with the disk number from the last command.
+
+
+# sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
+
+
+NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
+increase the write speed.
+
+Instructions for Windows
+
+
+Using Etcher
+
+
+Etcher works out of the box. Download Etcher from https://etcher.io. It will
+guide you through the process of selecting the ISO and your USB flash drive.
+
+Using Rufus
+^^^
+
+Rufus is a more lightweight alternative, but you need to use the *DD mode* to
+make it work. Download Rufus from https://rufus.ie/. Either install it or use
+the portable version. Select the destination drive and the {pve} ISO file.
+
+IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
+download a different version of GRUB. In the next dialog select the 'DD' mode.
+
+ifdef::wiki[]
+Boot your Server from the USB Flash Drive
+~
+
+Connect the USB flash drive to your server and make sure that booting from USB
+is enabled (check your servers firmware settings). Then follow the steps in the
+xref:chapter_installation[installation wizard].
Aligning chapter references will also
[pve-devel] [RFC PATCH docs-common 01/13] installation-media: move page from pve-docs here
Small adaptions were necessary; mostly a s/{pve}/{product}/g and
replacing the ISO URL with the {iso-url} variable.
Signed-off-by: Christoph Heiss
---
installation-media.adoc | 132
1 file changed, 132 insertions(+)
create mode 100644 installation-media.adoc
diff --git a/installation-media.adoc b/installation-media.adoc
new file mode 100644
index 000..a1c9402
--- /dev/null
+++ b/installation-media.adoc
@@ -0,0 +1,132 @@
+[[installation_prepare_media]]
+Prepare Installation Media
+--
+ifdef::wiki[]
+:pve-toplevel:
+endif::wiki[]
+
+Download the installer ISO image from:
{website}en/downloads/proxmox-virtual-environment/iso
+
+The {pve} installation media is a hybrid ISO image. It works in two ways:
+
+* An ISO image file ready to burn to a CD or DVD.
+
+* A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
+
+Using a USB flash drive to install {pve} is the recommended way because it is
+the faster option.
+
+Prepare a USB Flash Drive as Installation Medium
+
+
+The flash drive needs to have at least 1 GB of storage available.
+
+NOTE: Do not use UNetbootin. It does not work with the {pve} installation
image.
+
+IMPORTANT: Make sure that the USB flash drive is not mounted and does not
+contain any important data.
+
+
+Instructions for GNU/Linux
+~~
+
+On Unix-like operating system use the `dd` command to copy the ISO image to the
+USB flash drive. First find the correct device name of the USB flash drive (see
+below). Then run the `dd` command.
+
+
+# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ
+
+
+NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
+input filename ('if') path.
+
+CAUTION: Be very careful, and do not overwrite the wrong disk!
+
+
+Find the Correct USB Device Name
+
+There are two ways to find out the name of the USB flash drive. The first one
is
+to compare the last lines of the `dmesg` command output before and after
+plugging in the flash drive. The second way is to compare the output of the
+`lsblk` command. Open a terminal and run:
+
+
+# lsblk
+
+
+Then plug in your USB flash drive and run the command again:
+
+
+# lsblk
+
+
+A new device will appear. This is the one you want to use. To be on the extra
+safe side check if the reported size matches your USB flash drive.
+
+
+Instructions for macOS
+~~
+
+Open the terminal (query Terminal in Spotlight).
+
+Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
+for example:
+
+
+# hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
+
+
+TIP: macOS tends to automatically add '.dmg' to the output file name.
+
+To get the current list of devices run the command:
+
+
+# diskutil list
+
+
+Now insert the USB flash drive and run this command again to determine which
+device node has been assigned to it. (e.g., /dev/diskX).
+
+
+# diskutil list
+# diskutil unmountDisk /dev/diskX
+
+
+NOTE: replace X with the disk number from the last command.
+
+
+# sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
+
+
+NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
+increase the write speed.
+
+Instructions for Windows
+
+
+Using Etcher
+
+
+Etcher works out of the box. Download Etcher from https://etcher.io. It will
+guide you through the process of selecting the ISO and your USB flash drive.
+
+Using Rufus
+^^^
+
+Rufus is a more lightweight alternative, but you need to use the *DD mode* to
+make it work. Download Rufus from https://rufus.ie/. Either install it or use
+the portable version. Select the destination drive and the {pve} ISO file.
+
+IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
+download a different version of GRUB. In the next dialog select the 'DD' mode.
+
+ifdef::wiki[]
+Boot your Server from the USB Flash Drive
+~
+
+Connect the USB flash drive to your server and make sure that booting from USB
+is enabled (check your servers firmware settings). Then follow the steps in the
+xref:chapter_installation[installation wizard].
+
+endif::wiki[]
--
2.44.0
___
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
