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 Use it like any static HTML content (use a webserver or open the html index directly).
  51
  52 ## Developement
  53
  54 ```sh
  55 # Using yarn (recommended)
  56 yarn install
  57 yarn serve
  58
  59 # **OR** Using npm
  60 npm install
  61 npm run serve
  62 ```
  63
  64 ### Themes
  65
  66 Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
  67 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.
  68
  69 ```scss
  70 // `src/assets/themes/my-awesome-theme.scss`
  71 body #app.theme-my-awesome-theme. { ... }
  72 ```
  73
  74 ```scss
  75 // `src/assets/app.scss`
  76 // Themes import
  77 @import "./themes/sui.scss";
  78 ...
  79 @import "./themes/my-awesome-theme.scss";
  80 ```
  81
  82 ## Configuration
  83
  84 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.
  85
  86 ```yaml
  87 ---
  88 # Homepage configuration
  89 # See https://fontawesome.com/icons for icons options
  90
  91 title: "App dashboard"
  92 subtitle: "Homer"
  93 logo: "assets/homer.png"
  94 # Alternatively a fa icon can be provided:
  95 # icon: "fas fa-skull-crossbones"
  96
  97 header: true # Set to false to hide the header
  98 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:
  99
 100 # Optional theming
 101 theme: default # 'default' or one of the theme available in 'src/assets/themes'.
 102
 103 # Here is the exaustive list of customization parameters
 104 # However all value are optional and will fallback to default if not set.
 105 # if you want to change only some of the colors, feel free to remove all unused key.
 106 colors:
 107   light:
 108     highlight-primary: "#3367d6"
 109     highlight-secondary: "#4285f4"
 110     highlight-hover: "#5a95f5"
 111     background: "#f5f5f5"
 112     card-background: "#ffffff"
 113     text: "#363636"
 114     text-header: "#424242"
 115     text-title: "#303030"
 116     text-subtitle: "#424242"
 117     card-shadow: rgba(0, 0, 0, 0.1)
 118     link-hover: "#363636"
 119   dark:
 120     highlight-primary: "#3367d6"
 121     highlight-secondary: "#4285f4"
 122     highlight-hover: "#5a95f5"
 123     background: "#131313"
 124     card-background: "#2b2b2b"
 125     text: "#eaeaea"
 126     text-header: "#ffffff"
 127     text-title: "#fafafa"
 128     text-subtitle: "#f5f5f5"
 129     card-shadow: rgba(0, 0, 0, 0.4)
 130     link-hover: "#ffdd57"
 131
 132 # Optional message
 133 message:
 134   # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below.
 135   style: "is-warning"
 136   title: "Optional message!"
 137   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."
 138
 139 # Optional navbar
 140 # links: [] # Allows for navbar (dark mode, layout, and search) without any links
 141 links:
 142   - name: "ansible"
 143     icon: "fab fa-github"
 144     url: "https://github.com/xxxxx/ansible/"
 145     target: "_blank" # optional html tag target attribute
 146   - name: "Wiki"
 147     icon: "fas fa-book"
 148     url: "https://wiki.xxxxxx.com/"
 149
 150 # Services
 151 # First level array represent a group.
 152 # Leave only a "items" key if not using group (group name, icon & tagstyle are optional, section separation will not be displayed).
 153 services:
 154   - name: "DevOps"
 155     icon: "fa fa-code-fork"
 156     items:
 157       - name: "Jenkins"
 158         logo: "/assets/tools/jenkins.png"
 159         # Alternatively a fa icon can be provided:
 160         # icon: "fab fa-jenkins"
 161         subtitle: "Continuous integration server"
 162         tag: "CI"
 163         url: "#"
 164         target: "_blank" # optional html tag target attribute
 165       - name: "RabbitMQ Management"
 166         logo: "/assets/tools/rabbitmq.png"
 167         subtitle: "Manage & monitor RabbitMQ server"
 168         tag: "haproxy"
 169         # Optional tagstyle
 170         tagstyle: "is-success"
 171         url: "#"
 172   - name: "Monitoring"
 173     icon: "fas fa-heartbeat"
 174     items:
 175       - name: "M/Monit"
 176         logo: "/assets/tools/monit.png"
 177         subtitle: "Monitor & manage all monit enabled hosts"
 178         tag: "monit"
 179         url: "#"
 180       - name: "Grafana"
 181         logo: "/assets/tools/grafana.png"
 182         subtitle: "Metric analytics & dashboards"
 183         url: "#"
 184       - name: "Kibana"
 185         logo: "/assets/tools/elastic.png"
 186         subtitle: "Explore & visualize logs"
 187         tag: "elk"
 188         url: "#"
 189       - name: "Website monitoring"
 190         logo: "/assets/tools/pingdom.png"
 191         subtitle: "Pingdom public reports overview"
 192         tag: "CI"
 193         url: "#"
 194 ```
 195
 196 If you choose to fetch message information from an endpoint, the output format should be:
 197
 198 ```json
 199 {
 200   "style": null,
 201   "title": "Lorem ipsum 42",
 202   "content": "LA LA LA Lorem ipsum dolor sit amet, ....."
 203 }
 204 ```
 205
 206 `null` value or missing keys will be ignored and value from the `config.yml` will be used if available.
 207 Empty values (either in `config.yml` or the endpoint data) will hide the element (ex: set `"title": ""` to hide the title bar).
 208
 209 ### Style Options
 210
 211 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:
 212
 213 - `is-info` (blue)
 214 - `is-success` (green)
 215 - `is-warning` (yellow)
 216 - `is-danger` (red)
 217
 218 You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/) for other options regarding size, style, or state.