aboutsummaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
authorBastien Wirtz <bastien.wirtz@gmail.com>2020-06-11 22:40:36 -0700
committerBastien Wirtz <bastien.wirtz@gmail.com>2020-06-11 22:48:22 -0700
commit1bc75494cae6efd5a0fdff3195db110451bad2ec (patch)
treed9d505377933d6d92276ef1b37a6477684b8ac7a /README.md
parentcad54a560f77382d9584fd804f9cdd84c92012b7 (diff)
downloadhomer-1bc75494cae6efd5a0fdff3195db110451bad2ec.tar.gz
homer-1bc75494cae6efd5a0fdff3195db110451bad2ec.tar.zst
homer-1bc75494cae6efd5a0fdff3195db110451bad2ec.zip
Split documentation into separate files
Diffstat (limited to 'README.md')
-rw-r--r--README.md173
1 files changed, 7 insertions, 166 deletions
diff --git a/README.md b/README.md
index 8818e32..65ef9ab 100644
--- a/README.md
+++ b/README.md
@@ -14,9 +14,11 @@ ervices on hand, from a simple `yaml` configuration file.
14## Table of Contents 14## Table of Contents
15- [Features](#features) 15- [Features](#features)
16- [Getting started](#getting-started) 16- [Getting started](#getting-started)
17- [Configuration](#configuration) 17- [Configuration](docs/configuration.md)
18- [Tips & tricks](docs/tips-and-tricks.md)
18- [Roadmap](#roadmap) 19- [Roadmap](#roadmap)
19- [Developement](#developement) 20- [Developement](docs/developement.md)
21
20 22
21## Features 23## Features
22- [yaml](http://yaml.org/) file configuration 24- [yaml](http://yaml.org/) file configuration
@@ -36,6 +38,8 @@ ervices on hand, from a simple `yaml` configuration file.
36 38
37Homer 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**. 39Homer 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**.
38 40
41For more information about the `config.yml` file see [configuration](docs/configuration.md) the section.
42
39### Using docker 43### Using docker
40 44
41```sh 45```sh
@@ -76,171 +80,8 @@ npm run build
76 80
77Then your dashboard is ready to use in the `/dist` directory. 81Then your dashboard is ready to use in the `/dist` directory.
78 82
79## Configuration
80
81Title, icons, links, colors, and services can be configured in the `config.yml` file (located in project root directory once built, or in the `public/` directory in developement mode), using [yaml](http://yaml.org/) format.
82
83```yaml
84---
85# Homepage configuration
86# See https://fontawesome.com/icons for icons options
87
88# Optional: Use external configuration file.
89# Using this will ignore remaining config in this file
90# externalConfig: https://example.com/server-luci/config.yaml
91
92title: "App dashboard"
93subtitle: "Homer"
94logo: "assets/homer.png"
95# Alternatively a fa icon can be provided:
96# icon: "fas fa-skull-crossbones"
97
98header: true # Set to false to hide the header
99footer: '<p>Created with <span class="has-text-danger">❤️</span> with <a href="https://bulma.io/">bulma</a>, <a href="https://vuejs.org/">vuejs</a> & <a href="https://fontawesome.com/">font awesome</a> // Fork me on <a href="https://github.com/bastienwirtz/homer"><i class="fab fa-github-alt"></i></a></p>' # set false if you want to hide it.
100
101columns: "3" # "auto" or number (must be a factor of 12: 1, 2, 3, 4, 6, 12)
102connectivityCheck: true # whether you want to display a message when the apps are not accessible anymore (VPN disconnected for example)
103
104# Optional theming
105theme: default # 'default' or one of the theme available in 'src/assets/themes'.
106
107# Here is the exaustive list of customization parameters
108# However all value are optional and will fallback to default if not set.
109# if you want to change only some of the colors, feel free to remove all unused key.
110colors:
111 light:
112 highlight-primary: "#3367d6"
113 highlight-secondary: "#4285f4"
114 highlight-hover: "#5a95f5"
115 background: "#f5f5f5"
116 card-background: "#ffffff"
117 text: "#363636"
118 text-header: "#424242"
119 text-title: "#303030"
120 text-subtitle: "#424242"
121 card-shadow: rgba(0, 0, 0, 0.1)
122 link-hover: "#363636"
123 dark:
124 highlight-primary: "#3367d6"
125 highlight-secondary: "#4285f4"
126 highlight-hover: "#5a95f5"
127 background: "#131313"
128 card-background: "#2b2b2b"
129 text: "#eaeaea"
130 text-header: "#ffffff"
131 text-title: "#fafafa"
132 text-subtitle: "#f5f5f5"
133 card-shadow: rgba(0, 0, 0, 0.4)
134 link-hover: "#ffdd57"
135
136# Optional message
137message:
138 # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below.
139 style: "is-warning"
140 title: "Optional message!"
141 content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
142
143# Optional navbar
144# links: [] # Allows for navbar (dark mode, layout, and search) without any links
145links:
146 - name: "Link 1"
147 icon: "fab fa-github"
148 url: "https://github.com/bastienwirtz/homer"
149 target: "_blank" # optional html tag target attribute
150 - name: "link 2"
151 icon: "fas fa-book"
152 url: "https://github.com/bastienwirtz/homer"
153
154# Services
155# First level array represent a group.
156# Leave only a "items" key if not using group (group name, icon & tagstyle are optional, section separation will not be displayed).
157services:
158 - name: "Application"
159 icon: "fa fa-code-fork"
160 items:
161 - name: "Awesome app"
162 logo: "assets/tools/sample.png"
163 # Alternatively a fa icon can be provided:
164 # icon: "fab fa-jenkins"
165 subtitle: "Bookmark example"
166 tag: "app"
167 url: "https://www.reddit.com/r/selfhosted/"
168 target: "_blank" # optional html tag target attribute
169 - name: "Another one"
170 logo: "assets/tools/sample2.png"
171 subtitle: "Another application"
172 tag: "app"
173 # Optional tagstyle
174 tagstyle: "is-success"
175 url: "#"
176 - name: "Other group"
177 icon: "fas fa-heartbeat"
178 items:
179 - name: "Another app"
180 logo: "assets/tools/sample.png"
181 subtitle: "Another example"
182 tag: "other"
183 url: "https://www.reddit.com/r/selfhosted/"
184 target: "_blank" # optionnal html a tag target attribute
185```
186
187If you choose to fetch message information from an endpoint, the output format should be:
188
189```json
190{
191 "style": null,
192 "title": "Lorem ipsum 42",
193 "content": "LA LA LA Lorem ipsum dolor sit amet, ....."
194}
195```
196
197`null` value or missing keys will be ignored and value from the `config.yml` will be used if available.
198Empty values (either in `config.yml` or the endpoint data) will hide the element (ex: set `"title": ""` to hide the title bar).
199
200### Style Options
201
202Homer uses [bulma CSS](https://bulma.io/), which provides a [modifiers syntax](https://bulma.io/documentation/modifiers/syntax/). You'll notice in the config there is a `tagstyle` option. It can be set to any of the bulma modifiers. You'll probably want to use one of these 4 main colors:
203
204- `is-info` (blue)
205- `is-success` (green)
206- `is-warning` (yellow)
207- `is-danger` (red)
208
209You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/) for other options regarding size, style, or state.
210
211 83
212## Roadmap 84## Roadmap
213 85
214- [ ] Add more themes. 86- [ ] Add new themes.
215- [ ] Add support for custom service card (add custom feature to some service / app link) 87- [ ] Add support for custom service card (add custom feature to some service / app link)
216
217
218## Development
219
220```sh
221# Using yarn (recommended)
222yarn install
223yarn serve
224
225# **OR** Using npm
226npm install
227npm run serve
228```
229
230### Themes
231
232Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
233To 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.
234
235```scss
236// `src/assets/themes/my-awesome-theme.scss`
237body #app.theme-my-awesome-theme. { ... }
238```
239
240```scss
241// `src/assets/app.scss`
242// Themes import
243@import "./themes/sui.scss";
244...
245@import "./themes/my-awesome-theme.scss";
246```