ovdashboard/README.md

# OVDashboard

A fancy dashboard for use in a [THW](https://en.wikipedia.org/wiki/Technisches_Hilfswerk)-Ortsverband (OV).

![Screenshot](./doc/ovdashboard_en.jpg)


## Key Features

- **Clean Look** <br />
All that matters, at one glance! <br />
*Date and Time &ndash; Upcoming Events &ndash; Public Announcements &ndash; News &ndash; Pictures*

- **Easy Install** <br />
Set up a RaspberryPi, run the [installer script](./deploy/install.sh), done!

- **DAV Server Interface** <br />
Update your content anytime, from anywhere!
Basic [Markdown](https://www.markdownguide.org/) is enough! <br />
Already have a [Nextcloud](https://nextcloud.com/) instance?
OVDashboard will take it from there!

- **Customizable &ndash; Yet Always Recognizable** <br />
Change the Logo &ndash; Put your own Title &ndash; Publish Pictures &ndash; Create Event Lists &ndash; Customize the News Ticker Appearance &ndash; Adjust Item Rotation Speed

- **Responsive Design** <br />
OVDashboard is made for the big screen &ndash; but it also shines in your visitors' mobile browsers!

- **Locale Aware** <br />
No localized strings anywhere &ndash; formats generated using [Luxon](https://moment.github.io/luxon/#/), which [respects your browsers' settings](./doc/ovdashboard_de.jpg)!

- **Hackable** <br />
The Dashboard UI is created using [Vue](https://vuejs.org/) and the [Vuetify](https://vuetifyjs.com/) UI library. <br />
*Like my layout, but want it for something completely different? Fork me!*


## 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! <br />
On your WebDAV account, create a resource (directory) named `ovdashboard`[^1].

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

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/deploy/). 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 edit "dietpi-wifi.txt" like `aWIFI_SSID[0]='OV WLAN'` and `aWIFI_KEY[0]='Strong_pa55w0rd'`
   - 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/deploy/install.sh), then run it from a terminal.

This can all be done after logging into your prepared device:
- The safe way:
   1. download: `wget 'https://code.yavook.de/OEKZident.de/ovdashboard/raw/branch/master/deploy/install.sh'`
   1. read/edit: `nano install.sh`
   1. execute: `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/deploy/install.sh' )`

> There will be some prompts during installation.
>
> - DietPi might ask: "Would you like DietPi to apply the recommended GPU memory split?". Choose **Yes**.
> - DietPi will ask: "Would you like to configure the DietPi-AutoStart option?". **Cancel** that, this choice does not matter as it is changed by the installer.
> - DietPi will ask: "Would you like to join DietPi-Survey?". You should decide for yourself if you want telemetry or not, but I suggest to **opt OUT**.
> - The installer will ask for the connected screen's resolution. The default values should be fine, you can likely just hit **Return** here.
> - The installer will ask for "display languages". This will affect some details on the connected screen. <br />
    For German, enter `de-DE,de,en-US,en`.
> - The installer will ask you to "review the Docker Compose file" before starting the services. You will want to edit `WEBDAV__HOST`, `WEBDAV__USERNAME` and `WEBDAV__PASSWORD` at least. <br />
    Refer to [the "Settings"](#settings-on-your-device-opt-ovdashboard-docker-compose-yml) for the full list of options.

Afterwards, reboot your device (`reboot` in the terminal). 

If the install was successful, your OVDashboard should be showing up on the connected screen after rebooting.

> You will also be able to view your OVDashboard on any webbrowser in your network using `http://<device-ip>`. <br />
> The device IP is displayed in the lower right region of the OVDashboard.

For a better understanding of your newly created OVDashboard, refer to the [about section](#about-the-default-ovdashboard-deployment).

## Configuration

### "Config" in your WebDAV share: `config.txt`

<!-- TODO -->

### "Settings" on your Device: `/opt/ovdashboard/docker-compose.yml`

<!-- TODO -->

## Updating your Device

<!-- TODO `/opt/ovdashboard` -->

## Setup for development and contribution

Refer to the specific README files for [the API](./api/README.md) and [the UI](./ui/README.md) to contribute to one of those sub-projects.


## About the "default" OVDashboard deployment

Running the installer script carries out the following actions:

- install Chromium-Browser, Docker and Docker Compose
- create the OVDashboard project at `/opt/ovdashboard`
- start the OVDashboard project, this deploys the `ovdashboard` service from [`code.yavook.de`](https://code.yavook.de/OEKZident.de/-/packages/container/ovdashboard) and a [`redis` instance](https://redis.io/) to your device
- set up your device to auto-boot into Chromium "kiosk" mode to display the local OVDashboard