dashboard/README.md

221 lines
5.9 KiB
Markdown
Raw Normal View History

2020-05-24 22:17:56 +02:00
# Dashboard
2020-05-20 13:49:49 +02:00
2021-06-14 13:35:05 +02:00
[![CircleCI][shield-circleci]][circleci]
[![Docker Cloud Build Status][shield-docker]][docker]
[![Docker Image Size (latest)][shield-docker-image]][docker]
[![codecov][shield-codecov]][codecov]
[![Dependencies][shield-deps]][repo]
[![GitHub license][shield-license]][license]
2021-03-06 10:16:31 +01:00
![Alt text](/screenshot.png?raw=true "screenshot")
2020-05-20 13:49:49 +02:00
2020-05-20 21:00:45 +02:00
Dashboard is just that - a dashboard. It's inspired by [SUI](https://github.com/jeroenpardon/sui) and has all the same features as SUI, such as simple customization through JSON-files and a handy search bar to search the internet more efficiently.
2020-05-20 13:49:49 +02:00
2020-05-20 17:03:19 +02:00
## Features
2021-03-21 19:59:18 +01:00
So what makes this project different from (or even better than) SUI?
2020-05-20 17:03:19 +02:00
2021-03-21 19:59:18 +01:00
- "Display URL" functionality (The URL displayed for apps can differ from the actual URL)
- Categorization for apps
- Themes and search providers can be changed using JSON
- Imprint functionality
2020-05-20 17:03:19 +02:00
2020-05-20 13:49:49 +02:00
## Installation
2021-03-21 19:59:18 +01:00
The recommended way of installation is using [Docker](https://docker.com). You could also build your own version from source, but do proceed at your own risk.
2020-05-20 18:46:58 +02:00
2021-03-21 19:59:18 +01:00
### Docker
2020-05-20 18:46:58 +02:00
2021-03-21 19:59:18 +01:00
The Docker image is built on top of [this image](https://github.com/ratisbona-coding/nginx-cloudflare-cache), as it's based on Nginx and also provides functionality to purge the Cloudflare cache every time the container restarts (though this functionality is entirely optional).
2020-05-20 18:46:58 +02:00
2021-03-21 19:59:18 +01:00
1. Using the Docker CLI:
2020-05-20 13:49:49 +02:00
2021-03-21 19:59:18 +01:00
```sh
$ docker run -d \
2021-03-21 19:59:18 +01:00
-e CLOUDFLARE_ZONE_ID=[OPTIONAL CLOUDFLARE V4 ZONE ID] \
-e CLOUDFLARE_PURGE_TOKEN=[OPTIONAL CLOUDFLARE PURGE TOKEN] \
-v $(pwd)/data:/app/data
-p 8080:8080 \
--name dashboard \
phntxx/dashboard
2020-05-20 18:46:58 +02:00
```
2021-03-21 19:59:18 +01:00
2. Using Docker-Compose:
2020-06-08 13:29:00 +02:00
2021-03-21 19:59:18 +01:00
```yml
2020-06-08 13:29:00 +02:00
version: "3"
services:
2021-03-21 19:59:18 +01:00
dashboard:
image: phntxx/dashboard:latest
restart: unless-stopped
environment:
- CLOUDFLARE_ZONE_ID=[OPTIONAL CLOUDFLARE V4 ZONE ID]
- CLOUDFLARE_PURGE_TOKEN=[OPTIONAL CLOUDFLARE PURGE TOKEN]
volumes:
- [path to data directory]:/app/data
ports:
- 8080:8080
2020-06-08 13:29:00 +02:00
```
2021-03-21 19:59:18 +01:00
### Compile from source
2020-05-20 13:49:49 +02:00
2021-03-21 19:59:18 +01:00
I really don't anticipate people to use this, so go forth at your own risk.
2020-05-20 18:46:58 +02:00
2021-03-21 19:59:18 +01:00
```bash
$ git clone https://github.com/phntxx/dashboard.git
$ cd dashboard/
$ yarn
$ yarn build
$ yarn serve:production
2020-05-20 13:49:49 +02:00
```
2021-03-21 19:59:18 +01:00
## Configuration
2020-05-20 13:49:49 +02:00
2021-03-21 19:59:18 +01:00
There's a couple of things you can / need to configure to get Dashboard to look and behave just as you want it to.
2021-03-21 19:59:18 +01:00
If you don't require a specific component, just remove the file from your `data`-directory. Dashboard won't render the components whose files are not present. With no files present, only the greeter will be shown.
2021-03-21 20:19:44 +01:00
If you're running into problems with configuring your files and you can't seem to get them to work, feel free to open an issue, I'd be happy to help! :smile:
2021-03-21 19:59:18 +01:00
### Apps
2021-03-21 19:59:18 +01:00
To show the apps you want to show, change `apps.json` to resemble the following:
2021-03-21 19:59:18 +01:00
```json
{
2021-03-21 19:59:18 +01:00
"categories": [
{
"name": "[Name of the category]",
"items": [
{
"name": "[Name of the app]",
"displayURL": "[URL you want to show]",
2021-03-22 20:35:42 +01:00
"url": "[URL to redirect to]",
2021-03-21 19:59:18 +01:00
"icon": "[Icon code]"
},
...
]
},
...
],
"apps": [
{
"name": "[Name of the app]",
"displayURL": "[URL you want to show]",
2021-03-22 20:35:42 +01:00
"url": "[URL to redirect to]",
2021-03-21 19:59:18 +01:00
"icon": "[Icon code]"
},
...
]
}
```
2021-03-21 19:59:18 +01:00
Wherein either `apps` or `categories` can be omitted as needed.
2021-03-21 19:59:18 +01:00
To find icons, simply go to the [Material Design Icon Library](https://material.io/icons/) and copy one of the codes for an icon there.
2021-03-21 19:59:18 +01:00
### Bookmarks
2021-03-21 19:59:18 +01:00
To show bookmarks, `bookmarks.json` needs to resemble the following:
2021-03-21 19:59:18 +01:00
```json
{
2021-03-21 19:59:18 +01:00
"groups": [
{
"name": "[Group Name]",
"items": [
{
"name": "[Bookmark Name]",
"url": "[Bookmark URL]"
},
...
]
},
...
]
}
```
2021-03-21 19:59:18 +01:00
### Themes
2020-05-20 13:49:49 +02:00
2021-03-21 19:59:18 +01:00
In order to customize theming, `themes.json` needs to resemble this:
2020-05-20 13:49:49 +02:00
2021-03-21 19:59:18 +01:00
```json
2020-05-20 17:03:19 +02:00
{
2021-03-21 19:59:18 +01:00
"themes": [
{
"label": "[Theme Name]",
"value": "[Number of the theme]",
"mainColor": "[Main Color as 6-character hex code]",
"accentColor": "[Accent Color as 6-character hex code]",
"backgroundColor": "[Background Color as 6-character hex code]"
},
...
]
}
2020-05-20 13:49:49 +02:00
```
2021-03-21 19:59:18 +01:00
### Search Providers
2020-05-20 18:46:58 +02:00
2021-03-21 19:59:18 +01:00
For search providers to work, make sure your `search.json` resembles the following:
2020-05-20 13:49:49 +02:00
2021-03-21 19:59:18 +01:00
```json
2020-05-20 17:03:19 +02:00
{
2021-03-21 19:59:18 +01:00
"providers": [
{
"name": "[Name of the website]",
"url": "[Link that processes searches on that website]",
"prefix": "[A custom prefix (e.g. '/test')]"
},
...
]
2020-05-20 17:03:19 +02:00
}
```
2021-03-21 19:59:18 +01:00
### Imprint
2020-05-20 18:46:58 +02:00
2021-03-21 19:59:18 +01:00
In order for the imprint-modal to show up, make sure your `imprint.json` resembles the following:
2020-05-20 17:03:19 +02:00
2021-03-21 19:59:18 +01:00
```json
2020-05-20 17:03:19 +02:00
{
2021-03-21 19:59:18 +01:00
"imprint": {
"name": {
"text": "[Name]",
"link": "[Link to the name (to e.g. a portfolio)]"
},
"address": {
"text": "[Address]",
"link": "[Link for the address (to e.g. Google Maps)]"
},
"phone": {
"text": "[Phone number]",
"link": "[Link for the phone number]"
},
"email": {
"text": "[Email address]",
"link": "[Link for the email address (e.g. for 'mailto')]"
},
"url": {
"text": "[URL]",
"link": "[Link for the URL]"
},
"text": "[Text for the imprint]"
}
}
2020-05-20 13:49:49 +02:00
```
2021-03-21 19:59:18 +01:00
> :exclamation: I haven't quite tested this. I'm not a lawyer and I'm not responsible if you're sued for using this incorrectly.
2021-06-14 13:35:05 +02:00
[docker]: https://hub.docker.com/r/phntxx/dashboard
[codecov]: https://codecov.io/gh/phntxx/dashboard
[repo]: https://github.com/phntxx/dashboard
[license]: https://github.com/phntxx/dashboard/LICENSE
[circleci]: https://circleci.com/gh/phntxx/dashboard
[shield-docker]: https://img.shields.io/docker/cloud/build/phntxx/dashboard
[shield-docker-image]: https://img.shields.io/docker/image-size/phntxx/dashboard/latest
[shield-circleci]: https://circleci.com/gh/phntxx/dashboard.svg?style=shield
[shield-codecov]: https://codecov.io/gh/phntxx/dashboard/branch/master/graph/badge.svg
[shield-license]: https://img.shields.io/github/license/phntxx/dashboard.svg
[shield-deps]: https://img.shields.io/david/phntxx/dashboard