Add setup-alpine user-handbook page & example

2 files changed, 113 insertions, 0 deletions

diff --git a/modules/Installing/examples/setup_example.sh b/modules/Installing/examples/setup_example.sh
new file mode 100644
index 0000000..2023895
--- /dev/null
+++ b/modules/Installing/examples/setup_example.sh
@@ -0,0 +1,42 @@
+# Example answer file for setup-alpine script
+# If you don't want to use a certain option, then comment it out
+
+# Use US layout with US variant
+KEYMAPOPTS="us us"
+
+# Set hostname to alpine-test
+HOSTNAMEOPTS="-n alpine-test"
+
+# Contents of /etc/network/interfaces
+INTERFACESOPTS="auto lo
+iface lo inet loopback
+
+auto eth0
+iface eth0 inet dhcp
+    hostname alpine-test
+"
+
+# Search domain of example.com, Google public nameserver
+DNSOPTS="-d example.com 8.8.8.8"
+
+# Set timezone to UTC
+TIMEZONEOPTS="-z UTC"
+
+# set http/ftp proxy
+PROXYOPTS="http://webproxy:8080"
+
+# Add a random mirror
+APKREPOSOPTS="-r"
+
+# Install Openssh
+SSHDOPTS="-c openssh"
+
+# Use openntpd
+NTPOPTS="-c openntpd"
+
+# Use /dev/sda as a data disk
+DISKOPTS="-m data /dev/sda"
+
+# Setup in /media/sdb1
+LBUOPTS="/media/sdb1"
+APKCACHEOPTS="/media/sdb1/cache"
diff --git a/modules/Installing/pages/setup_alpine.adoc b/modules/Installing/pages/setup_alpine.adoc
new file mode 100644
index 0000000..be1b81e
--- /dev/null
+++ b/modules/Installing/pages/setup_alpine.adoc
@@ -0,0 +1,71 @@
+= `setup-alpine`
+// MAINT: this whole page, on alpine-conf
+
+Now that you are booted in, you can log-in without a password as the root user.
+Alpine has a script called `setup-alpine`, which performs basic installation procedures.
+This section of the handbook describes its operation modes, as well as how to use it.
+However, no script is perfect, so it is recommended that if your use-case is not so simple, or you run into issues using it, to proceed to the next section that involves manual setup.
+// TODO: link to network configuration section
+For example, if you have no access to a wired network, you will need to configure networking yourself.
+
+== `setup-alpine -q`
+
+The q, or "quick" mode of the `setup-alpine` script allows one to get a trivial system configuration running quickly, to then proceed with other installation tasks, possibly remotely.
+
+Under quick mode, `setup-alpine` will:
+
+- Setup your keyboard layout
+- Initialize your hostname to the default "alpine" value
+- Set your primary (autodetected) interface to use DHCP, and start networking
+- Enable various relevant system services, and start them
+- Generate a valid `/etc/hosts` file
+- Enable the default repository
+
+// TODO: add networking xref
+[WARNING]
+====
+`setup-alpine`'s networking set-up will *not* work by itself for wifi.
+If you have no access to an ethernet port and cable, make sure you see the section on configuring networking manually.
+====
+
+Quick mode is useful to get a system online and operational very quickly (thus the name) to then go on to use it manually.
+
+The steps quick mode skips are, in order:
+
+- Setting a root password
+- Setting up a timezone
+- Setting up an optional proxy
+- Setting up an ssh daemon
+- Enabling NTP synchronization
+- Configuring the disk, if any
+- Configuring lbu
+- Configuring apk's caching mechanism
+
+== Full `setup-alpine`
+
+`setup-alpine` in normal mode will do all of the abovementioned steps, under some conditions, and will rely much less on default values.
+
+It is recommended to use this mode directly if your scenario is trivial.
+A trivial scenario is defined as such:
+
+- You have a single (currently) physical disk and you want to install to it
+- Your primary network connection is wired, and it is DHCP-compatible
+- You do not significantly care about what bootloader or filesystem you use
+- You are not in UEFI mode
+
+If all of these apply, you can simply run `setup-alpine` and follow the prompts to set up your system.
+If they do not, it may still be appropriate, but you will need to customize its behavior with an answer file and/or environment variables.
+
+== Answer Files
+
+You can preprogram various answers to `setup-alpine` 's questions.
+Here is the answer file it generates for you if you ask it to.
+
+// EDITOR NOTE: this include will only show up in Antora
+[source,sh]
+----
+include::example$setup_example.sh[]
+----
+
+You can also add extra environment variables to configure the behavior of any given utility.
+For more details on those, see the rest of the setting up (manually) section of the user handbook, or the developer handbook on the technical details of those utilities.