documentation: updating readme and adding architecture

Updating documentation and also adding Github related templates

.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: ["https://www.jaredwolff.com/store/nrf9160-feather/", nRF9160 Feather Hardware]

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Version**
+List the versions of all `pyrinas` crates you are using. The easiest way to get
+this information is using `cargo-tree`.
+
+`cargo install cargo-tree`
+(see install here: https://github.com/sfackler/cargo-tree)
+
+Then:
+
+`cargo tree | grep pyrinas`
+
+**Platform**
+The output of `uname -a` (UNIX), or version and 32 or 64-bit (Windows)
+
+**Description**
+Enter your issue details here.
+One way to structure the description:
+
+[short summary of the bug]
+
+I tried this code:
+
+[code sample that causes the bug]
+
+I expected to see this happen: [explanation]
+
+Instead, this happened: [explanation]

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question
+    url: https://community.jaredwolff.com
+    about: 'Please post your question on the community form here
+    https://community.jaredwolff.com.'

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: feature
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

Architecture.md

@@ -0,0 +1,3 @@
+# Architecture
+
+This is forthcoming!

Changelog.md

@@ -4,12 +4,12 @@ All notable changes to this project will be documented in this file. This file a
 
 ## [Unreleased]
 
-### Addded
+### Added
+* Detailed documentation and the skeleton of further detailed how-to in the `docs` folder.
+* Github configuration in `.github`
 
 ### Changed
-* Moved items out of `lib-shared` that aren't necessary. This reduces build time of `pyrinas-cli` significantly (~250+ packages down to 113)
-
-### Removed
+* Moved items out of `lib-shared` that aren't necessary. This reduces build time of `pyrinas-cli` significantly (~250+ packages down to ~115)
 
 ## [0.2.2] - 3/7/2021
 

Readme.md

@@ -1,78 +1,106 @@
-# Pyrinas Server
+# Pyrinas Server & CLI
 
-## Building Development Release
+![Pyrinas Logo](docs/img/pyrinas-logo-crab.png)
 
-```
-cargo build
-```
+For the latest changes, check out the [changelog](Changelog.md). 
 
-Result will be placed in `target/debug`
+Interested how all the pieces fit together? Check out the [architecture](Architecture.md);
 
-## Building Production Release
+## What is Pyrinas Server?
 
-```
-cargo build --release
-```
+Pyrinas, means core or nucleus in Greek (pronounced pir-inas). It's meant to be used as the core server application that conects the [nRF9160 Feather](https://www.jaredwolff.com/store/nrf9160-feather/) and boards like it to the cloud via MQTT. 
 
-The release will be placed in `target/release`. As of this writing
-the bin is called `pyrinas-server`.
+It currently includes the abillity to:
 
+1. Save, publish and facilitate OTA updates via a self-serve HTTP endpoint
+2. Publish sensor data on to a separate InfluxDB instance (Optional)
+3. Act as a secure MQTT broker (thanks to [rumqttd](https://github.com/bytebeamio/rumqtt)) utilitzing Rusts's `native_tls` 
+4. Provides an admin interface using WebSockets for configuring the server, uploading OTA updates, etc. (Optional but recommended)
+5. Tested and works well with reverse proxies like Caddy
 
-## .env file
+Pyrinas is also meant to integrate with the Zephyr module implementation for easy publishing of device data. For more information check out [that repository.](https://github.com/pyrinas-iot/pyrinas-zephyr)
 
-Currently the `.env` file defines what the server does and how it operates. An example can be found in `.env.sample`
+While you can run the example server on it's own, this library ultimately allows you to integrate your own project logic, web servers, frontends and backends. The possiblities are endless!
 
-## Set the log level for `env_logger`
+### What this project is
 
+* Scafolding and pre-tested components for deploying nRF9160 + Zephyr devices with relative ease.
+* Meant for small-medium deployments
 
-The `pyrinas-server` example uses `env_logger`. In order to see output make sure the `RUST_LOG`  environment variable is set
+### What this not
 
-```
-$ export RUST_LOG=info
-```
+* A one-size fit all implementation for all IoT Devices
+* Pre-configurable server with all the features and protocols (not yet at least!)
 
+## Running the example server & CLI
 
-## Generating OTA Manifest file
+While this is more of a library than an executable, you can compile and run the included examples to get an idea of how things work. For more info check out [Using the Example](docs/using-the-example.md) for a step-by-step guide.
 
-In order to generate a manifest file you'll need `deno` installed. On OSX run:
 
-```
-brew install deno
-```
+### Using `cross`
 
-For other platforms see the [documentation](https://deno.land/#installation).
+You can use [`cross`](https://github.com/rust-embedded/cross) to build cross-compiled versions of Pyrinas.
 
-Then, in your Pyrinas firmware directory run:
+Once you have it installed simply invoke `cross` as if you would `cargo`
 
 ```
-> deno run --allow-run --allow-write manifest-generator.ts
+> cross build --package pyrinas-cli --target x86_64-unknown-freebsd
 ```
 
-It will spit out some results for your review:
+While `cross` is a handy tool, it takes almost 3 times as long to build a FreeBSD target using `cross`'s Docker based container than simply building it in a FreeBSD VM. (2015 MBP - 16GB Ram)
+
+**Note:** the default target is `x86_64-unknown-freebsd` and is configured in `Cross.toml`.
+
+**Another note** if you do know how to speed Docker based builds up i'm all eyes & ears!
+
+## Configuring the Server
+
+Pyrinas uses TOML for it's configuration. There is an example TOML file included in this repository. (`config.example.toml`)
+
+For more details on running the included example. Check out [Configuring Pyrinas Server](docs/configuring-server.md).
+
+## Configuring the CLI
+
+The first time you run the CLI you should cofigure your admin address and API key.
+
+The **address** is where you can safely access your admin endpoint. Highly recommended to have this behind a TLS reverse proxy. Alternatively, don't expose the endpoint at all and access safely behind a VPN like `wireguard`.
+
+The **api key** is set within the server's **confg.toml**. It's recommended to make it long and not easily guessable/bruteforceable. 
 
 ```
-❯ deno run --allow-run --allow-write manifest-generator.ts
-Check file:///.../manifest-generator.ts
-version 0.1.0-6-g74b7376
-manifest generated!
-{
-  version: {
-    major: 0,
-    minor: 1,
-    patch: 0,
-    commit: 6,
-    hash: [
-      103, 55, 52, 98,
-       55, 51, 55, 54
-    ]
-  },
-  file: "app_update.bin",
-  force: false
-}
-File written to ./manifest.json
+> pyrinas-cli config install admin.yourdomain.com <YOUR API KEY>
 ```
 
+This will place a CLI configuration in your $HOME/.pyrinas/ folder. You can always re-run the command to overwrite the previous configuration if something changes. 
+
+
+## What's on deck?
+
+Here's what's on my plate and what's to come:
+
+- [x] Serving OTA updates from CLI all the way to a test device
+- [ ] Provide clear documentation for current exmaples 
+  - [ ] For server side
+    - [ ] Example of full workng setup (and the steps to complete it)
+  - [ ] CLI 
+  - [ ] Zephyr side as well
+- [ ] Uploading an OTA package directly from Zephyr based repository
+ - [ ] Clean build checks
+- [ ] Implement more tests around:
+ - [ ] Broker and optional broker capabilties 
+ - [ ] Better coverage in OTA
+ - [ ] Better coverage in Mqtt
+ - [ ] Better coverage in Admin area
+- [ ] More functionality/control for Admin
+
+## Don't see what you're looking for?
+
+Consider creating a feature request and supporting this project by [purchasing hardware](https://www.jaredwolff.com/store/nrf9160-feather/).
+
 ## License
 
-This repository has an Apache 2.0 license. Contributions will be licensed the same
-with no additional terms or conditions. See `LICEENSE` file for more information.
+This repository has an Apache 2.0 license. Contributions will be licensed the same with no additional terms or conditions. See `LICEENSE` file for more information.
+
+## Attribution
+
+Crab icon made by [Flat Icons](https://www.flaticon.com/authors/flat-icons)

docs/configuring-server.md

@@ -0,0 +1,68 @@
+# Configuring Pyrinas Server
+
+There are some important pieces to take care of in order to fully utilize Pyrinas. See below for each item.
+
+## Hosting
+
+- [ ] Self hosting option
+- [ ] Hosting in a container
+
+## Opening up firewall
+
+* 443 - for https
+* 8883 - mqtt
+
+## Generating certs
+
+- [ ] Provision certs 
+
+### Generating server identity file
+
+`openssl` generate `.p12`
+
+### Installing onto nRF9160 Feather
+
+Manifest blah.
+
+## Using with Caddy
+
+Currrently, Pyrinas Server has been tested with Caddy as a reverse proxy. Below are some examples of how you can configure external facing endpoints: `ota` and `admin`.
+
+
+```
+ota.yourdomain.com {
+    log
+    reverse_proxy 127.0.0.1:3030
+    tls {
+        ciphers TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
+    }
+}
+
+admin.yourdomain.com {
+    log
+    reverse_proxy 127.0.0.1:3032
+    encode gzip
+}
+```
+
+Note: the `reverse_proxy` location will differ depending on how you have your server set up. It's always recommended to run Pyrinas in a protected jail or container.
+
+### Ciphers
+
+It's important to note the ciphers section. Currently, the nRF9160 only supports a small subset of ciphers including:
+
+* TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384
+* TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA   
+* TLS-ECDHE-ECDSA-WITH-AES-128-CBC-SHA256
+* TLS-ECDHE-ECDSA-WITH-AES-128-CBC-SHA  
+* TLS-ECDHE-RSA-WITH-AES-256-CBC-SHA         
+* TLS-ECDHE-RSA-WITH-AES-128-CBC-SHA256    
+* TLS-ECDHE-RSA-WITH-AES-128-CBC-SHA       
+* TLS-PSK-WITH-AES-256-CBC-SHA      
+* TLS-PSK-WITH-AES-128-CBC-SHA256   
+* TLS-PSK-WITH-AES-128-CBC-SHA
+* TLS-PSK-WITH-AES-128-CCM-8
+
+Many TLS packages have removed the `CBC` type ciphers since they are not as secure as their `GCM` cousins. Hopefully Noric will address this in  future revisions of their modem firmware for the nRF9160.
+
+Another suggestion is not to expose your `admin` endpoint at all. This can be accomplished using something like `wireguard` where you're using your `admin` endpoint within a VPN.

docs/using-the-example.md

@@ -0,0 +1,12 @@
+# Using the example
+
+You'll need the latest version of `rust`. You can use [`rustup`](https://rustup.rs) to download and install.
+
+```
+> cargo build --package pyrinas-server
+> cargo build --package pyrinas-cli
+```
+
+The server can be cross compiled using other platforms. Pyrinas is mostly used on and is compiled fairly regularly on FreeBSD. It does have some dependencies on OpenSSL/Libc so you'll need to configure these for your intended system of use.
+
+This will build the example server and cli. They'll be available in the `target/debug/` folder.