aboutsummaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
authorBastien Wirtz <bastien.wirtz@gmail.com>2020-06-05 22:56:53 -0700
committerBastien Wirtz <bastien.wirtz@gmail.com>2020-06-06 16:06:56 -0700
commite1470a8c42d3e8bff52c6a9bf79710625612fe16 (patch)
tree3fc96366c8831972480cc4061916bc2ad3686ff0 /README.md
parent51e02bed72896b94170c4e0d9878c58a4210143a (diff)
downloadhomer-e1470a8c42d3e8bff52c6a9bf79710625612fe16.tar.gz
homer-e1470a8c42d3e8bff52c6a9bf79710625612fe16.tar.zst
homer-e1470a8c42d3e8bff52c6a9bf79710625612fe16.zip
Adding more documentation
Diffstat (limited to 'README.md')
-rw-r--r--README.md189
1 files changed, 100 insertions, 89 deletions
diff --git a/README.md b/README.md
index aa934f7..337fb5d 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,39 @@
1# Homer 1# Homer
2[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
3[![Contribution Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
4[![Dowload](https://img.shields.io/badge/Dowload-homer.zip-orange)](https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip)
5[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/awesome-selfhosted/awesome-selfhosted)
2 6
3A dead simple static **HOM**epage for your serv**ER** to keep your services on hand, from a simple `yaml` configuration file. 7A dead simple static **HOM**epage for your serv**ER** to keep your s
8ervices on hand, from a simple `yaml` configuration file.
4 9
5**Check out the live demo [here](https://homer-demo.netlify.app).** 10## [Live demo](https://homer-demo.netlify.app).
6 11![screenshot](https://raw.github.com/bastienwirtz/homer/master/screenshot.png)
7It supports keyboard shortcuts:
8 12
9- `/` Start searching. 13## Table of Contents
10- `Escape` Stop searching. 14- [Features](#features)
11- `Enter` Open the first matching result (respects the bookmark's `_target` property). 15- [Getting started](#getting-started)
12- `Alt`/`Option` + `Enter` Open the first matching result in a new tab. 16- [Configuration](#configuration)
17- [Roadmap](#roadmap)
18- [Developement](#developement)
13 19
14If you need authentication support, you're on your own (it can be secured using a web server auth module or exposing it only through a VPN network / SSH tunnel, ...) 20## Features
21- [yaml](http://yaml.org/) file configuration
22- Installable (pwa)
23- Search
24- Grouping
25- Theme customization
26- Offline heathcheck
27- keyboard shortcuts:
28 - `/` Start searching.
29 - `Escape` Stop searching.
30 - `Enter` Open the first matching result (respects the bookmark's `_target` property).
31 - `Alt`/`Option` + `Enter` Open the first matching result in a new tab.
15 32
16![screenshot](https://raw.github.com/bastienwirtz/homer/master/screenshot.png)
17 33
18## Roadmap 34## Getting started
19 35
20- [ ] Add more themes. 36Homer is a full static html/js dashboard, generated from the source in `/src` using webpack. It's meant to be served by an HTTP server, **it will not work if you open dist/index.html directly over file:// protocol**.
21- [ ] Add support for custom service card (add custom feature to some service / app link)
22- [x] Colors / theme customization
23- [x] Enable PWA support (making possible to "install" - add to homescreen - it)
24- [x] Improve maintainability (external library import & service workers cached file list.)
25
26## Usage
27 37
28### Using docker 38### Using docker
29 39
@@ -31,55 +41,31 @@ If you need authentication support, you're on your own (it can be secured using
31docker run -p 8080:8080 -v /your/local/config.yml:/www/config.yml -v /your/local/assets/:/www/assets b4bz/homer:latest 41docker run -p 8080:8080 -v /your/local/config.yml:/www/config.yml -v /your/local/assets/:/www/assets b4bz/homer:latest
32``` 42```
33 43
34### Manually 44### Using the release tarball (prebuilt, ready to use)
35
36Homer is a static page that need to be generated from the source in this repository.
37Use the folowing command to build the project:
38 45
46Download and extract the latest the latest release (`homer.zip`) from the [release page](https://github.com/bastienwirtz/homer/releases), rename the `config.yml.dist` file to `config.yml`, and put it behind a webserver.
47
39```sh 48```sh
40# Using yarn (recommended) 49wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
41yarn install 50unzip homer.zip
42yarn build 51cd homer
43 52cp config.yml.dist config.yml
44# **OR** Using npm 53npx serve # or python -m http.server 8010 or apache, nginx ...
45npm install
46npm run build
47``` 54```
48 55
49Then your dashboard is ready to use in the `/dist` directory. 56### Build manually
50The `dist` directory is meant to be served by an HTTP server, so **it will not work if you open dist/index.html directly over file:// protocol**.
51
52Use it like any static HTML content (use a webserver or open the html index directly).
53
54## Development
55 57
56```sh 58```sh
57# Using yarn (recommended) 59# Using yarn (recommended)
58yarn install 60yarn install
59yarn serve 61yarn build
60 62
61# **OR** Using npm 63# **OR** Using npm
62npm install 64npm install
63npm run serve 65npm run build
64```
65
66### Themes
67
68Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
69To addd a new theme, just add a file in the theme directory, and put all style in the `body #app.theme-<name>` scope. Then import it in the main style file.
70
71```scss
72// `src/assets/themes/my-awesome-theme.scss`
73body #app.theme-my-awesome-theme. { ... }
74``` 66```
75 67
76```scss 68Then your dashboard is ready to use in the `/dist` directory.
77// `src/assets/app.scss`
78// Themes import
79@import "./themes/sui.scss";
80...
81@import "./themes/my-awesome-theme.scss";
82```
83 69
84## Configuration 70## Configuration
85 71
@@ -136,63 +122,51 @@ message:
136 # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below. 122 # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below.
137 style: "is-warning" 123 style: "is-warning"
138 title: "Optional message!" 124 title: "Optional message!"
139 content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque risus mi, tempus quis placerat ut, porta nec nulla. Vestibulum rhoncus ac ex sit amet fringilla. Nullam gravida purus diam, et dictum felis venenatis efficitur. Aenean ac eleifend lacus, in mollis lectus. Donec sodales, arcu et sollicitudin porttitor, tortor urna tempor ligula." 125 content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
140 126
141# Optional navbar 127# Optional navbar
142# links: [] # Allows for navbar (dark mode, layout, and search) without any links 128# links: [] # Allows for navbar (dark mode, layout, and search) without any links
143links: 129links:
144 - name: "ansible" 130 - name: "Link 1"
145 icon: "fab fa-github" 131 icon: "fab fa-github"
146 url: "https://github.com/xxxxx/ansible/" 132 url: "https://github.com/bastienwirtz/homer"
147 target: "_blank" # optional html tag target attribute 133 target: "_blank" # optional html tag target attribute
148 - name: "Wiki" 134 - name: "link 2"
149 icon: "fas fa-book" 135 icon: "fas fa-book"
150 url: "https://wiki.xxxxxx.com/" 136 url: "https://github.com/bastienwirtz/homer"
151 137
152# Services 138# Services
153# First level array represent a group. 139# First level array represent a group.
154# Leave only a "items" key if not using group (group name, icon & tagstyle are optional, section separation will not be displayed). 140# Leave only a "items" key if not using group (group name, icon & tagstyle are optional, section separation will not be displayed).
155services: 141services:
156 - name: "DevOps" 142 - name: "Application"
157 icon: "fa fa-code-fork" 143 icon: "fa fa-code-fork"
158 items: 144 items:
159 - name: "Jenkins" 145 - name: "Awesome app"
160 logo: "/assets/tools/jenkins.png" 146 logo: "assets/tools/sample.png"
161 # Alternatively a fa icon can be provided: 147 # Alternatively a fa icon can be provided:
162 # icon: "fab fa-jenkins" 148 # icon: "fab fa-jenkins"
163 subtitle: "Continuous integration server" 149 subtitle: "Bookmark example"
164 tag: "CI" 150 tag: "app"
165 url: "#" 151 url: "https://www.reddit.com/r/selfhosted/"
166 target: "_blank" # optional html tag target attribute 152 target: "_blank" # optional html tag target attribute
167 - name: "RabbitMQ Management" 153 - name: "Another one"
168 logo: "/assets/tools/rabbitmq.png" 154 logo: "assets/tools/sample2.png"
169 subtitle: "Manage & monitor RabbitMQ server" 155 subtitle: "Another application"
170 tag: "haproxy" 156 tag: "app"
171 # Optional tagstyle 157 # Optional tagstyle
172 tagstyle: "is-success" 158 tagstyle: "is-success"
173 url: "#" 159 url: "#"
174 - name: "Monitoring" 160 - name: "Other group"
175 icon: "fas fa-heartbeat" 161 icon: "fas fa-heartbeat"
176 items: 162 items:
177 - name: "M/Monit" 163 - name: "Another app"
178 logo: "/assets/tools/monit.png" 164 logo: "assets/tools/sample.png"
179 subtitle: "Monitor & manage all monit enabled hosts" 165 subtitle: "Another example"
180 tag: "monit" 166 tag: "other"
181 url: "#" 167 url: "https://www.reddit.com/r/selfhosted/"
182 - name: "Grafana" 168 target: "_blank" # optionnal html a tag target attribute
183 logo: "/assets/tools/grafana.png" 169
184 subtitle: "Metric analytics & dashboards"
185 url: "#"
186 - name: "Kibana"
187 logo: "/assets/tools/elastic.png"
188 subtitle: "Explore & visualize logs"
189 tag: "elk"
190 url: "#"
191 - name: "Website monitoring"
192 logo: "/assets/tools/pingdom.png"
193 subtitle: "Pingdom public reports overview"
194 tag: "CI"
195 url: "#"
196``` 170```
197 171
198If you choose to fetch message information from an endpoint, the output format should be: 172If you choose to fetch message information from an endpoint, the output format should be:
@@ -218,3 +192,40 @@ Homer uses [bulma CSS](https://bulma.io/), which provides a [modifiers syntax](h
218- `is-danger` (red) 192- `is-danger` (red)
219 193
220You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/) for other options regarding size, style, or state. 194You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/) for other options regarding size, style, or state.
195
196
197## Roadmap
198
199- [ ] Add more themes.
200- [ ] Add support for custom service card (add custom feature to some service / app link)
201
202
203## Development
204
205```sh
206# Using yarn (recommended)
207yarn install
208yarn serve
209
210# **OR** Using npm
211npm install
212npm run serve
213```
214
215### Themes
216
217Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
218To addd a new theme, just add a file in the theme directory, and put all style in the `body #app.theme-<name>` scope. Then import it in the main style file.
219
220```scss
221// `src/assets/themes/my-awesome-theme.scss`
222body #app.theme-my-awesome-theme. { ... }
223```
224
225```scss
226// `src/assets/app.scss`
227// Themes import
228@import "./themes/sui.scss";
229...
230@import "./themes/my-awesome-theme.scss";
231```