diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 173 |
1 files changed, 7 insertions, 166 deletions
@@ -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 | ||
37 | Homer 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**. | 39 | Homer 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 | ||
41 | For 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 | ||
77 | Then your dashboard is ready to use in the `/dist` directory. | 81 | Then your dashboard is ready to use in the `/dist` directory. |
78 | 82 | ||
79 | ## Configuration | ||
80 | |||
81 | Title, 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 | |||
92 | title: "App dashboard" | ||
93 | subtitle: "Homer" | ||
94 | logo: "assets/homer.png" | ||
95 | # Alternatively a fa icon can be provided: | ||
96 | # icon: "fas fa-skull-crossbones" | ||
97 | |||
98 | header: true # Set to false to hide the header | ||
99 | footer: '<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 | |||
101 | columns: "3" # "auto" or number (must be a factor of 12: 1, 2, 3, 4, 6, 12) | ||
102 | connectivityCheck: true # whether you want to display a message when the apps are not accessible anymore (VPN disconnected for example) | ||
103 | |||
104 | # Optional theming | ||
105 | theme: 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. | ||
110 | colors: | ||
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 | ||
137 | message: | ||
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 | ||
145 | links: | ||
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). | ||
157 | services: | ||
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 | |||
187 | If 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. | ||
198 | Empty 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 | |||
202 | Homer 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 | |||
209 | You 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) | ||
222 | yarn install | ||
223 | yarn serve | ||
224 | |||
225 | # **OR** Using npm | ||
226 | npm install | ||
227 | npm run serve | ||
228 | ``` | ||
229 | |||
230 | ### Themes | ||
231 | |||
232 | Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)). | ||
233 | To 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` | ||
237 | body #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 | ``` | ||