From bfbdcfad3489f943748fa584972d27c9255d365b Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Fri, 5 Jan 2024 22:14:44 +0100
Subject: doc: Add Alpine Linux installation instructions

This is currently the recommended OS installation for soundbox.
---
 doc/documentation.tex | 82 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 2 deletions(-)

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 2576a8a..aa45cf8 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -84,9 +84,87 @@ Alternatively a mp3 file can be sent like this:
 
 These commands allow to test the \texttt{soundbox} device setup.
 
-%\chapter{Production}
+\chapter{Production}
+
+The given chapter contains documentation about how to produce a
+\texttt{soundbox} device.
+
 %\section{Printing mechanical parts}
-%\section{Install operating system to SD card}
+
+\section{Alpine Linux installation on a Raspberry Pi}
+
+Alpine Linux for the Raspberry Pi can be downloaded from the Alpine
+Linux\footnote{\href{https://alpinelinux.org/}{https://alpinelinux.org/}}
+download page. This section describes the installation procedure for the
+variant targeting the AArch64 architecture provided as a compressed image file.
+It can be downloaded and verified against a checksum with the \texttt{wget} and
+\texttt{sha256sum} utilities.
+
+\begin{verbatim}
+wget https://dl-cdn.alpinelinux.org/alpine/v3.19/releases\
+    /aarch64/alpine-rpi-3.19.0-aarch64.img.gz
+wget https://dl-cdn.alpinelinux.org/alpine/v3.19/releases\
+    /aarch64/alpine-rpi-3.19.0-aarch64.img.gz.sha256
+sha256sum -c alpine-rpi-3.19.0-aarch64.img.gz.sha256
+\end{verbatim}
+
+The image has to be flashed to a SD card which will be inserted into the
+Raspberry Pi. This SD card has to be put into a Linux PC first. In Linux every
+SD card is represented as a block device like \texttt{sda} or \texttt{sdb} with
+a file path like \texttt{/dev/sda}. Possibly existing partitions on the SD card
+are represented with that path and a number as suffix like in
+\texttt{/dev/sda1}. The program \texttt{lsblk} gives an overview of the
+currently connected block devices. The correct device name for the SD card can
+be identified by its size.
+
+\begin{verbatim}
+$ lsblk
+NAME        MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
+sda           8:0    1  59,5G  0 disk
+`-sda1        8:1    1  59,5G  0 part
+\end{verbatim}
+
+If the correct SD card file path is determined the downloaded image can be
+decompressed with \texttt{gzip} and flashed with \texttt{dd}. The \texttt{dd}
+call requires the privileges of the root user which might be temporarily
+accessed by prefixing \texttt{sudo}.
+
+\textbf{Warning}: \texttt{dd} will write the image to the specified block
+device. If that block device is the primary hard drive of the computer it will
+do that without further confirmation. This will make the operating system of
+the PC unusable.
+
+After flashing it is required to synchronize all write operations to the card
+with \texttt{sync}.
+
+\begin{verbatim}
+gzip -d alpine-rpi-3.19.0-aarch64.img.gz
+dd if=alpine-rpi-3.19.0-aarch64.img of=<sd-card-path>
+sync
+\end{verbatim}
+
+Afterwards the SD card can be inserted into the Raspberry Pi. To do initial
+configuration it should be connected to a screen via HDMI. Also a keyboard has
+to be connected via USB. A mouse is not required. Finally the Pi should be
+powered up by connecting a USB power supply to the corresponding USB power
+input of the Raspberry Pi. Text from the boot process should be displayed on
+the screen.
+
+After logging in with the username \texttt{root} and no password basic system
+configuration on Alpine Linux can be done interactively with
+\texttt{setup-alpine}. The Alpine Linux installation
+guide\footnote{\href{https://wiki.alpinelinux.org/wiki/Installation}{https://wiki.alpinelinux.org/wiki/Installation}}
+contains further details. When a diskless installation is choosen the
+configuration changes have to be made persistent with the \texttt{lbu} command.
+Otherwise they will be lost on the next reboot.
+
+\begin{verbatim}
+setup-alpine
+lbu commit -d
+\end{verbatim}
+
+With this setup the Alpine Linux installation is completed.
+
 %\section{Final assembly}
 
 %\chapter{Device internals}
-- 
cgit v1.2.3-70-g09d2