doc: Add container example to run a web browser.

* doc/guix.texi (Invoking `guix environment'): Add paragraph and example to
  run Eolie in a guix environment container.  Add `container' cindex for the
  first container example, and the `certificates' cindex for the web browser
  example.

1 files changed, 17 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index bc5ecbbcde..ffef097dba 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4777,6 +4777,7 @@ additionally includes Git and strace:
 guix environment --pure guix --ad-hoc git strace
 @end example
 
+@cindex container
 Sometimes it is desirable to isolate the environment as much as
 possible, for maximal purity and reproducibility.  In particular, when
 using Guix on a host distro that is not Guix System, it is desirable to
@@ -4793,6 +4794,22 @@ guix environment --ad-hoc --container guile -- guile
 The @code{--container} option requires Linux-libre 3.19 or newer.
 @end quotation
 
+@cindex certificates
+Another typical use case for containers is to run security-sensitive
+applications such as a web browser.  To run Eolie, we must expose and
+share some files and directories; we include @code{nss-certs} and expose
+@file{/etc/sll/certs/} for HTTPS authentication; finally we preserve the
+the @code{DISPLAY} environment variable since containerized graphical
+applications won't display without it.
+
+@example
+guix environment --preserve='^DISPLAY$' --container --network \
+  --expose=/etc/machine-id \
+  --expose=/etc/ssl/certs/ \
+  --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
+  --ad-hoc eolie nss-certs dbus --  eolie
+@end example
+
 The available options are summarized below.
 
 @table @code