doc: Add quickstart document #66
Conversation
|
Direct link to the quickstart document https://github.com/cfergeau/vfkit/blob/quickstart/doc/quickstart.md |
doc/quickstart.md
Outdated
| # For Intel Macs | ||
| $ curl -L https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora-Cloud-Base-38-1.6.x86_64.raw.xz | ||
| $ xz -d ./Fedora-Cloud-Base-38-1.6.x86_64.raw.xz | ||
| $ cp -c Fedora-Cloud-Base-38-1.6.x86_64.raw Fedora-Cloud-Base-38.raw |
There was a problem hiding this comment.
why not mv ? the resulting copy is only to use a consistent name in the next paragraphs.
There was a problem hiding this comment.
It's a good point that cp -c might be "too advanced" for this guide. However, to me it's a very neat feature to be aware of, it's macOS-specific so users are likely not to be aware of it, and it allows to have the equivalent of qcow2 backing files. You keep a base image, and you have an overlay with your changes on top of it. Maybe move this to its own paragraph with more details? Or to the reference documentation ?
There was a problem hiding this comment.
I have left this unchanged in the update I just made, but will do more changes now.
There was a problem hiding this comment.
I've addressed this now, only using mv in the quick start document, and pointing at a more detailed doc about cp -c and truncate and corresponding syscalls.
doc/quickstart.md
Outdated
| $ cp -c Fedora-Cloud-Base-38-1.6.x86_64.raw Fedora-Cloud-Base-38.raw | ||
| ``` | ||
|
|
||
| `cp -c` will create a copy on write image, its initial content is the same as the downloaded file, but all modifications will only be done in the copy. |
There was a problem hiding this comment.
this seems unnecessary information, as you explain what a 'copy' of a virtual disk image represents. It would most likely be easier to just call the copy in that case simply something like: fedora-vfkit-test.raw or whatever.
There was a problem hiding this comment.
No cleanup for the downloaded file either, I would leave that up to the reader?
cfergeau
force-pushed
the
quickstart
branch
2 times, most recently
from
d03ad2a
to
c923127
Compare
|
One big unsanswered question in this document is how to inject a ssh key into the image, or get shell access to the guest, or do anything useful with the guest. This is an image which uses cloud-init, and I don't know how to use this with vfkit, so it will stay unanswered for now. |
doc/quickstart.md
Outdated
| You start a virtual machine by running vfkit with a set of arguments describing the virtual machine configuration/hardware. | ||
| When vfkit stops, the virtual machine stops running. | ||
| It requires macOS 11 or newer, and runs on both x86_64 and aarch64 Macs. | ||
| Some features are only available on macOS 13 or newer. |
There was a problem hiding this comment.
some features? if EFI is not available < 13 it might be wise to explain this.
There was a problem hiding this comment.
EFI, virtio-fs, ...
doc/quickstart.md
Outdated
| ### Getting a disk image | ||
|
|
||
| Your virtual machine will need an operating system to run, so you need to download a disk image first. | ||
| The image needs to be in the raw or iso format. qcow2 or VirtualBox images cannot be used by vfkit. |
There was a problem hiding this comment.
Please note that qcow to avoid starting the sentence without a capital.
doc/quickstart.md
Outdated
|
|
||
| The virtual machine will be running until you hit Ctrl+C or kill the vfkit process. | ||
| If you are using an image which does not support UEFI boot, you can use the [`linux` bootloader](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#linux-bootloader). | ||
| This requires separate kernel, initrd file and kernel command-line arguments. |
There was a problem hiding this comment.
I would suggest to use linux bootloader as a regular part of sentence and moving the usage.md to the end of the following sentence.
This requires a .... Details about the use can be found in the usage instructions.
| See also [vz/CreateDiskImage](https://pkg.go.dev/github.com/Code-Hex/vz/v3#CreateDiskImage). | ||
|
|
||
|
|
||
| #### Thin images |
Updated, I'll merge it tomorrow if no more comments. |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: anjannath, gbraad The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
No description provided.