Install doc + templates overhaul

Install doc + templates overhaul

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 4225 bytes --]

I've just re-installed Guix from a 0.16 image.  My first time in a year,
and I've had the opportunity to have a fresh look at the installation
manual.  I've taken note of a few confusing points that gave me a hard
time installing Guix (even the 2nd time :p) so here they are.  I'll send
a patch to address them if you people agree.


- From the manual, 6.1.4 Preparing for Installation:

--8<---------------cut here---------------start------------->8---
   If you instead wish to use EFI-based GRUB, a FAT32 “EFI System
Partition” (ESP) is required.  This partition should be mounted at
‘/boot/efi’ and must have the ‘esp’ flag set.  E.g., for ‘parted’:
--8<---------------cut here---------------end--------------->8---

Actually the EFI partition can be mounted anywhere (/efi or /boot are also
customary), it's up to the users to make sure they are pointed at the right
mounted location.


--8<---------------cut here---------------start------------->8---
   Also mount any other file systems you would like to use on the target
system relative to this path.  If you have ‘/boot’ on a separate
partition for example, mount it at ‘/mnt/boot’ now so it is found by
‘guix system init’ afterwards.
--8<---------------cut here---------------end--------------->8---

That's not consistent with /mnt/boot/efi that was just mentioned above.
Besides, I think we should mention the word "EFI" in this paragraph so that
people find this paragraph when they search for the EFI term to make sure
they've covered everything

- From 6.1.5 Proceeding with the Installation
--8<---------------cut here---------------start------------->8---
   • Make sure the ‘bootloader-configuration’ form refers to the target
     you want to install GRUB on.  It should mention ‘grub-bootloader’
     if you are installing GRUB in the legacy way, or
     ‘grub-efi-bootloader’ for newer UEFI systems.  For legacy systems,
     the ‘target’ field names a device, like ‘/dev/sda’; for UEFI
     systems it names a path to a mounted EFI partition, like
     ‘/boot/efi’, and do make sure the path is actually mounted.
--8<---------------cut here---------------end--------------->8---

At the end, it's unclear whether the EFI partition must be _currently_ mounted
or if the config.scm must have a mount point declaration.  Actually, it's both,
and that be made explicit I think.  Also see the next point:

- From gnu/system/examples/desktop.tmpl:

--8<---------------cut here---------------start------------->8---
  ;; Use the UEFI variant of GRUB with the EFI System
  ;; Partition mounted on /boot/efi.
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")))
  ;...

  (file-systems (cons (file-system
                        (device (file-system-label "my-root"))
                        (mount-point "/")
                        (type "ext4")
                        (dependencies mapped-devices))
                      %base-file-systems))
--8<---------------cut here---------------end--------------->8---

The EFI partition is missing from the file-systems declaration!!


- All templates:
I remember this was discussed before, but shouldn't we replace (cons* ...) with
(list ...)?  It's easier to grok for users new to Lisp.

- In the operating-system record, what's the default value of home-directory (in
  (users (list (user-account (home-directory ...)))))?  Shouldn't default to
  (string-append "/home/" name)?  That could also spare us some potential
  mistakes at install-time.

- I was surprised to see that from the install image, curl, git, etc. would fail
  with an SSL error.  It's annoying because I really needed to get my config.scm
  from an online source.

  I only briefly investigated: the environment has

--8<---------------cut here---------------start------------->8---
SSL_CERT_DIR=/etc/ssl/certs
SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
--8<---------------cut here---------------end--------------->8---

  but the install image only has a /etc/ssl file.

--
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Install doc + templates overhaul

[Ludovic Courtès]

Hello Pierre,

Pierre Neidhardt <mail@ambrevar.xyz> skribis:

> I've just re-installed Guix from a 0.16 image.  My first time in a year,
> and I've had the opportunity to have a fresh look at the installation
> manual.  I've taken note of a few confusing points that gave me a hard
> time installing Guix (even the 2nd time :p) so here they are.  I'll send
> a patch to address them if you people agree.

Did you try installing with the new installer?  Hopefully most of this
documentation becomes secondary when one uses the installer.  :-)

Anyway, the changes you propose overall LGTM.

Thanks,
Ludo’.

Re: Install doc + templates overhaul

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 330 bytes --]


> Did you try installing with the new installer?  Hopefully most of this
> documentation becomes secondary when one uses the installer.  :-)

I did, see the other thread "Merging 'wip-newt-installer' in master?".

I'll update master later today.
Thanks for reviewing this!

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Install doc + templates overhaul

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 688 bytes --]

Wait, what about this:

> - I was surprised to see that from the install image, curl, git, etc. would fail
>   with an SSL error.  It's annoying because I really needed to get my config.scm
>   from an online source.
> 
>   I only briefly investigated: the environment has
> 
> --8<---------------cut here---------------start------------->8---
> SSL_CERT_DIR=/etc/ssl/certs
> SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
> --8<---------------cut here---------------end--------------->8---
> 
>   but the install image only has a /etc/ssl file.

