From ff2305ee58d183eddd5a0efa3ba93e15abedf05a Mon Sep 17 00:00:00 2001 From: notplants Date: Mon, 29 Mar 2021 11:18:03 +0200 Subject: [PATCH 1/2] Add setup guides --- src/SUMMARY.md | 4 +- src/quick_deployment.md | 109 ---------------------- src/setup/index.md | 8 ++ src/setup/install_from_debian.md | 149 +++++++++++++++++++++++++++++++ src/setup/quick_deployment.md | 93 +++++++++++++++++++ 5 files changed, 253 insertions(+), 110 deletions(-) delete mode 100644 src/quick_deployment.md create mode 100644 src/setup/index.md create mode 100644 src/setup/install_from_debian.md create mode 100644 src/setup/quick_deployment.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3d6e554..6d8f8c8 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,7 +4,9 @@ - [Story](./introduction/story.md) - [Design Principles](./introduction/design_principles.md) - [Features](./introduction/features.md) -- [Quick Deployment](./quick_deployment.md) +- [Setup](./setup/index.md) + - [Quick Deployment](./setup/quick_deployment.md) + - [Install From Debian](./setup/install_from_debian.md) - [Hardware](./hardware/index.md) - [Requirements](./hardware/requirements.md) - [GPIO Pinout](./hardware/gpio_pinout.md) diff --git a/src/quick_deployment.md b/src/quick_deployment.md deleted file mode 100644 index b64adb1..0000000 --- a/src/quick_deployment.md +++ /dev/null @@ -1,109 +0,0 @@ -# Quick Deployment - -[![GitHub logo](/assets/github_logo.png "peach-config GitHub repository")](https://github.com/peachcloud/peach-config) - -The instructions, configuration files and scripts referred to in this section can all be found in the [peach-config repo](https://github.com/peachcloud/peach-config). - -## Prerequisite Steps - -Download the latest Debian Buster preview image for RPi3 and flash it to an SD card. - -Note: Be sure to use the correct device location in the `dd` command, otherwise you risk wiping another connected USB device. `sudo dmesg | tail` can be run after plugging in the SD card to determine the correct device location: - -```bash -wget https://raspi.debian.net/verified/20200831_raspi_3.img.xz -xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/mmcblk0 bs=64k oflag=dsync status=progress -``` - -On Mac OS, use the following command to flash the SD card: - -`xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdcarddisc` - -Alternatively, use [Etcher](https://www.balena.io/etcher/). - -Note: if the above image link stops working, you can find the complete list of Raspberry Pi Debian images [here](https://raspi.debian.net/tested-images/). - -## Setup - -Quick setup commands to connect to a local WiFi network over the `wlan0` interface (assuming `eth0` connection is not possible): - -```bash -# username -root -# password (by default raspberry debian requires no password, so we set the password for root here) -passwd -# set interface up (run command twice if you receive 'link is not ready' error on first try) -ip link set wlan0 up -# append ssid and password for wifi access point -wpa_passphrase > /etc/wpa_supplicant/wpa_supplicant.conf -# open wpa_supplicant.conf -nano /etc/wpa_supplicant/wpa_supplicant.conf -``` - -[ Add the following two lines to top of file ] - -```plaintext -ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wpactrl-user -update_config=1 -``` - -[ Save and exit ] - -```bash -# open network interfaces config -nano /etc/network/interfaces -``` - -[ Add the following lines to the file ] - -```plaintext -auto lo -iface lo inet loopback - -allow-hotplug wlan0 -auto wlan0 -iface wlan0 inet dhcp - wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf -``` - -[ Save and exit ] - -`reboot now` - -[ Pi should now be connected to the WiFi network ] - -## Scripts - -The `setup_dev_env.py` script can be executed once your Pi is internet-connected and `git` and `python` have been installed. - -```bash -apt update -apt install git python -git clone https://github.com/peachcloud/peach-config.git -cd peach-config -# run the script with --i2c and --rtc flags to configure -python scripts/setup_dev_env.py -i -r ds3231 -``` - -Running the script with the `-h` flag shows the help menu: - -```bash -usage: setup_dev_env.py [-h] [-i] [-r {ds1307,ds3231}] user - -positional arguments: - user username for the default user account - -optional arguments: - -h, --help show this help message and exit - -i, --i2c configure i2c - -r {ds1307,ds3231}, --rtc {ds1307,ds3231} - configure real-time clock -``` - -A `` argument must be supplied to create a new system user. You will be prompted to enter a password for your newly created user. - -The script also allows optional configuration of I2C and real-time clock (RTC) modules. I2C configuration is necessary for the OLED display and physical interface to work correctly. RTC configuration is required for the real-time clock to work correctly. When passing the `-r` flag, the type of real-time clock module must be included (either ds1307 or ds3231). Selecting real-time clock configuration will not work if the I2C flag is not selected (in other words, the real-time clock requires I2C). - -Run the script as follows for a full installation and configuration with I2C and the ds3231 RTC module (username in this case is `peach`): - -`python scripts/setup_dev_env.py -i -r ds3231 peach` diff --git a/src/setup/index.md b/src/setup/index.md new file mode 100644 index 0000000..6d1a543 --- /dev/null +++ b/src/setup/index.md @@ -0,0 +1,8 @@ +# Setup + +The recommended way to install PeachCloud is from a PeachCloud disc image, +you can find a guide [here](./quick_deployment.md). + +Alternatively, you can also install PeachCloud onto a device already running Debian, +using the guide [here]('./install_from_debian.md'). + diff --git a/src/setup/install_from_debian.md b/src/setup/install_from_debian.md new file mode 100644 index 0000000..491cb2f --- /dev/null +++ b/src/setup/install_from_debian.md @@ -0,0 +1,149 @@ +# Installation From Debian Disc Image + +You can also setup PeachCloud by installing Debian onto an sd card, and then installing and running peach-config. +This is essentially how the PeachCloud disc image is created (see [peach-img-builder](https://github.com/peachcloud/peach-img-builder)). + +Here are the steps for installing peach-config on Debian. + +## Step 1: Flash The SD Card + +Download the latest Debian Buster preview image for RPi3 and flash it to an SD card. + +_Note:_ Be sure to use the correct device location in the `dd` command, otherwise you risk wiping another connected USB device. `sudo dmesg | tail` can be run after plugging in the SD card to determine the correct device location: + +```bash +wget https://raspi.debian.net/verified/20200831_raspi_3.img.xz +xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdb bs=64k oflag=dsync status=progress +``` + +On Mac OS, use the following command to flash the SD card: + +`xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdcarddisc` + +Alternatively, use [Etcher](https://www.balena.io/etcher/). + +_Note:_ If the above image link stops working, you can find the complete list of Raspberry Pi Debian images [here](https://raspi.debian.net/tested-images/). + + +## Step 2: Connect To The Internet + +Use the following commands to connect to a local WiFi network over the `wlan0` interface (assuming `eth0` connection is not possible): + +```bash +# username +root +# password (by default raspberry debian requires no password, so we set the password for root here) +passwd +# set interface up (run command twice if you receive 'link is not ready' error on first try) +ip link set wlan0 up +# append ssid and password for wifi access point +wpa_passphrase > /etc/wpa_supplicant/wpa_supplicant.conf +# open wpa_supplicant.conf +nano /etc/wpa_supplicant/wpa_supplicant.conf +``` + +[ Add the following two lines to top of file ] + +```plaintext +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +``` + +[ Save and exit ] + +```bash +# open network interfaces config +nano /etc/network/interfaces +``` + +[ Add the following lines to the file ] + +```plaintext +auto lo +iface lo inet loopback + +auto eth0 +allow-hotplug eth0 +iface eth0 inet dhcp + +auto wlan0 +allow-hotplug wlan0 +iface wlan0 inet dhcp + wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf +``` + + +[ Save and exit ] + +`reboot now` + +[ Pi should now be connected to the WiFi network ] + +## Step 3: Install PeachCloud + + +You can run the following commands to add the PeachCloud apt repository and install PeachCloud: +``` bash +echo "deb http://apt.peachcloud.org/ buster main" > /etc/apt/sources.list.d/peach.list +wget -O - http://apt.peachcloud.org/pubkey.gpg | sudo apt-key add - +apt-get update +apt-get install -y python3-peach-config +peach-config setup -i -n -d peach +``` + + +#### Connecting + +Once the setup script has been run, connect to the system remotely over the local network using ssh or mosh: + +`ssh user@peach.local` or `mosh user@peach.local` + +There is a file with detailed instructions on how to connect via a direct ethernet cable located in `docs/direct-ethernet-setup.md` + + +#### Network + +Networking is handled by `wpa_supplicant` and `systemd-networkd`. + +The RPi connects to other networks with the `wlan0` interface and deploys an access point on the `ap0` interface. Only one of these modes is active at a time (client or access point). The RPi boots in client mode by default. + +To switch to access point mode: + +`sudo systemctl start wpa_supplicant@ap0.service` + +To switch to client mode: + +`sudo systemctl start wpa_supplicant@wlan0.service` + +_Note:_ No stopping of services or rebooting is required. + +To enable access point mode on boot: + +```bash +sudo systemctl disable wpa_supplicant@wlan0.service +sudo systemctl enable wpa_supplicant@ap0.service +``` + +A standalone networking configuration script is included in this repository (`scripts/setup_networking.py`). Network-related documentation can also be found in this repository (`docs`). + +This repository also contains a script for automatically starting an access point on `ap0` if the `wlan0` service is active but not connected (`scripts/ap_auto_deploy.sh`). The executable script is installed at `/usr/local/bin/ap_auto_deploy` and can either be run once-off or scheduled for repeated execution using a `systemd` service file and timer file (`conf/network/ap-auto-deploy.service` and `conf/network/ap-auto-deploy.timer`). When the timer is enabled for repeated execution, the script is automatically run 60 seconds after boot and every 180 seconds after that. + +To stop and disable the access point auto deploy service: + +```bash +sudo systemctl stop ap-auto-deploy.timer +sudo systemctl disable ap-auto-deploy.timer +``` + + +## Troubleshooting + +You may encounter DNS issues if your system time is inaccurate. Please refer to this [StackExchange answer](https://unix.stackexchange.com/a/570382/450882) for details. The steps to remedy the situation are offered here in brief: + +```bash +sudo -Es +timedatectl set-ntp 0 +# edit this line according to your current date & time +timedatectl set-time "2021-01-13 11:37:10" +timedatectl set-ntp 1 +exit diff --git a/src/setup/quick_deployment.md b/src/setup/quick_deployment.md new file mode 100644 index 0000000..e6bd9af --- /dev/null +++ b/src/setup/quick_deployment.md @@ -0,0 +1,93 @@ +# Quick Deployment + +This guide contains the steps for setting up PeachCloud on a raspberry pi using a PeachCloud disc image. + +## Step 1: Flash The SD Card + +Download the latest PeachCloud image from http://releases.peachcloud.org and flash it to an SD card. + +_Note:_ Be sure to use the correct device location in the `dd` command, otherwise you risk wiping another connected USB device. `sudo dmesg | tail` can be run after plugging in the SD card to determine the correct device location: + +```bash +wget http://releases.peachcloud.org/peach-imgs/20210225/20210225_peach_raspi3.img +sudo dd 20210225_peach_raspi3.img of=/dev/sdb bs=64k oflag=dsync status=progress +``` + +On Mac OS, use the following command to flash the SD card: + +`xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdcarddisc` + +Alternatively, use [Etcher](https://www.balena.io/etcher/). + +Your SD card now has a complete PeachCloud installation on it and is ready to use. + + +## Step 2: Connecting To The Internet + +#### Via access point + +When PeachCloud first starts it will start in access point mode. From your laptop or phone look for a wifi network +named "peach" and connect to it using the password "cloudless". + +Once you are connected, in your browser navigate to peach.local, +which should load the PeachCloud web interface. + +From the PeachCloud web interface, you can connect to the internet: +1. Settings -> Add Wifi Network (add your wifi credentials) +2. Click "Enable Wifi" + +This will take PeachCloud out of access point mode and into client mode. +If you connect to the same WIFI network as the peach, +you should now also be able to access the web interface via peach.local. + + +#### Via screen + +If you connect a screen and keyboard to the raspberry pi, you can login to the pi directly using +the following username and password: +``` +username: peach +password: peachcloud +``` + +You can then edit `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf` +and add your wifi credentials to the file: + +``` +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +network={ + ssid="your_ssid" + psk="your_wifi_password" +} +``` + +#### Via sd card + +If you create a file on the RASPIFIRM partition of the sdcard named `wpa_supplicant.conf`, +while PeachCloud is booting this file will be copied to `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf` +and used for connecting to wifi. + +This is a third way you can get the PeachCloud connected to the internet. + +``` +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +network={ + ssid="your_ssid" + psk="your_wifi_password" +} +``` + + +## Step 3: Getting Started + +You can then continue to configure your PeachCloud via the web interface (accessed by peach.local), +through the physical interface, or through ssh (`ssh peach@peach.local`). + +There is a file with detailed instructions on how to connect via a direct ethernet cable located [here](/software/operating_system/networking.md) + +TODO: link to PeachCloud caretaker guides for more detailed info on how to configure the device. + +When sshed into the device you can also configure and update the device using the peach-config CLI tool. +Documentation on how to use peach-config can be found [here](https://github.com/peachcloud/peach-config). \ No newline at end of file From 32baf1ec645c6a003d7b62687a23fd2a08e6a37d Mon Sep 17 00:00:00 2001 From: notplants Date: Mon, 29 Mar 2021 12:04:43 +0200 Subject: [PATCH 2/2] Add sections for peach-package-builder and peach-img-builder --- src/SUMMARY.md | 4 +- src/software/distribution/image_building.md | 23 ++++++++ src/software/distribution/index.md | 5 ++ src/software/distribution/packaging.md | 59 +++++++++++++++++++++ src/software/packaging.md | 29 ---------- 5 files changed, 90 insertions(+), 30 deletions(-) create mode 100644 src/software/distribution/image_building.md create mode 100644 src/software/distribution/index.md create mode 100644 src/software/distribution/packaging.md delete mode 100644 src/software/packaging.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 6d8f8c8..ff4c431 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -29,7 +29,9 @@ - [Web Interface](./software/web_interface.md) - [Pattern Library](./software/pattern_library.md) - [Compilation](./software/compilation.md) - - [Packaging](./software/packaging.md) + - [Distribution](./software/distribution/index.md) + - [Packaging](./software/distribution/packaging.md) + - [Image Building](./software/distribution/image_building.md) - [Configuration](./software/configuration.md) - [Contributor's Guide](./contributors_guide.md) - [Licensing](./licensing.md) diff --git a/src/software/distribution/image_building.md b/src/software/distribution/image_building.md new file mode 100644 index 0000000..02f575b --- /dev/null +++ b/src/software/distribution/image_building.md @@ -0,0 +1,23 @@ +# PeachCloud Image Building + +PeachCloud microservices are packaged and installed onto a custom disc image running Debian, +using [peach-img-builder](https://github.com/peachcloud/peach-img-builder), a utility which runs on the PeachVPS. + +peach-img-builder is based off of a fork of [a vmdb2 script used for creating a Debian image for Raspberry pi](https://salsa.debian.org/raspi-team/image-specs/-/tree/master). + +peach-img-builder creates a working Debian image, +adds apt.peachcloud.org as an apt source, +and then uses peach-config to install all PeachCloud microservices. + + +## Publishing A New Image + +To build a new peach image, compress the image, and publish it to http://releases.peachcloud.org/, on the VPS run: +```shell +cd /srv/peachcloud/automation/peach-img-builder +./build.sh +``` + +This script additionally creates a manifest file listing the versions of all PeachCloud microservices included in the image. +The image, log of the build, and the manifest, are all copied to folder named with the current date, +in `/var/www/releases.peachcloud.org/html/peach-imgs/`. \ No newline at end of file diff --git a/src/software/distribution/index.md b/src/software/distribution/index.md new file mode 100644 index 0000000..5d368cf --- /dev/null +++ b/src/software/distribution/index.md @@ -0,0 +1,5 @@ +# Distribution + +PeachCloud is distributed as a set of Debian [packages](./packaging.md) and as a disc image, +which can be downloaded from http://releases.peachcloud.org. + diff --git a/src/software/distribution/packaging.md b/src/software/distribution/packaging.md new file mode 100644 index 0000000..2fe6f22 --- /dev/null +++ b/src/software/distribution/packaging.md @@ -0,0 +1,59 @@ +# Debian Packaging + +The microservices comprising the PeachCloud software suite are packaged for easy deployment and maintainance on Debian and derivative operating systems. + +Each microservice repository includes a `debian` directory which includes a `systemd` service file. `deb` packages are created using the `cargo-deb` tool ([crate](https://crates.io/crates/cargo-deb)), which installs the systemd unit file to the correct location. + +**Install cargo-deb:** + +`cargo install cargo-deb` + +**Create the package:** + +`cargo deb --target aarch64-unknown-linux-gnu` + +Note: the correct linker, objcopy and strip parameters must be defined in `~/.cargo/config` for the above command to execute successfully. Visit the [Compilation](/software/compilation.md) page and look under 'Configure the linker' for more details. + +**Install the package:** + +`sudo dpkg -i peach-network_0.1.0_arm64.deb` + +The service will be automatically enabled and started. + +**Uninstall the package:** + +`sudo apt-get remove peach-network` + +**Remove configuration files** (not removed with `apt-get remove`): + +`sudo apt-get purge peach-network` + + +# Freight Repository + +[peach-package-builder](https://github.com/peachcloud/peach-package-builder) is a set of python scripts that run on the VPS and build all the PeachCloud microservice +packages and add them to the [Freight](https://github.com/rcrowley/freight) repository at apt.peachcloud.org. + +Documentation for peach-package-builder +cand be found [here](https://github.com/peachcloud/peach-package-builder). + + +# Installing packages from apt.peachcloud.org + +To add the PeachCloud Debian package archive as an apt source, run the following commands from your Pi: + +``` +echo "deb http://apt.peachcloud.org/ buster main" > /etc/apt/sources.list.d/peach.list +wget -O - http://apt.peachcloud.org/pubkey.gpg | sudo apt-key add - +``` + +You can then install peach packages using apt: + +``` +sudo apt-get update +sudo apt-get install peach-oled +``` + + + + diff --git a/src/software/packaging.md b/src/software/packaging.md deleted file mode 100644 index 0e36272..0000000 --- a/src/software/packaging.md +++ /dev/null @@ -1,29 +0,0 @@ -# Debian Packaging - -The microservices comprising the PeachCloud software suite are packaged for easy deployment and maintainance on Debian and derivative operating systems. - -Each microservice repository includes a `debian` directory which includes a `systemd` service file and Debian maintainer scripts, including `postinst`, `postrm` and `prerm` scripts. These scripts define behavior for installing and uninstalling the respective services. `deb` packages are created using the `cargo-deb` tool ([crate](https://crates.io/crates/cargo-deb)). - -**Install cargo-deb:** - -`cargo install cargo-deb` - -**Create the package:** - -`cargo deb --target aarch64-unknown-linux-gnu` - -Note: the correct linker, objcopy and strip parameters must be defined in `~/.cargo/config` for the above command to execute successfully. Visit the [Compilation](/software/compilation.md) page and look under 'Configure the linker' for more details. - -**Install the package:** - -`sudo dpkg -i peach-network_0.1.0_arm64.deb` - -The service will be automatically enabled and started. - -**Uninstall the package:** - -`sudo apt-get remove peach-network` - -**Remove configuration files** (not removed with `apt-get remove`): - -`sudo apt-get purge peach-network`