peach-workspace/peach-web/README.md

117 lines
4.1 KiB
Markdown
Raw Normal View History

2021-08-06 17:58:40 +00:00
# peach-web
2021-11-23 10:30:24 +00:00
[![Build Status](https://travis-ci.com/peachcloud/peach-web.svg?branch=master)](https://travis-ci.com/peachcloud/peach-web) ![Generic badge](https://img.shields.io/badge/version-0.4.12-<COLOR>.svg)
2021-08-06 17:58:40 +00:00
## Web Interface for PeachCloud
**peach-web** provides a web interface for the PeachCloud device. It serves static assets and exposes a JSON API for programmatic interactions.
Initial development is focused on administration of the device itself, beginning with networking functionality, with SSB-related administration to be integrated at a later stage.
The peach-web stack currently consists of [Rocket](https://rocket.rs/) (Rust web framework), [Tera](http://tera.netlify.com/) (Rust template engine), HTML, CSS and JavaScript.
_Note: This is a work-in-progress._
2021-11-16 06:43:04 +00:00
### Setup
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
Clone the `peach-workspace` repo:
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
`git clone https://git.coopcloud.tech/PeachCloud/peach-workspace`
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
Move into the repo and compile:
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
`cd peach-workspace/peach-web`
`cargo build --release`
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
Run the tests:
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
`cargo test`
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
Move back to the `peach-workspace` directory:
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
`cd ..`
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
Run the binary:
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
`./target/release/peach-web`
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
_Note: Networking functionality requires peach-network microservice to be running._
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
### Environment
2021-08-06 17:58:40 +00:00
2021-11-25 09:15:39 +00:00
**Deployment Mode**
2021-11-23 10:30:24 +00:00
2021-11-16 06:43:04 +00:00
The web application deployment mode is configured with the `ROCKET_ENV` environment variable:
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
`export ROCKET_ENV=stage`
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
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.
2021-08-06 17:58:40 +00:00
2021-11-25 09:15:39 +00:00
**Authentication**
Authentication is disabled in `development` mode and enabled by default when running the application in `production` mode. It can be disabled by setting the `ROCKET_DISABLE_AUTH` environment variable to `true`:
`export ROCKET_DISABLE_AUTH=true`
**Logging**
2021-11-16 06:43:04 +00:00
Logging is made available with `env_logger`:
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
`export RUST_LOG=info`
2021-08-06 17:58:40 +00:00
2021-11-16 06:43:04 +00:00
Other logging levels include `debug`, `warn` and `error`.
2021-08-06 17:58:40 +00:00
### 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.
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`
### Design
2021-11-16 06:43:04 +00:00
`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.
2021-08-06 17:58:40 +00:00
2022-01-11 23:03:07 +00:00
### Configuration
Configuration variables are stored in /var/lib/peachcloud/config.yml.
Peach-web also updates this file when changes are made to configurations via
the web interface. peach-web has no database, so all configurations are stored in this file.
#### Dynamic DNS Configuration
Most users will want to use the default PeachCloud dynamic dns server.
If the config dyn_use_custom_server=false, then default values will be used.
If the config dyn_use_custom_server=true, then a value must also be set for dyn_dns_server_address (e.g. "http://peachdynserver.commoninternet.net").
This value is the URL of the instance of peach-dyndns-server that requests will be sent to for domain registration.
Using a custom value can here can be useful for testing.
2021-08-06 17:58:40 +00:00
### Licensing
AGPL-3.0