From 494f09955d4e6ca15dc1e2e9c7e091ef8bd56593 Mon Sep 17 00:00:00 2001
From: Chloe Kudryavtsev <toast@toastin.space>
Date: Wed, 5 Dec 2018 23:36:49 -0500
Subject: Add setup-alpine user-handbook page & example

---
 modules/Installing/pages/setup_alpine.adoc | 71 ++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 modules/Installing/pages/setup_alpine.adoc

(limited to 'modules/Installing/pages/setup_alpine.adoc')

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.
-- 
cgit v1.2.3

