diff --git a/peach-web/README.md b/peach-web/README.md index e8956cf6..f8185cdd 100644 --- a/peach-web/README.md +++ b/peach-web/README.md @@ -12,62 +12,30 @@ The peach-web stack currently consists of [Rocket](https://rocket.rs/) (Rust web _Note: This is a work-in-progress._ -### WEB ROUTES (`src/routes.rs`) +### Setup -| 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?` | 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?` | 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 | -| `/network/dns` | GET | | View current DNS configurations | -| `/network/dns` | POST | | Modify DNS configurations | -| `/shutdown` | GET | | Shutdown menu | +Clone the `peach-workspace` repo: -### JSON API (`src/json_api.rs`) +`git clone https://git.coopcloud.tech/PeachCloud/peach-workspace` -All JSON API calls are prefixed by `/api/v1/`. This has been excluded from the table below to keep the table compact. +Move into the repo and compile: -| 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 | -| `dns/configure` | POST | | Modify dns configurations | +`cd peach-workspace/peach-web` +`cargo build --release` + +Run the tests: + +`cargo test` + +Move back to the `peach-workspace` directory: + +`cd ..` + +Run the binary: + +`./target/release/peach-web` + +_Note: Networking functionality requires peach-network microservice to be running._ ### Environment @@ -75,13 +43,7 @@ The web application deployment mode is configured with the `ROCKET_ENV` environm `export ROCKET_ENV=stage` -Other deployment modes are `dev` and `prod`. Read the [Rocket Environment Configurations docs](https://rocket.rs/v0.4/guide/configuration/#environment) 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`. +Other deployment modes are `dev` and `prod`. Read the [Rocket Environment Configurations docs](https://rocket.rs/v0.5-rc/guide/configuration/#environment-variables) for further information. Logging is made available with `env_logger`: @@ -89,27 +51,6 @@ Logging is made available with `env_logger`: 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](https://crates.io/crates/cargo-deb) can be used to achieve this. @@ -144,7 +85,7 @@ Remove configuration files (not removed with `apt-get remove`): ### Design -`peach-web` is built on the Rocket webserver and Tera templating engine. It presents a web interface for interacting with the device. 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). 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. +`peach-web` is built on the Rocket webserver and Tera templating engine. It presents a web interface for interacting with the device. 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 plain JavaScript following unobstructive design principles). 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. ### Licensing