docs: add initial installation document

Sponsored-by: author

1 files changed, 127 insertions, 0 deletions

diff --git a/install.md b/install.md
new file mode 100644
index 0000000..47b0ca7
--- /dev/null
+++ b/install.md
@@ -0,0 +1,127 @@
+# Installing Puomi
+
+Puomi is Internet router software for home and small office use. It
+consists of [Debian][] with a custom configuration to enable use of a
+PC as a router.
+
+To use Puomi you need:
+
+* A PC with at least two Ethernet ports and UEFI. Below, we call it
+  "the router PC".
+* A USB drive to hold the installer image.
+* A second machine to provision the router. Below, we call it the
+  "laptop", but it can be any machine.
+
+To install, short version:
+
+* Download a [v-i][] installer image.
+  - v-i is a custom installer for Debian
+* Write the image to a USB drive.
+* Configure the USB drive.
+* Boot your router PC from the USB drive.
+* Copy the Puomi specification file and playbook to installer.
+* Install Puomi on the PC.
+* Boot the PC.
+
+These steps will be covered in more detail below.
+
+## Get installer image
+
+* Download the 0.2 release image and helper scripts.
+  - <https://files.liw.fi/v-i/0.2/v-i.img.xz>
+  - <https://files.liw.fi/v-i/0.2/write-and-config.sh>
+  - <https://files.liw.fi/v-i/0.2/configure-installer>
+* Decompress the image.
+  - `unxz v-i.img.xz`
+* Create an installer configuration, like the one below. Below, we
+  call it `your.yaml`. The simplest is to set one configuration key to
+  the name of your SSH public key file.
+
+~~~yaml
+authorized_keys_file: mykey.pub
+~~~
+
+* Insert the USB drive to a USB port, and find out the device name.
+  (GNOME Disks is a good tool for this. Kernel messages will also tell
+  you.) Below, we call it `/dev/sdx`.
+* Write the installer to the USB drive and configure it.
+
+~~~sh
+./write-and-config your.yaml /dev/sdx
+~~~
+
+* Make sure everything is written to the drive, then remove it.
+
+~~~sh
+eject /dev/sdx
+~~~
+
+* You may want to label the drive so you remember which one is the
+  installer.
+
+## Install on your PC.
+
+* Connect the router PC's main Ethernet port to your home Internet
+  connection. This can be directly to the external network, or to your
+  existing router.
+  - the main port is the one know to Linux as "eth0".
+* Connect your laptop to any other Ethernet port in the router PC.
+* Insert the installer USB to the router PC and boot off it. This may
+  involve telling your BIOS which drive to boot from. Every BIOS is
+  different about this.
+* Your laptop should get an address 10.1.1.something from the router
+  DHCP. Your laptop won't be able to access the Internet, but you can
+  log into the installer. Check that you can log, then log out again.
+
+~~~sh
+ssh root@v-i
+~~~
+
+* Create a "specification" file to describe the installation you want
+  to do. Below we call it `x220.yaml`. You can pick any host name. The
+  drive must be the drive from which the PC boots.
+
+~~~yaml
+drive: /dev/sda
+hostname: x220
+extra_playbooks:
+  - puomi-playbook.yml
+ansible_vars:
+  user_pub: |
+    YOUR SSH PUBLIC KEY GOES HERE
+~~~
+
+* Copy the spec file and the Puomi initial playbook to the installer.
+
+~~~sh
+scp x220.yaml puomi-playbook.yml root@v-i:
+~~~
+
+* Log back into the installer, and do the install. Run the following
+  in the installer:
+
+~~~sh
+./v-i --verbose x220.yaml
+~~~
+
+* Reboot.
+
+The router PC should now boot into a Debian system that has been
+configured as an Internet router. Your laptop, still connected to the
+router, should be able to access the Internet normally. DNS should
+work just fine.
+
+The router implements NAT, which means that your laptop won't be
+accessible directly from the public side of the router PC: any
+connections must be initiated by the laptop. There is, however, no
+firewall, unless you set it up yourself.
+
+## Configure the installer as you wish
+
+You have root. You can configure the router as you wish. The `puomi`
+Ansible role in the Puomi source tree may be useful, if Ansible is
+your kind of thing. You can also use any other configuration
+management tooling you prefer.
+
+[Debian]: https://www.debian.org/
+[v-i]: https://v-i.liw.fi/