From a93f56ee65fb14e7733a4a7f14f7a91d243e61af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rn-Michael=20Miehe?= <40151420+ldericher@users.noreply.github.com> Date: Wed, 15 Nov 2023 11:27:09 +0100 Subject: [PATCH] README overhaul --- README.md | 80 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index f1520f0..c07c8de 100644 --- a/README.md +++ b/README.md @@ -36,19 +36,53 @@ The Dashboard UI is created using [Vue](https://vuejs.org/) and the [Vuetify](ht ## Quick Start +### Prerequisites + Make sure you have a WebDAV and CalDAV account available. For an all-in-one solution, consider setting up an account on a [Nextcloud](https://nextcloud.com/) instance!
-On your WebvDAV account, create a resource (directory) named `ovdashboard`. +On your WebDAV account, create a resource (directory) named `ovdashboard`[^1]. -The intended installation method is as follows: -1. Have a Raspberry Pi (3 or later) connected to a HDMI screen -1. Boot up "Raspberry Pi OS" (64 bit) and connect the Pi to your local network -1. Download (and review) the [OVDashboard installer](TODO), then run it from a terminal - > If you feel adventurous and want to skip the script review, run `curl --proto '=https' --tlsv1.2 -sSf 'TODO' | sh` instead. -1. Reboot the Raspberry Pi +Your target device should be a Raspberry Pi Model 3 or later[^2]. You will need some accessories: + - microSD card, class 10 or UHS (min. 8 GB) + - network connectivity (bring WiFi credentials if applicable) + - connection to a HDMI screen -For a better understanding of your newly created OVDashboard, refer to the [about section](TODO). +It is also heavily advisable that you log into your device using SSH, so you should get another device (PC, tablet or smartphone) onto the same network as your OVDashboard. +[^1]: if named differently, you will need to adjust your compose file later on +[^2]: other devices will also work, but might require extra installation steps + +### Install Base System + +`OVDashboard` is designed to run on a `DietPi` installation. Full installation documentation is available [at dietpi.com](https://dietpi.com/docs/install/). To quickly get up and running: + +1. Download Image from [dietpi.com/#download](https://dietpi.com/#download) +1. Uncompress Image and flash onto SD card – you might need "7zip", "balenaEtcher" and/or other tools +1. Check the SD card, open "dietpi.txt" and change some options (full documentation [here](https://dietpi.com/docs/usage/#options-within-the-file)): + - For WiFi, use `AUTO_SETUP_NET_WIFI_ENABLED=1` and `AUTO_SETUP_NET_WIFI_COUNTRY_CODE=DE`, and also check "dietpi-wifi.txt" + - System options, e.g. `AUTO_SETUP_AUTOMATED=1`, `AUTO_SETUP_NET_HOSTNAME=ovdashboard`, `AUTO_SETUP_GLOBAL_PASSWORD=dietpi`, `AUTO_SETUP_LOCALE=de_DE.UTF-8`, `AUTO_SETUP_KEYBOARD_LAYOUT=de`, `AUTO_SETUP_TIMEZONE=Europe/Berlin`, `CONFIG_SERIAL_CONSOLE_ENABLE=0` +1. Be sure to at least change the password (and remember it 🙂️), then put the SD card into your device and boot it. Let the first time setup finish, it will take a bit. It will let you know when it is done! +1. Log into your device using SSH. By default, that's user name `root` and password `dietpi` + +### Install OVDashboard + +Download (and review) the [OVDashboard install script](//code.yavook.de/OEKZident.de/ovdashboard/raw/branch/master/install/install.sh), then run it from a terminal. + +This can all be done after logging into your prepared device: +- The safe way: + 1. `mkdir /tmp/ovdashboard && cd /tmp/ovdashboard` + 1. `wget 'https://code.yavook.de/OEKZident.de/ovdashboard/raw/branch/master/install/install.sh'` + 1. `less install.sh` and/or edit with `nano install.sh` + 1. `sh install.sh` +- If you feel adventurous and do not want to review the script, just run `sh <( curl --proto '=https' --tlsv1.2 -sSf 'https://code.yavook.de/OEKZident.de/ovdashboard/raw/branch/master/install/install.sh' )` + +Afterwards, reboot your device (`reboot` in the terminal). Your OVDashboard should be working now. + +For a better understanding of your newly created OVDashboard, refer to the [about section](#about-the-default-ovdashboard-deployment). + +## Updates, upgrades + +`/opt/ovdashboard` ## Configuration @@ -60,31 +94,17 @@ Refer to the specific README files for [the API](./api/README.md) and [the UI](. ## About the "default" OVDashboard deployment -The default deployment is made up of three parts: The **installer** which runs once, prepares your device for OVDashboard usage and deploys the **client** and the **service**. +The default deployment is made up of three parts: The **installer** runs once, prepares your device for OVDashboard usage and deploys the **server**. -The **client** will connect to and display your OVDashboard. +The **server** will then run continuously and make OVDashboard available as a web application in your network. -The **service** will run continuously and makes sure your OVDashboard is up to date. +Also, a browser is installed to display the OVDashboard using your device. ### The OVDashboard installer will: -- install some general-purpose packages -- make you set a new password, if you haven't yet -- install and set up Docker Engine and Mozilla Firefox -- (optionally) enable SSH and/or VNC access to your device -- create the OVDashboard configuration directory `/usr/local/etc/ovdashboard` on your device -- set up the OVDashboard service -- (optionally) set up your device to auto-run the OVDashboard client - - -### The OVDashboard service will: - -- regularly pull the latest `docker` image from [`TODO`](TODO), containing both the OVDashboard API and UI -- ensure a container of that image is always running, using your OVDashboard configuration directory - - -### The OVDashboard client will: - -- open Mozilla Firefox in full-screen mode and browse to the local OVDashboard UI -- enable auto-hiding your mouse cursor +- install and set up Docker, Docker Compose and Chromium-Browser +- create the OVDashboard Compose project at `/opt/ovdashboard` +- get a `docker` image from [`code.yavook.de`](https://code.yavook.de/OEKZident.de/-/packages/container/ovdashboard) containing the OVDashboard server +- set up your device to auto-run Chromium in "kiosk" mode to display the local OVDashboard +- auto-hide your mouse cursor