Web Interface
peach-web provides a web interface for monitoring and interacting with the PeachCloud device. This allows administration of the single-board computer (ie. Raspberry Pi) running PeachCloud, as well as the ssb-server and related plugins.
Design
peach-web is written primarily in Rust and presents a web interface for interacting with the device. The stack currently consists of Rocket (Rust web framework), Tera (Rust template engine inspired by Jinja2 and the Django template language), HTML, CSS and JavaScript. Additional functionality is provided by JSON-RPC clients for the peach-network and peach-stats microservices.
HTML is rendered server-side. Request handlers call JSON-RPC microservices and serve HTML and assets. A JSON API is exposed for remote calls and dynamic client-side content updates via vanilla JavaScript following unobstructive design principles. A basic Websockets server is included, though is not currently utilised. Each Tera template is passed a context object. In the case of Rust, this object is a struct and must implement Serialize. The fields of the context object are available in the context of the template to be rendered.
Directory Tree
.
├── Cargo.lock
├── Cargo.toml
├── docs
│ ├── api_docs.md
│ ├── FEATURES.md
│ ├── js_docs.md
│ └── RESOURCES.md
├── .gitignore
├── README.md
├── Rocket.toml
├── src
│ ├── device.rs
│ ├── error.rs
│ ├── lib.rs
│ ├── main.rs
│ ├── network.rs
│ ├── stats.rs
│ ├── structs.rs
│ ├── tests.rs
│ └── ws.rs
├── static
│ ├── css
│ │ ├── peachcloud.css
│ │ └── _variables.css
│ ├── favicon.ico
│ ├── icons
│ ├── js
│ │ ├── network_card.js
│ │ ├── shutdown_menu.js
│ └── templates
│ ├── base.html.tera
│ ├── device.html.tera
│ ├── index.html.tera
│ ├── nav.html.tera
│ ├── network_add.html.tera
│ ├── network_card.html.tera
│ ├── network_detail.html.tera
│ ├── network_list.html.tera
│ ├── network_modify.html.tera
│ ├── not_found.html.tera
│ └── shutdown.html.tera
WEB ROUTES (src/routes.rs)
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/ | GET | Home | |
/device | GET | Device status overview | |
/device/reboot | GET | Reboot device | |
/device/shutdown | GET | Shutdown device | |
/login | GET | Login form | |
/network | GET | Network status overview | |
/network/ap/activate | GET | Activate WiFi access point mode | |
/network/wifi | GET | List of networks | |
/network/wifi?<ssid> | GET | ssid | Details of a single network |
/network/wifi/activate | GET | Activate WiFi client mode | |
/network/wifi/add | GET | ssid (optional - prepopulation value of SSID in form) | Add a WiFi network |
/network/wifi/add | POST | ssid & pass | Submit form to add a WiFi network |
/network/wifi/connect | POST | ssid | Connect to the given WiFi network |
/network/wifi/disconnect | POST | ssid | Disconnect from currently associated WiFi network |
/network/wifi/forget | POST | ssid | Submit form to forget a saved WiFi network |
/network/wifi/modify?<ssid> | GET | ssid | Form for updating a WiFi network password |
/network/wifi/modify | POST | ssid & pass | Submit form to update a WiFi network password |
/network/wifi/usage | GET | Network data usage values and a form to update alert thresholds | |
/network/wifi/usage | POST | rx_warn, rx_cut, tx_warn, tx_cut, rx_warn_flag, rx_cut_flag, tx_warn_flag, tx_cut_flag | Submit form to update alert thresholds & set flags |
/network/wifi/usage/reset | GET | Reset the stored network data usage total to zero | |
/shutdown | GET | Shutdown menu |
JSON API (src/json_api.rs)
All JSON API calls are prefixed by /api/v1/. This has been excluded from the table below to keep the table compact.
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
device/reboot | POST | Reboot device | |
device/shutdown | POST | Shutdown device | |
network/activate_ap | POST | Activate WiFi access point mode | |
network/activate_client | POST | Activate WiFi client mode | |
network/ip | GET | Returns IP address values for wlan0 & ap0 interfaces | |
network/rssi | GET | Returns RSSI for connected WiFi network | |
network/ssid | GET | Returns SSID for connected WiFi network | |
network/state | GET | Returns state of wlan0 & ap0 interfaces | |
network/status | GET | Returns status object for connected WiFi network | |
network/wifi | GET | Returns scan results for in-range access-points | |
network/wifi | POST | ssid & pass | Submit SSID & password to create new WiFi connection |
network/wifi/connect | POST | ssid | Submit SSID to connect to a given WiFi network |
network/wifi/disconnect | POST | ssid | Disconnect from the currently associated WiFi network |
network/wifi/forget | POST | ssid | Submit SSID to delete credentials for given WiFi network |
network/wifi/modify | POST | ssid & pass | Submit SSID & password to update the credentials for given WiFi network |
/network/wifi/usage | POST | rx_warn, rx_cut, tx_warn, tx_cut, rx_warn_flag, rx_cut_flag, tx_warn_flag, tx_cut_flag | Submit form to update alert thresholds & set flags |
/network/wifi/usage/reset | POST | Reset network data usage total | |
ping | GET | Returns pong! if peach-web is running | |
ping/network | GET | Returns pong! if peach-network microservice is running | |
ping/oled | GET | Returns pong! if peach-oled microservice is running | |
ping/stats | GET | Returns pong! if peach-stats microservice is running |
Environment
The web application deployment mode is configured with the ROCKET_ENV environment variable:
export ROCKET_ENV=stage
Other deployment modes are dev and prod. Read the Rocket Environment Configurations docs for further information.
The WebSocket server port can be configured with PEACH_WEB_WS environment variable:
export PEACH_WEB_WS=2333
When not set, the value defaults to 5115.
Logging is made available with env_logger:
export RUST_LOG=info
Other logging levels include debug, warn and error.
Setup
Clone this repo:
git clone https://github.com/peachcloud/peach-web.git
Move into the repo and compile:
cd peach-web
cargo build --release
Run the tests:
cargo test
Run the binary:
./target/release/peach-web
Note: Networking functionality requires peach-network microservice to be running.
Debian Packaging
A systemd service file and Debian maintainer scripts are included in the debian directory, allowing peach-web to be easily bundled as a Debian package (.deb). The cargo-deb crate can be used to achieve this.
Install cargo-deb:
cargo install cargo-deb
Move into the repo:
cd peach-web
Build the package:
cargo deb
The output will be written to target/debian/peach-web_0.3.0_arm64.deb (or similar).
Install the package as follows:
sudo dpkg -i target/debian/peach-web_0.3.0_arm64.deb
The service will be automatically enabled and started.
Uninstall the service:
sudo apt-get remove peach-web
Remove configuration files (not removed with apt-get remove):
sudo apt-get purge peach-web
Licensing
AGPL-3.0