Merge pull request #203 from towercomputers/dev

v0.4.0

docs/mkdocs.yml

@@ -1,5 +1,7 @@
-site_name: TowerOS
+site_name: Documentation
 site_url: https://toweros.org
+repo_url: https://github.com/towercomputers/toweros/
+repo_name: TowerOS
 docs_dir: src
 markdown_extensions:
  - attr_list
@@ -11,6 +13,13 @@ theme:
  - navigation.expand
  - navigation.instant
  - navigation.instant.prefetch
+ logo: img/tower-logo.png
+ favicon: img/favicon.ico
+ icon:
+ repo: fontawesome/brands/github
+ font: false
+extra_css:
+ - css/towerdoc.css
 nav:
  - Getting Started:
  - Introduction: index.md
@@ -19,14 +28,18 @@ nav:
  - Usage:
  - Using TowerOS: usage.md
  - Guides: guides.md
+ - Tower CLI Manual: manual.md
  - Security:
  - Security: security.md
  - Secure Boot: secure-boot.md
  - Technical:
  - Whitepaper: "TowerOS Whitepaper.pdf"
  - Implementation: implementation.md
- - Development: development.md
  - GitHub Repository: https://github.com/towercomputers/toweros
+ - Development:
+ - Developer Environment: dev-environment.md
+ - Building TowerOS: build-toweros.md
+ - QA Script: qa-script.md
 
 extra:
  generator: false

docs/src/development.md → docs/src/build-toweros.md