Is this broken or intentional?  Can you point me at where this is defined?

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Install doc + templates overhaul

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 1029 bytes --]

I'm trying to set the default for user.  Here is the record from
installer/user.scm:

--8<---------------cut here---------------start------------->8---
(define-record-type* <user>
  user make-user
  user?
  (name            user-name)
  (group           user-group
                   (default "users"))
  (home-directory  user-home-directory))
--8<---------------cut here---------------end--------------->8---

The following does not work:

--8<---------------cut here---------------start------------->8---
(define-record-type* <user>
  user make-user
  user?
  (name            user-name)
  (group           user-group
                   (default "users"))
  (home-directory  user-home-directory
                   (default (string-append "/home/" name))))
--8<---------------cut here---------------end--------------->8---

The define-record-type* does not seem to allow the record field initialization
to refer to itself.

Is there a way around it?

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Install doc + templates overhaul

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 161 bytes --]

I've pushed the doc changes onto the install-doc-overhaul branch.
Feel free to merge if you are happy with it.

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

‘nss-certs’ missing in the installation image

[Ludovic Courtès]

Hi,

Pierre Neidhardt <mail@ambrevar.xyz> skribis:

> Wait, what about this:
>
>> - I was surprised to see that from the install image, curl, git, etc. would fail
>>   with an SSL error.  It's annoying because I really needed to get my config.scm
>>   from an online source.
>> 
>>   I only briefly investigated: the environment has
>> 
>> --8<---------------cut here---------------start------------->8---
>> SSL_CERT_DIR=/etc/ssl/certs
>> SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
>> --8<---------------cut here---------------end--------------->8---
>> 
>>   but the install image only has a /etc/ssl file.
>
> Is this broken or intentional?  Can you point me at where this is defined?

‘nss-certs’ is intentionally not in %base-packages nor in the
installation image.  The rationale is that the package contains X.509
certificates bundled together by Mozilla and when we discussed it there
was a rough consensus that it should be the user’s decision to trust
these.  One could object that IceCat comes with its own copy of these
certificates anyway…

Someone following the normal installation procedure shouldn’t need those
certificates though.  WDYT?

Ludo’.

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 394 bytes --]

What's the procedure to install nss-certs then?
Will a simple `guix package -i nss-certs` do?

I think we should document this in the installation manual.

> Someone following the normal installation procedure shouldn’t need those
> certificates though.  WDYT?

HTTPS access is a fairly common requirement for a lot of people I think.

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: ‘nss-certs’ missing in the installation image

[Giovanni Biscuolo]

[-- Attachment #1: Type: text/plain, Size: 906 bytes --]

Hi Pierre,

Pierre Neidhardt <mail@ambrevar.xyz> writes:

> What's the procedure to install nss-certs then?
> Will a simple `guix package -i nss-certs` do?

no, a number of environment variables need to be defined, depending on
applications

> I think we should document this in the installation manual.

it's all documented in "@node X.509 Certificates" ;-)

>> Someone following the normal installation procedure shouldn’t need those
>> certificates though.  WDYT?
>
> HTTPS access is a fairly common requirement for a lot of people I
> think.

there's a "@cindex HTTPS, certificates" in that node: do you think we
need another one?

do we need a guix-faq.texi ala "Emacs FAQ"?
(IMHO we need it, I can help maintaining it but sorry I cannot
"bootstrap" it since I still lack needed knowledge)

WDYT?

Ciao,
Giovanni

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 216 bytes --]

Indeed, it's all in the X.509 section.  My problem is that it's not mentioned in
"6.1 System Installation".

I'll add a link to the X.509 node if no one disagrees.

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: ‘nss-certs’ missing in the installation image

[Ludovic Courtès]

Pierre Neidhardt <mail@ambrevar.xyz> skribis:

> Indeed, it's all in the X.509 section.  My problem is that it's not mentioned in
> "6.1 System Installation".
>
> I'll add a link to the X.509 node if no one disagrees.

I’m not sure it belongs in “System Installation”.  After all, it’s
already under “System Configuration” and in several OS config examples.

Ludo’.

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 486 bytes --]


> I’m not sure it belongs in “System Installation”.  After all, it’s
> already under “System Configuration” and in several OS config examples.

Here the issue is not with system configuration, but with the live install
image.
In this sense, I'd say it belongs next to the network setup instructions.

Leaving it to System Configuration is too late.  Conversely, the OS config
examples don't address the same issue.

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: ‘nss-certs’ missing in the installation image

[swedebugia]

Hi

