README.md

   1 # Homer
   2
   3 A dead simple static **HOM**epage for your serv**ER** to keep your services on hand, from a simple `yaml` configuration file.
   4
   5 **Check out the live demo [here](https://homer-demo.netlify.app).**
   6
   7 It supports keyboard shortcuts:
   8
   9 - `/` Start searching.
  10 - `Escape` Stop searching.
  11 - `Enter` Open the first matching result (respects the bookmark's `_target` property).
  12 - `Alt`/`Option` + `Enter` Open the first matching result in a new tab.
  13
  14 If 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, ...)
  15
  16 ![screenshot](https://raw.github.com/bastienwirtz/homer/master/screenshot.png)
  17
  18 ## Roadmap
  19
  20 - [ ] Add more themes.
  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
  28 ### Using docker
  29
  30 ```sh
  31 docker run -p 8080:8080 -v /your/local/config.yml:/www/config.yml -v /your/local/assets/:/www/assets b4bz/homer:latest
  32 ```
  33
  34 ### Manually
  35
  36 Homer is a static page that need to be generated from the source in this repository.
  37 Use the folowing command to build the project:
  38
  39 ```sh
  40 # Using yarn (recommended)
  41 yarn install
  42 yarn build
  43
  44 # **OR** Using npm
  45 npm install
  46 npm run build
  47 ```
  48
  49 Then your dashboard is ready to use in the `/dist` directory.
  50 The `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
  52 Use it like any static HTML content (use a webserver or open the html index directly).
  53
  54 ## Development
  55
  56 ```sh
  57 # Using yarn (recommended)
  58 yarn install
  59 yarn serve
  60
  61 # **OR** Using npm
  62 npm install
  63 npm run serve
  64 ```
  65
  66 ### Themes
  67
  68 Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
  69 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.
  70
  71 ```scss
  72 // `src/assets/themes/my-awesome-theme.scss`
  73 body #app.theme-my-awesome-theme. { ... }
  74 ```
  75
  76 ```scss
  77 // `src/assets/app.scss`
  78 // Themes import
  79 @import "./themes/sui.scss";
  80 ...
  81 @import "./themes/my-awesome-theme.scss";
  82 ```
  83
  84 ## Configuration
  85
  86 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.
  87
  88 ```yaml
  89 ---
  90 # Homepage configuration
  91 # See https://fontawesome.com/icons for icons options
  92
  93 title: "App dashboard"
  94 subtitle: "Homer"
  95 logo: "assets/homer.png"
  96 # Alternatively a fa icon can be provided:
  97 # icon: "fas fa-skull-crossbones"
  98
  99 header: true # Set to false to hide the header
 100 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.header:
 101
 102 # Optional theming
 103 theme: default # 'default' or one of the theme available in 'src/assets/themes'.
 104
 105 # Here is the exaustive list of customization parameters
 106 # However all value are optional and will fallback to default if not set.
 107 # if you want to change only some of the colors, feel free to remove all unused key.
 108 colors:
 109   light:
 110     highlight-primary: "#3367d6"
 111     highlight-secondary: "#4285f4"
 112     highlight-hover: "#5a95f5"
 113     background: "#f5f5f5"
 114     card-background: "#ffffff"
 115     text: "#363636"
 116     text-header: "#424242"
 117     text-title: "#303030"
 118     text-subtitle: "#424242"
 119     card-shadow: rgba(0, 0, 0, 0.1)
 120     link-hover: "#363636"
 121   dark:
 122     highlight-primary: "#3367d6"
 123     highlight-secondary: "#4285f4"
 124     highlight-hover: "#5a95f5"
 125     background: "#131313"
 126     card-background: "#2b2b2b"
 127     text: "#eaeaea"
 128     text-header: "#ffffff"
 129     text-title: "#fafafa"
 130     text-subtitle: "#f5f5f5"
 131     card-shadow: rgba(0, 0, 0, 0.4)
 132     link-hover: "#ffdd57"
 133
 134 # Optional message
 135 message:
 136   # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below.
 137   style: "is-warning"
 138   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."
 140
 141 # Optional navbar
 142 # links: [] # Allows for navbar (dark mode, layout, and search) without any links
 143 links:
 144   - name: "ansible"
 145     icon: "fab fa-github"
 146     url: "https://github.com/xxxxx/ansible/"
 147     target: "_blank" # optional html tag target attribute
 148   - name: "Wiki"
 149     icon: "fas fa-book"
 150     url: "https://wiki.xxxxxx.com/"
 151
 152 # Services
 153 # 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).
 155 services:
 156   - name: "DevOps"
 157     icon: "fa fa-code-fork"
 158     items:
 159       - name: "Jenkins"
 160         logo: "/assets/tools/jenkins.png"
 161         # Alternatively a fa icon can be provided:
 162         # icon: "fab fa-jenkins"
 163         subtitle: "Continuous integration server"
 164         tag: "CI"
 165         url: "#"
 166         target: "_blank" # optional html tag target attribute
 167       - name: "RabbitMQ Management"
 168         logo: "/assets/tools/rabbitmq.png"
 169         subtitle: "Manage & monitor RabbitMQ server"
 170         tag: "haproxy"
 171         # Optional tagstyle
 172         tagstyle: "is-success"
 173         url: "#"
 174   - name: "Monitoring"
 175     icon: "fas fa-heartbeat"
 176     items:
 177       - name: "M/Monit"
 178         logo: "/assets/tools/monit.png"
 179         subtitle: "Monitor & manage all monit enabled hosts"
 180         tag: "monit"
 181         url: "#"
 182       - name: "Grafana"
 183         logo: "/assets/tools/grafana.png"
 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 ```
 197
 198 If you choose to fetch message information from an endpoint, the output format should be:
 199
 200 ```json
 201 {
 202   "style": null,
 203   "title": "Lorem ipsum 42",
 204   "content": "LA LA LA Lorem ipsum dolor sit amet, ....."
 205 }
 206 ```
 207
 208 `null` value or missing keys will be ignored and value from the `config.yml` will be used if available.
 209 Empty values (either in `config.yml` or the endpoint data) will hide the element (ex: set `"title": ""` to hide the title bar).
 210
 211 ### Style Options
 212
 213 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:
 214
 215 - `is-info` (blue)
 216 - `is-success` (green)
 217 - `is-warning` (yellow)
 218 - `is-danger` (red)
 219
 220 You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/) for other options regarding size, style, or state.