@@ -1,48 +1,3 @@
-## Set Up Development Environment
-
-### Connect to internet
-
-To connect the thin client to the Internet you must:
-
-1. Provision a `router`.
-1. Set the gateway on the thin client to `192.168.2.1` (the router's IP address):
-
- The file `/etc/network/interfaces` must contain the following:
-
-  auto lo
-  iface lo inet loopback
-  auto eth0
-  iface eth0 inet static
-  address 192.168.2.100/24
-  gateway 192.168.2.1
-  auto eth1
-  iface eth1 inet static
-  address 192.168.3.100/24
-
-1. Set the DNS server on the thin client:
-
- The file `/etc/resolv.conf` must contain the following:
-
-  nameserver 8.8.8.8
-  nameserver 8.8.4.4
-
-1. Restart the network with: `[thinclient]$ sudo rc-service networking restart`
-
-### Configure Git and download Github repository
-
-Configure `git`, download Github repository in `~/towercomputers/toweros` and install `hatch` with:
-
-```
-[thinclient]$ /var/towercomputers/install-dev.sh <git-name> <git-email> <git-private-key-path>
-```
-
-### Use `tower-cli` with `hatch`
-
-```
-[thinclient]$ cd ~/towercomputers/toweros/tower-cli
-[thinclient]$ hatch run tower --help
-```
-
 ## Build TowerOS images
 
 Connect to internet and download Github repository as explained in the first paragraph above.
@@ -102,47 +57,6 @@ Finally delete the container with:
  build-tower-image thinclient
 ```
 
-## Manually QA TowerOS for Thin Client
-
-On first boot:
-
-1. Basic checking
-
- - The “welcome message” should refer to TowerOS.
- - The README, whitepaper and `install-dev.sh` script should be found in `~/`.
- - The `wheel` package and host image should be in `~/.cache/tower/builds`.
- - `$ iptables -L -v` should show firewall rules, and `/var/logs/iptables.log` should contain firewall logs.
- - `lo` and `eth0` should be up (check with `$ ip ad`)
-
-1. Provision an online host:
-
-  [thinclient]$ tower provision router --wlan-ssid <ssid> --wlan-password <password>
-  [thinclient]$ tower provision web --online
-
-1. Provision an offline host:
-
-  [thinclient]$ tower provision office --offline
-
-1. Check system status:
-
-  [thinclient]$ tower status
-
-1. Install a package in an offline host:
-
-  [thinclient]$ tower install office xcalc
-
-1. Install a package in an online host:
-
-  [thinclient]$ tower install web midori
-
-1. Test installed packages:
-
-  [thinclient]$ dbus-launch labwc
-  [thinclient]$ tower run office xcalc
-  [thinclient]$ tower run web midori
-
- Check also if the Xfce Application menu contains shortcuts for installed packages.
-
 ## Build your own custom Thin Client (Linux)
 
 ### Install Dependencies
@@ -206,4 +120,3 @@ Install the `tower` CLI with `pip`:
 ```
 [thinclient]$ python3 -m pip install "tower-cli @ git+https://github.com/towercomputers/toweros.git#subdirectory=tower-cli"
 ```
-

docs/src/css/towerdoc.css

@@ -0,0 +1,7 @@
+:root {
+ --md-primary-fg-color: #111024 !important;
+ --md-primary-fg-color--dark: #111024 !important;
+}
+.md-header__button.md-logo img {
+ height: 2.2rem !important;
+}

docs/src/dev-environment.md

@@ -0,0 +1,44 @@
+## Set Up Development Environment
+
+### Connect to internet
+
+To connect the thin client to the Internet you must:
+
+1. Provision a `router`.
+1. Set the gateway on the thin client to `192.168.2.1` (the router's IP address):
+
+ The file `/etc/network/interfaces` must contain the following:
+
+  auto lo
+  iface lo inet loopback
+  auto eth0
+  iface eth0 inet static
+  address 192.168.2.100/24
+  gateway 192.168.2.1
+  auto eth1
+  iface eth1 inet static
+  address 192.168.3.100/24
+
+1. Set the DNS server on the thin client:
+
+ The file `/etc/resolv.conf` must contain the following:
+
+  nameserver 8.8.8.8
+  nameserver 8.8.4.4
+
+1. Restart the network with: `[thinclient]$ sudo rc-service networking restart`
+
+### Configure Git and download Github repository
+
+Configure `git`, download Github repository in `~/towercomputers/toweros` and install `hatch` with:
+
+```
+[thinclient]$ /var/towercomputers/install-dev.sh <git-name> <git-email> <git-private-key-path>
+```
+
+### Use `tower-cli` with `hatch`
+
+```
+[thinclient]$ cd ~/towercomputers/toweros/tower-cli
+[thinclient]$ hatch run tower --help
+```

docs/src/guides.md

@@ -44,23 +44,49 @@ It is recommended to reserve one of your hosts, for example `storage`, to store
 
 1. Install `pip` in online and offline host
 
-  [thinclient]$ tower install router python3 py3-pip
+  [thinclient]$ tower install web python3 py3-pip
   [thinclient]$ tower install office python3 py3-pip
 
 1. Download package and dependencies in online host
 
-  [thinclient]$ ssh router mkdir mypackages
-  [thinclient]$ ssh router pip download <package_name> -d mypackages 
+  [thinclient]$ ssh web mkdir mypackages
+  [thinclient]$ ssh web pip download <package_name> -d mypackages 
 
 1. Copy package and dependencies to offline host
 
-  [thinclient]$ scp -r router:mypackages office:
+  [thinclient]$ scp -r web:mypackages office:
 
 1. Install `pip` package in offline host
 
   [thinclient]$ ssh office pip install --no-index --find-links="~/mypackages" <package_name>
 
-1. Clean cache in online and offline host
+1. Clean up
 
   [thinclient]$ ssh office rm -rf mypackages
-  [thinclient]$ ssh router rm -rf mypackages
+  [thinclient]$ ssh web rm -rf mypackages
+
+## Install `npm` package in offline host using online host
+
+1. Install `npm` in online and offline host
+
+  [thinclient]$ tower install web npm
+  [thinclient]$ tower install office npm
+
+1. Download package and dependencies in online host
+
+  [thinclient]$ ssh web 'mkdir mypackages && cd mypackages && npm init -y'
+  [thinclient]$ ssh web 'cd mypackages && npm install -B <package_name> && npm pack'
+
+1. Copy package and dependencies to offline host
+
+  [thinclient]$ scp -r web:mypackages/mypackages-1.0.0.tgz office:
+
+1. Install `npm` package in offline host
+
+  [thinclient]$ ssh office tar -xvzf mypackages-1.0.0.tgz
+  [thinclient]$ ssh office 'sudo npm install -g package/node_modules/*/'
+
+1. Clean up
+
+  [thinclient]$ ssh office rm -rf mypackages-1.0.0.tgz package
+  [thinclient]$ ssh web rm -rf mypackages

docs/src/hardware.md

@@ -4,23 +4,23 @@ TowerOS is designed to run on a thin client device and several hosts connected _
 
 
 ## Thin Client Hardware
-The thin client is typically a laptop like the Lenovo X270. The thin client should have an SD card reader for provisioning SD cards that the hosts will boot from if you are using CM4s. (Raspberry Pi 4Bs may be booted from a second USB key, however.) The thin client should also have one or two RJ-45 ports, depending on the number of networks in use. Finally, a dedicated USB key for installing / upgrading the thin client (which will host the boot volume for the device).
+The thin client is typically a laptop like the Lenovo X270. The thin client should have an SD card reader for provisioning SD cards that the hosts will boot from if you are using CM4s. (Raspberry Pi 4/5Bs may be booted from a second USB key, however.) The thin client should also have one or two RJ-45 ports, depending on the number of networks in use. Finally, a dedicated USB key for installing / upgrading the thin client (which will host the boot volume for the device).
 
 
 ## Networking Hardware
-- DeskPi Super6C when using Compute Module 4 Lites *or* Netgear unmanaged switches when using Raspberry Pi 4Bs
+- DeskPi Super6C when using Compute Module 4 Lites *or* Netgear unmanaged switches when using Raspberry Pi 4/5Bs
 - Olimex USB Ethernet Adapter (https://www.olimex.com/Products/USB-Modules/USB-GIGABIT/open-source-hardware)
 - One Ethernet cable per host.
 
 
 ## Host Hardware
-TowerOS currently supports two kinds of host hardware: Raspberry Pi 4B and Compute Module 4 Lite (“CM4” for short). Whereas Raspberry Pi 4Bs must be connected with standalone switch hardware, CM4 modules may be connected with a board like the DeskPi Super6C, which provides for a much more compact form factor for a complete TowerOS system. CM4 modules may easily use M.2 SSDs as their persistent storage _via_ a DeskPi Super6C, and they should therefore perform much better.
+TowerOS currently supports two kinds of host hardware: Raspberry Pi 4B  and 5B and Compute Module 4 Lite (“CM4” for short). Whereas Raspberry Pi 4/5Bs must be connected with standalone switch hardware, CM4 modules may be connected with a board like the DeskPi Super6C, which provides for a much more compact form factor for a complete TowerOS system. CM4 modules may easily use M.2 SSDs as their persistent storage _via_ a DeskPi Super6C, and they should therefore perform much better.
 
 ### Notes
 - The amount of RAM required for each host is heavily dependent on the intended usage pattern. Generally, at least one host should have 8GB of RAM, to run a web browser. For the router host, we recommend having at least 2GB of RAM.
 - Different SD cards and USB keys may have very different performance characteristics. In general, USB keys are much faster than SD cards, and M.2 SSDs are faster still.
 - Each host needs two storage devices to function properly: one for the boot filesystem and another for the root filesystem (the one that contains your applications and data).
- - If your system is based on Raspberry PI 4Bs, you can use either an SD card or a USB key for each file system (It is recommended to use the fastest device for the root file system).
+ - If your system is based on Raspberry PI 4/5Bs, you can use either an SD card or a USB key for each file system (It is recommended to use the fastest device for the root file system).
  - For CM4s with a DeskPi, you must use an SD card for the boot file system and an M.2 SSD for the root file system.
  - The decryption key for the root filesystem is stored directly on the boot device, so the user may remove this device when leaving the host hardware unattended to protect against data theft by physical means.
 
@@ -40,16 +40,17 @@ Using CM4s and the [DeskPi Super6C Board](https://deskpi.com/collections/deskpi-
 - CM4s must use an M.2 SSD for the root partition.
 
 
-### Raspberry Pi 4B
+### Raspberry Pi 4B or 5B
 
 ![Diagram - RPi](img/diagram-rpi.png)
 
-Using standard Raspberry Pi 4Bs for your system is most appropriate if it does not need to be portable, because of the additional bulk of the Raspberry Pi form factor. If you wish to support offline hosts, then you need two unmanaged switches; otherwise, one will do.
+Using standard Raspberry Pi 4/5Bs for your system is most appropriate if it does not need to be portable, because of the additional bulk of the Raspberry Pi form factor. If you wish to support offline hosts, then you need two unmanaged switches; otherwise, one will do.
 
 #### Requirements
 - You will need either two USB keys, or one USB key and one SD card per host. (For best performance, the root partition should reside on a fast USB key, which should be plugged into the blue USB 3.0 port.)
 - If you are using a PoE switch, you will need one PoE hat per host; if not, a USB hub may be used for power delivery.
 - You will need one RTC Clock hat for each offline host.
+- If you use Raspberry Pi 5B and want to boot from USB keys, you must use a 5V5A power supply.
 
 
 ## Hardware for Debugging