Max Fowler
GitHub
commit
039ffeff9f
|
|
@ -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)
|
||||
|
|
@ -27,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)
|
||||
|
|
|
|||
|
|
@ -1,109 +0,0 @@
|
|||
# Quick Deployment
|
||||
|
||||
[](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 <SSID> <PASS> > /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 <USER>
|
||||
```
|
||||
|
||||
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 `<USER>` 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`
|
||||
|
|
@ -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').
|
||||
|
||||
|
|
@ -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 <SSID> <PASS> > /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
|
||||
|
|
@ -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).
|
||||
|
|
@ -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/`.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -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`
|
||||
Loading…
Reference in New Issue