doc: Add Alpine Linux config guide

Configuring the Alpine Linux operating system correctly for soundbox is
not trivial. Since it is very important it has to be documented in
detail.

1 files changed, 69 insertions, 1 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 53452ee..ddade37 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -54,7 +54,7 @@ devices..
 
 %\section{Device setup}
 
-\section{Playing audio}
+\section{Playing audio} \label{playing-audio}
 
 For a simple audio streaming test the following commands from the FFmpeg
 streaming
@@ -179,6 +179,74 @@ lbu commit -d
 
 With this setup the Alpine Linux installation is completed.
 
+\section{Configure Alpine Linux for soundbox}
+
+soundbox requires packages from the Alpine Linux community package repository.
+Since this is not enabled by default it has to be done manually. This can be
+done by editing the \texttt{/etc/apk/repositories} file with an editor like
+\texttt{vi}. The hash sign \texttt{\#} in front of the URL to the community
+repository has to be removed. Instead also \texttt{sed} can remove this sign on
+a fresh installation quite easily since the community repository is the only
+one with such a sign in front of it.
+
+\begin{verbatim}
+sed -i 's/^#//g' /etc/apk/repositories
+\end{verbatim}
+
+With an enabled community repository all required packages for soundbox can be
+installed. The list with required packages can be written to the
+\texttt{/etc/apk/world} file with \texttt{echo}. Running \texttt{apk add} after
+it will install all of these packages including their dependencies and removes
+everything else. This makes sure that always exactly the same set of packages
+is used for a soundbox device.
+
+\begin{verbatim}
+echo 'alpine-base
+alsa-utils
+alsaconf
+busybox-mdev-openrc
+chrony
+ffplay
+iw
+openssh
+openssl
+wpa_supplicant' > /etc/apk/world
+
+apk add
+\end{verbatim}
+
+The only user on a soundbox device is \texttt{root}. Even that super user has
+to be added to the \texttt{audio} group to be able to play sound via ALSA. This
+can be achieved with \texttt{addgroup}.
+
+\begin{verbatim}
+addgroup root audio
+\end{verbatim}
+
+soundbox uses the HiFiBerry shield to output high-quality audio. This shield
+needs to be enabled as an audio output by specifying a Devicetree overlay in
+the Raspberry Pi configuration file with \texttt{echo}. Since this file is
+stored on the SD card only which is mounted as read-only it has to be remounted
+with the read-write option first.
+
+\begin{verbatim}
+mount -o remount,rw /media/mmcblk0p1
+echo 'dtoverlay=hifiberry-dac' >> /media/mmcblk0p1/config.txt
+\end{verbatim}
+
+Since a diskless Alpine Linux installation is preferred for soundbox the
+changes have to be made persistent with \texttt{lbu}. Rebooting after it makes
+sure the SD card is again mounted in read-only mode and all Kernel-affecting
+changes can be applied.
+
+\begin{verbatim}
+lbu commit -d
+reboot
+\end{verbatim}
+
+After this reboot the soundbox device should be able to play audio like
+described in section~\ref{playing-audio}.
+
 %\section{Final assembly}
 
 %\chapter{Device internals}