On 2019-01-23 12:22, Pierre Neidhardt wrote:
> 
>> I’m not sure it belongs in “System Installation”.  After all, it’s
>> already under “System Configuration” and in several OS config examples.
> 
> Here the issue is not with system configuration, but with the live install
> image.
> In this sense, I'd say it belongs next to the network setup instructions.
> 
> Leaving it to System Configuration is too late.  Conversely, the OS config
> examples don't address the same issue.
> 

I agree we should at least note this in the installer.

I stumbled on this the last time I installed from USB. I could not get 
my config.scm because it was on a https-only server:

$ wget http://gitlab.com/swedebugia/guix-config/raw/master/config.scm
URL transformed to HTTPS due to an HSTS policy
--2019-01-23 14:58:06-- 
https://gitlab.com/swedebugia/guix-config/raw/master/config.scm
Läste in CA-certifikatet ”/etc/ssl/certs/ca-certificates.crt”
Slår upp gitlab.com (gitlab.com)... 35.231.145.151
Ansluter till gitlab.com (gitlab.com)|35.231.145.151|:443... ansluten.
HTTP-begäran skickad, väntar på svar... 200 OK
Längd: 4569 (4,5K) [text/plain]
Sparar till: "config.scm"

config.scm 
100%[================================================================>] 
  4,46K  --.-KB/s    om 0s

2019-01-23 14:58:07 (28,9 MB/s) - "config.scm" sparades [4569/4569]

-- 
Cheers Swedebugia

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 68 bytes --]

Any other opinion?

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: ‘nss-certs’ missing in the installation image

[Amin Bandali]

> Any other opinion?

I’d personally prefer if nss-certs were already available during
installation; but if not, having a link in “System Installation” to
instructions on how to safely install and set it up seems like a fair
compromise.

My 2¢.

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 686 bytes --]

I suggest the following patch:

diff --git a/doc/guix.texi b/doc/guix.texi
index 972a6a776..3f148e390 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2071,6 +2071,10 @@ ping -c 3 gnu.org
 Setting up network access is almost always a requirement because the
 image does not contain all the software and tools that may be needed.
 
+If you require web access over HTTPS with tools such as @command{wget} or
+@command{git}, see @xref{X.509 Certificates} for details on how to set up the
+certificates.
+
 @cindex installing over SSH
 If you want to, you can continue the installation remotely by starting
 an SSH server:

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: ‘nss-certs’ missing in the installation image

[Ludovic Courtès]

Pierre Neidhardt <mail@ambrevar.xyz> skribis:

>> I’m not sure it belongs in “System Installation”.  After all, it’s
>> already under “System Configuration” and in several OS config examples.
>
> Here the issue is not with system configuration, but with the live install
> image.

Oh OK.  For the install image, maybe it’s OK to add ‘nss-certs’ to the
base package set after all, if that helps minimize friction.

Objections?

Ludo’.

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 58 bytes --]

None! :)

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1.1: Type: text/plain, Size: 136 bytes --]

Find a patch attached.

Let me know if it's the right way to do it, then I'll merge.

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-install-Add-nss-certs-to-the-image.patch --]
[-- Type: text/x-patch, Size: 946 bytes --]

From 082f569611a889ef0e852263b5ba23373936b422 Mon Sep 17 00:00:00 2001
From: Pierre Neidhardt <mail@ambrevar.xyz>
Date: Fri, 8 Feb 2019 15:30:08 +0100
Subject: [PATCH] install: Add nss-certs to the image.

* gnu/system/install.scm (installation-os)[packages]: Add nss-certs.
---
 gnu/system/install.scm | 1 +
 1 file changed, 1 insertion(+)

diff --git a/gnu/system/install.scm b/gnu/system/install.scm
index 880a8be32..137123c72 100644
--- a/gnu/system/install.scm
+++ b/gnu/system/install.scm
@@ -409,6 +409,7 @@ You have been warned.  Thanks for being so brave.\x1b[0m
                      ;; available here, so we keep that.
                      bash-completion
                      nvi                          ;:wq!
+                     nss-certs ; To access HTTPS, use git, etc.
                      %base-packages))))
 
 (define* (os-with-u-boot os board #:key (bootloader-target "/dev/mmcblk0")
-- 
2.20.1


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: ‘nss-certs’ missing in the installation image

[Ludovic Courtès]

Pierre Neidhardt <mail@ambrevar.xyz> skribis:

> From 082f569611a889ef0e852263b5ba23373936b422 Mon Sep 17 00:00:00 2001
> From: Pierre Neidhardt <mail@ambrevar.xyz>
> Date: Fri, 8 Feb 2019 15:30:08 +0100
> Subject: [PATCH] install: Add nss-certs to the image.
>
> * gnu/system/install.scm (installation-os)[packages]: Add nss-certs.

LGTM, thanks!

Ludo'.

Re: ‘nss-certs’ missing in the installation image

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 57 bytes --]

Merged!

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]