X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=README.md;h=aa934f73278b3ac693ea8b157ff5e0ee60e39e4a;hb=51e02bed72896b94170c4e0d9878c58a4210143a;hp=f052fc9074939580702289034951413228ee13f8;hpb=a4de4a3a71e460141b740564ef22d1c79760db4e;p=github%2Fbastienwirtz%2Fhomer.git diff --git a/README.md b/README.md index f052fc9..aa934f7 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@ # Homer + A dead simple static **HOM**epage for your serv**ER** to keep your services on hand, from a simple `yaml` configuration file. -**Check out the live demo [here](https://homer-demo.netlify.com/).** +**Check out the live demo [here](https://homer-demo.netlify.app).** It supports keyboard shortcuts: -* `/` Start searching. -* `Escape` Stop searching. -* `Enter` Open the first matching result (respects the bookmark's `_target` property). -* `Alt`/`Option` + `Enter` Open the first matching result in a new tab. +- `/` Start searching. +- `Escape` Stop searching. +- `Enter` Open the first matching result (respects the bookmark's `_target` property). +- `Alt`/`Option` + `Enter` Open the first matching result in a new tab. 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, ...) @@ -16,39 +17,119 @@ If you need authentication support, you're on your own (it can be secured using ## Roadmap -- [ ] Colors / theme customization -- [ ] Enable PWA support (making possible to "install" - add to homescreen - it) -- [ ] Improve maintenability (external library import & service workers cached file list.) +- [ ] Add more themes. +- [ ] Add support for custom service card (add custom feature to some service / app link) +- [x] Colors / theme customization +- [x] Enable PWA support (making possible to "install" - add to homescreen - it) +- [x] Improve maintainability (external library import & service workers cached file list.) -## Installation +## Usage ### Using docker ```sh -sudo docker run -p 8080:8080 -v /your/local/config.yml:/www/config.yml -v /your/local/assets/:/www/assets b4bz/homer:latest +docker run -p 8080:8080 -v /your/local/config.yml:/www/config.yml -v /your/local/assets/:/www/assets b4bz/homer:latest ``` ### Manually -**How to build / install it?** There is no build system (😱), use it like that! It's meant to be stupid simple & zero maintenance required. Just copy the static files somewhere, and visit the `index.html`. +Homer is a static page that need to be generated from the source in this repository. +Use the folowing command to build the project: +```sh +# Using yarn (recommended) +yarn install +yarn build -## Configuration +# **OR** Using npm +npm install +npm run build +``` + +Then your dashboard is ready to use in the `/dist` directory. +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**. + +Use it like any static HTML content (use a webserver or open the html index directly). -Title, icons, links, colors, and services can be configured in the `config.yml` file, using [yaml](http://yaml.org/) format. +## Development +```sh +# Using yarn (recommended) +yarn install +yarn serve + +# **OR** Using npm +npm install +npm run serve +``` + +### Themes + +Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)). +To addd a new theme, just add a file in the theme directory, and put all style in the `body #app.theme-` scope. Then import it in the main style file. + +```scss +// `src/assets/themes/my-awesome-theme.scss` +body #app.theme-my-awesome-theme. { ... } +``` + +```scss +// `src/assets/app.scss` +// Themes import +@import "./themes/sui.scss"; +... +@import "./themes/my-awesome-theme.scss"; +``` + +## Configuration + +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. ```yaml --- # Homepage configuration # See https://fontawesome.com/icons for icons options -title: "Simple homepage" +title: "App dashboard" subtitle: "Homer" logo: "assets/homer.png" # Alternatively a fa icon can be provided: -# icon: "fas fa-skull-crossbones" -footer: '

Created with ❤️ with bulma, vuejs & font awesome // Fork me on

' # set false if you want to hide it.header: +# icon: "fas fa-skull-crossbones" + +header: true # Set to false to hide the header +footer: '

Created with ❤️ with bulma, vuejs & font awesome // Fork me on

' # set false if you want to hide it.header: + +# Optional theming +theme: default # 'default' or one of the theme available in 'src/assets/themes'. + +# Here is the exaustive list of customization parameters +# However all value are optional and will fallback to default if not set. +# if you want to change only some of the colors, feel free to remove all unused key. +colors: + light: + highlight-primary: "#3367d6" + highlight-secondary: "#4285f4" + highlight-hover: "#5a95f5" + background: "#f5f5f5" + card-background: "#ffffff" + text: "#363636" + text-header: "#424242" + text-title: "#303030" + text-subtitle: "#424242" + card-shadow: rgba(0, 0, 0, 0.1) + link-hover: "#363636" + dark: + highlight-primary: "#3367d6" + highlight-secondary: "#4285f4" + highlight-hover: "#5a95f5" + background: "#131313" + card-background: "#2b2b2b" + text: "#eaeaea" + text-header: "#ffffff" + text-title: "#fafafa" + text-subtitle: "#f5f5f5" + card-shadow: rgba(0, 0, 0, 0.4) + link-hover: "#ffdd57" # Optional message message: @@ -61,11 +142,11 @@ message: # links: [] # Allows for navbar (dark mode, layout, and search) without any links links: - name: "ansible" - icon: "fa-github" + icon: "fab fa-github" url: "https://github.com/xxxxx/ansible/" - target: '_blank' # optionnal html a tag target attribute + target: "_blank" # optional html tag target attribute - name: "Wiki" - icon: "fa-book" + icon: "fas fa-book" url: "https://wiki.xxxxxx.com/" # Services @@ -73,7 +154,7 @@ links: # Leave only a "items" key if not using group (group name, icon & tagstyle are optional, section separation will not be displayed). services: - name: "DevOps" - icon: "fa-code-fork" + icon: "fa fa-code-fork" items: - name: "Jenkins" logo: "/assets/tools/jenkins.png" @@ -82,7 +163,7 @@ services: subtitle: "Continuous integration server" tag: "CI" url: "#" - target: '_blank' # optionnal html a tag target attribute + target: "_blank" # optional html tag target attribute - name: "RabbitMQ Management" logo: "/assets/tools/rabbitmq.png" subtitle: "Manage & monitor RabbitMQ server" @@ -91,7 +172,7 @@ services: tagstyle: "is-success" url: "#" - name: "Monitoring" - icon: "fa-heartbeat" + icon: "fas fa-heartbeat" items: - name: "M/Monit" logo: "/assets/tools/monit.png" @@ -112,18 +193,28 @@ services: subtitle: "Pingdom public reports overview" tag: "CI" url: "#" - ``` If you choose to fetch message information from an endpoint, the output format should be: ```json { - "style": null, - "title": "Lorem ipsum 42", - "content": "LA LA LA Lorem ipsum dolor sit amet, ....." + "style": null, + "title": "Lorem ipsum 42", + "content": "LA LA LA Lorem ipsum dolor sit amet, ....." } ``` `null` value or missing keys will be ignored and value from the `config.yml` will be used if available. Empty values (either in `config.yml` or the endpoint data) will hide the element (ex: set `"title": ""` to hide the title bar). + +### Style Options + +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: + +- `is-info` (blue) +- `is-success` (green) +- `is-warning` (yellow) +- `is-danger` (red) + +You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/) for other options regarding size, style, or state.