ALPN & Documentation Cleanup (#15)

.gitignore

@@ -51,11 +51,11 @@ docker-compose.override.yaml
 # Integration Tests
 
 # Mosquitto
-tests/integration/mosquitto/*.pem
-tests/integration/mosquitto/*.key
-tests/integration/mosquitto/*.crt
-tests/integration/mosquitto/aws-bridge.conf
+misc/examples/mosquitto/certs
+misc/examples/mosquitto/aws-bridge.conf
 
 # Upparat
-tests/integration/upparat/config.ini
-tests/integration/upparat/tmp
+misc/examples/upparat/config/config.alpn.ini
+misc/examples/upparat/config/config.bridge.ini
+misc/examples/upparat/tmp
+misc/examples/upparat/config/certs

README.md

@@ -15,111 +15,52 @@
 The _Upparat_ is a secure and robust service that runs on your
 IoT device to download and install files such as firmware updates.
 
-## How it works
+[Several hooks](./docs/README.md#hooks) provide a seamless integration in your device environment and allow you
+to use any software update tool such as [RAUC](https://github.com/rauc/rauc),
+[SWUpdate](https://github.com/sbabic/swupdate) or a custom solution.
 
-The _Upparat_ subscribes to [AWS Iot Jobs](https://docs.aws.amazon.com/en_pv/iot/latest/developerguide/iot-jobs.html),
+_Upparat_ subscribes to [AWS Iot Jobs](https://docs.aws.amazon.com/en_pv/iot/latest/developerguide/iot-jobs.html),
 downloads and verifies the specified file and runs an installation command of your
 choice. It handles all the nitty gritty details such as cancelled jobs,
-failed downloads or progress updates.
-
-Several hooks provide a seamless integration in your device environment and allow you
-to use any software update tool such as [RAUC](https://github.com/rauc/rauc),
-[SWUpdate](https://github.com/sbabic/swupdate) or custom solutions.
-
-## Quickstart
-
-### Installation
-TDB
-
-### AWS Setup
-- Create an AWS Iot Thing in the console and download the certificates
-- Create policy
-- Create S3 bucket and upload a test file
-- Create IAM role
-
-TBD
-
-### Configuration
-```ini
-[service]
-sentry = <SENTRY_DNS>
-
-# Default: WARNING
-log_level = <DEBUG|INFO|WARNING|ERROR|EXCEPTION>
-
-# Default: tmpdir
-download_location = <path>
-
-[broker]
-# Default: 127.0.0.1
-host = <host>
-
-# Default: 1883
-port = <port>
-
-# Default: hostname
-thing_name = <AWS thing name>
-
-# Default: upparat
-client_id = <Local client id>
-
-# Default: false
-ssl = <true|false>
-
-cafile = <>
-certfile = <>
-keyfile = <>
+failed downloads and progress updates.
 
+## Getting started
 
-[hooks]
-version = <returns the currently installed version>
-download = <checks if allowed to download>
-ready = <checks if your system is ready/stable>
-install = <installs the file>
-restart = <restarts your device/service>
-
-# Default: 60
-retry_interval = <retry in seconds>
-
-# Default: 60
-max_retries = <>
-```
-
-### Start
-`upparat -v -c <config>`
-
-### Update
-Create a job in the AWS Iot Console.
-
-```json
-{
-    "version": "<test file version>",
-    "file": "${aws:iot:s3-presigned-url:https://s3.<test file location>}",
-    "meta": "<will be passed as an argument to your commands>",
-    "force": false
-}
-```
-
+- [Checkout the examples](./misc/examples/README.md)
+- [Checkout the documentation](./docs/README.md)
 
 ## Development
+
 - Create a virtualenv:
+
   ```
   python3 -m venv .venv
   . .venv/bin/activate
+  pip3 install --upgrade pip setuptools wheel
   ```
 
-- Install Upparat in editable mode with development and optional sentry dependencies:
+- Install Upparat in editable mode with development and optional dependencies:
+
   ```
   pip install -e ".[dev,sentry]"
   ```
 
+#### Pre-commit hooks
+
 - Install the [pre-commit framework](https://pre-commit.com/#install).
 
 - Install the pre-commit hooks:
   ```
   pre-commit install --install-hooks
   ```
 
-### Tests
+#### Unittests & Formatter
+
+```bash
+docker-compose run test
+docker-compose run format
+```
+
+#### Statemachine
 
-- `docker-compose run test`
+- See [visual representation](https://github.com/caruhome/upparat/blob/feat/alpn/docs/statemachine/statemachine.png) of the internal statemachine.

docs/README.md

@@ -0,0 +1,131 @@
+## Configuration Options
+
+The following configuration options exist
+(for a minimal configuration file consult the examples).
+
+```ini
+[service]
+sentry_dsn = <sentry DSN>
+
+# Default: WARNING
+log_level = <DEBUG|INFO|WARNING|ERROR|EXCEPTION>
+
+# Default: tmpdir
+download_location = <path>
+
+[broker]
+# MQTT broker host / port
+host = <host>
+port = <port>
+
+# Default: hostname
+thing_name = <AWS thing name>
+
+# Default: upparat
+client_id = <local client id>
+
+# Optional for client certifacte authentication
+cafile = <Amazon root certificate>
+certfile = <client certificate>
+keyfile = <client priviate key>
+
+[hooks]
+# Used to compare against jobDoucment.version
+version = <returns the currently installed version>
+download = <checks if allowed to download>
+install = <installs the downloaded file>
+restart = <restarts your device/service>
+ready = <checks if your system is stable / update succeeded>
+
+# Hooks can return a status code 3 to indicate
+# a retry at later time after retry_interval.
+# Default: 60
+retry_interval = <retry in seconds>
+
+# Default: 60
+# See retry_interval if hook has reached
+# max_retries the job will be set to failed
+max_retries = <max_retries>
+```
+
+## Hooks
+
+Hooks provide a way to integrate Upparat with any update system (i.e. RAUC, swupdate, etc.).
+
+For a minimal setup you need to provide the following hooks:
+
+- `install`: Handle the installation of the downloaded file.
+- `reboot`: Handle the reboot of the device / service.
+
+### List of all hooks with examples for RAUC
+
+#### `version`
+
+Return the currently installed version. Used to compare
+with the provided version in the job, if equal update
+is not considered necessary. Optional, if not specified
+installation will always be executed.
+
+```
+#!/usr/bin/env bash
+# $1: time elapsed since first call
+# $2: retry count
+# $3: meta from job document
+
+# Gets the system version
+cat /etc/bundle-version
+```
+
+#### `install`
+
+Handle the installation of the downloaded file (`$4`).
+
+```
+#!/usr/bin/env bash
+# $1: time elapsed since first call
+# $2: retry count
+# $3: meta from job document
+# $4: file location
+
+# Example of the retry mechanism:
+# Only install if a certain lock file is not present
+if test -f /tmp/critical.lock; then
+    exit 3
+else
+   rauc install $4
+fi
+```
+
+#### `download`
+
+## Start
+
+`upparat -v -c <config>`
+
+## Systemd service & integration:
+
+```
+[Unit]
+Description=Upparat AWS IoT file installer
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/upparat -c /etc/upparat/upparat.conf
+Environment=PYTHONUNBUFFERED=1
+StandardOutput=journal
+
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## More Tooling
+
+- [Upparat Job Creator](../misc/scripts/README.md)
+
+## Statemachine
+
+![statemachine](./statemachine/statemachine.png)