Merge branch 'develop' into feature/time-server/EVA-2020-02

[EVA-2020-02.git] / doc / setup / README.org

diff --git a/doc/setup/README.org b/doc/setup/README.org
index fadd0887fcdcf92b807cbb6ad0bcfc1a50189e72..7c5b63afcebc2be41a11c28b93b17ca3b0d39ac4 100644 (file)
--- a/doc/setup/README.org
+++ b/doc/setup/README.org
@@ -5,7 +5,7 @@
 ** About
 This document created by [[http://baltakatei.com][Steven Baltakatei Sandoval]] on
 ~2020-10-07T18:39Z~ under a [[http://creativecommons.org/licenses/by-sa/4.0/][CC BY-SA 4.0]] license and last updated on
 ** About
 This document created by [[http://baltakatei.com][Steven Baltakatei Sandoval]] on
 ~2020-10-07T18:39Z~ under a [[http://creativecommons.org/licenses/by-sa/4.0/][CC BY-SA 4.0]] license and last updated on

-~2020-10-07T23:08Z~.
+~2020-10-08T00:50Z~.

 
 This document contains information regarding setup of the
 ninfacyzga-01 hardware common to all operation modes. This includes:
 
 This document contains information regarding setup of the
 ninfacyzga-01 hardware common to all operation modes. This includes:


@@ -121,10 +121,16 @@ cat location.gpx.age | age -d -i key.txt > location.gpx
 
 The version of ~age~ used to perform the encryption 
 
 
 The version of ~age~ used to perform the encryption 
 

-

 ** Operating Procedures
 *** Initial Startup
 **** Physical Setup
 ** Operating Procedures
 *** Initial Startup
 **** Physical Setup

+The device should be supplied with 5V power and an SD card with the
+latest Raspberry Pi OS image installed. As of 2020-10-07, this will be
+version 10 (e.g. Raspbian Buster 10).
+
+No additional hardware (ex: GPS module, UPS module, thermocouples) is
+required to perform actions described in this document
+

 **** Software Setup
 ***** Install Operating System
 Install Raspberry Pi OS onto an SD card image. See the Raspberry Pi
 **** Software Setup
 ***** Install Operating System
 Install Raspberry Pi OS onto an SD card image. See the Raspberry Pi


@@ -161,7 +167,7 @@ Replace ~<Name of your wireless LAN>~ with your WiFi network's SSID.
 
 Replace ~<Password for your wireless LAN>~ with your WiFi network's
 passphrase.
 
 Replace ~<Password for your wireless LAN>~ with your WiFi network's
 passphrase.

-***** Configure Remote SSH Login
+***** Enable Remote SSH Login

 Configure SSH to permit remote administration via the command line
 interface. Raspberry Pi Foundation instructions [[https://www.raspberrypi.org/documentation/remote-access/ssh/README.md][here]].
 
 Configure SSH to permit remote administration via the command line
 interface. Raspberry Pi Foundation instructions [[https://www.raspberrypi.org/documentation/remote-access/ssh/README.md][here]].
 


@@ -169,6 +175,15 @@ In summary, remote SSH access may be enabled upon initial startup of a
 freshly installed image of Raspberry Pi OS by making sure an empty
 file named ~ssh~ is present on the ~boot~ partition.
 
 freshly installed image of Raspberry Pi OS by making sure an empty
 file named ~ssh~ is present on the ~boot~ partition.
 

+***** Add SSH public key
+If the use has an SSH public key, it may be added as a line in
+~~/.ssh/authorized_keys~.
+
+Follow [[https://superuser.com/a/925859/][these]] directions to set permissions.
+
+: $ chmod 700 ~/.ssh
+: $ chmod 644 ~/.ssh/authorized_keys
+

 ***** Change default passphrase
 The default username is ~pi~ and the default passphrase is
 ~raspberry~. Change them to something unique.
 ***** Change default passphrase
 The default username is ~pi~ and the default passphrase is
 ~raspberry~. Change them to something unique.


@@ -182,6 +197,28 @@ Update software with distribution repository.
 : $ sudo apt upgrade -y
 : $ sudo apt dist-upgrade -y
 
 : $ sudo apt upgrade -y
 : $ sudo apt dist-upgrade -y
 

+***** Change time zone
+The time zone should be set to "UTC" for simplicity.
+
+: $ sudo raspi-config
+
+Navigate to ~4 Localisation Options~, ~I2 Change Time Zone~, ~None of the above~, ~UTC~.
+
+***** Update hostname
+A unique hostname is required to uniquely identify the device on the
+network.
+
+Start up the Raspberry Pi Software Configuration Tool by running:
+: $ sudo raspi-config
+
+- Select `2 Network Options`
+- Select `N1 Hostname`
+
+This document recommends a hostname beginning with the prefix:
+: ninfacyzga-1-
+
+An example hostname would be ~ninfacyzga-1-2~.
+

 ***** Install software
 ****** ~unattended-upgrades~
 Make sure to install the ~unattended-upgrades~ package to make sure
 ***** Install software
 ****** ~unattended-upgrades~
 Make sure to install the ~unattended-upgrades~ package to make sure


@@ -201,15 +238,31 @@ Install ~syncthing~ for log file transfer capability.
 
 : $ sudo apt install syncthing
 
 
 : $ sudo apt install syncthing
 

+Enable automatic startup. (See [[https://docs.syncthing.net/users/autostart.html][ref]]).
+
+: $ sudo systemctl enable syncthing@pi.service
+: $ sudo systemctl start syncthing@pi.service
+
+The WebUI of the local instance of syncthing (port 8384) can be
+accessed by running the following command from a separate machine:
+
+: $ ssh -L 127.0.0.1:8390:127.0.0.1:8384 pi@ninfacyzga-1-x
+
+Then, the separate machine should navigate to ~localhost:8390~ in a
+web browser in order to change the ninfacyzga-1 device's
+configuration. The separate machine's Syncthing configuration options
+are accessible via its own web browser via ~localhost:8384~.
+

 ****** ~git~
 ****** ~git~

-Install ~git~ for downloading this repository to the device.
+~git~ facilitates downloading files from this repository to the
+device. It may be installed via:

 
 : $ sudo apt install git
 
 ****** ninfacyzga-01 git repository
 Create the directory ~/git-OC/~ . Within this directory, run the
 following commands to clone the ~ninfacyzga-01~ git repository:
 
 : $ sudo apt install git
 
 ****** ninfacyzga-01 git repository
 Create the directory ~/git-OC/~ . Within this directory, run the
 following commands to clone the ~ninfacyzga-01~ git repository:

-: $ git clone https://gitlab.com/baltakatei/ninfacyzga-01.git
+: $ git clone https://zdv2.bktei.com/gitweb/ninfacyzga-01.git

 : $ cd ninfacyzga-01
 
 Check out the ~develop~ branch (if the latest changes are desired over
 : $ cd ninfacyzga-01
 
 Check out the ~develop~ branch (if the latest changes are desired over


@@ -217,17 +270,22 @@ those of the ~master~ branch).
 : $ git checkout --track origin/develop
 
 ****** ~age~
 : $ git checkout --track origin/develop
 
 ****** ~age~

+~age~ is required for encrypting data at rest.
+

 Place ~age~ binary (the one compiled for ARM CPU architecture for
 Linux) in ~$HOME/.local/bin~. A copy of binary may be found within the
 ~exec~ directory.
 
 Place ~age~ binary (the one compiled for ARM CPU architecture for
 Linux) in ~$HOME/.local/bin~. A copy of binary may be found within the
 ~exec~ directory.
 

+: $ mkdir ~/.local/bin
+: $ cp exec/age ~/.local/bin/
+

 ***** Disable Swap File
 ***** Disable Swap File

-Since standard Raspbian 10 (Buster) install involves copying
-unencrypted file system image to SD card which is mounted by the
-Raspberry Pi, system memory may be written to disk in the form of a
-Swap file as described [[https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/][here]]. In order to reduce the chance that
-location log data is ever written to disk, swap file functionality
-must be disabled[fn:ideaheap_20130731_disableswap].
+Since standard Raspberry OS 10 install involves copying unencrypted
+file system image to SD card which is mounted by the Raspberry Pi,
+system memory may be written to disk in the form of a Swap file as
+described [[https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/][here]]. In order to reduce the chance that location log data
+is ever written to disk, swap file functionality must be
+disabled[fn:ideaheap_20130731_disableswap].

 
 Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
 disabled persistently[fn:rpf_20190702_disableswappersist] by running
 
 Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
 disabled persistently[fn:rpf_20190702_disableswappersist] by running