docs/configuration.md

   1 # Configuration
   2
   3 Title, icons, links, colors, and services can be configured in the `config.yml`
   4 file (located in `/assets` directory once built, or in the `public/assets`
   5 directory in development mode), using [yaml](http://yaml.org/) format.
   6
   7 ```yaml
   8 ---
   9 # Homepage configuration
  10 # See https://fontawesome.com/v5/search for icons options
  11
  12 # Optional: Use external configuration file.
  13 # Using this will ignore remaining config in this file
  14 # externalConfig: https://example.com/server-luci/config.yaml
  15
  16 title: "App dashboard"
  17 subtitle: "Homer"
  18 # Customize the browser tab text
  19 # documentTitle: "Welcome"
  20 logo: "assets/logo.png"
  21 # Alternatively a Font Awesome icon can be provided
  22 # icon: "fas fa-skull-crossbones"
  23
  24 # Set to false to hide the header
  25 header: true
  26 # Set to false to hide the footer
  27 footer: >
  28   <p>Created with <span class="has-text-danger">❤️</span> with
  29   <a href="https://bulma.io/">bulma</a>,
  30   <a href="https://vuejs.org/">vuejs</a>, &
  31   <a href="https://fontawesome.com/">font awesome</a>
  32   // Fork me on <a href="https://github.com/bastienwirtz/homer">
  33   <i class="fab fa-github-alt"></i></a></p>
  34
  35 # Use "auto" or number (must be a factor of 12: 1, 2, 3, 4, 6, 12)
  36 columns: "3"
  37 # Whether you want to display a message when the apps are not accessible
  38 # anymore (VPN disconnected for example)
  39 connectivityCheck: true
  40
  41 # Optional: Set a different hotkey for search, defaults to "/"
  42 # hotkey:
  43 #   search: "Shift"
  44
  45 # Optional: Proxy / hosting option
  46 proxy:
  47   # Send cookies & authorization headers when fetching service specific data.
  48   # Set to `true` if you use an authentication proxy. Can be overrided on
  49   # service level.
  50   useCredentials: false
  51
  52 # Set the default layout and color scheme
  53 defaults:
  54   layout: columns # Either 'columns', or 'list'
  55   colorTheme: auto # One of 'auto', 'light', or 'dark'
  56
  57 # Optional theming: 'default' or one of the themes available in
  58 # 'src/assets/themes'.
  59 theme: default
  60
  61 # Optional custom stylesheet
  62 # Will load custom CSS files. Especially useful for custom icon sets.
  63 # stylesheet:
  64 #   - "assets/custom.css"
  65
  66 # Here is the exhaustive list of customization parameters, however all values
  67 # are optional and will fallback to default if not set. If you want to change
  68 # only some of the colors, feel free to remove all unused keys.
  69 colors:
  70   light:
  71     highlight-primary: "#3367d6"
  72     highlight-secondary: "#4285f4"
  73     highlight-hover: "#5a95f5"
  74     background: "#f5f5f5"
  75     card-background: "#ffffff"
  76     text: "#363636"
  77     text-header: "#424242"
  78     text-title: "#303030"
  79     text-subtitle: "#424242"
  80     card-shadow: rgba(0, 0, 0, 0.1)
  81     link: "#3273dc"
  82     link-hover: "#363636"
  83     background-image: "assets/your/light/bg.png"
  84   dark:
  85     highlight-primary: "#3367d6"
  86     highlight-secondary: "#4285f4"
  87     highlight-hover: "#5a95f5"
  88     background: "#131313"
  89     card-background: "#2b2b2b"
  90     text: "#eaeaea"
  91     text-header: "#ffffff"
  92     text-title: "#fafafa"
  93     text-subtitle: "#f5f5f5"
  94     card-shadow: rgba(0, 0, 0, 0.4)
  95     link: "#3273dc"
  96     link-hover: "#ffdd57"
  97     background-image: "assets/your/dark/bg.png"
  98
  99 # Optional message
 100 message:
 101   # Uses Bulma. See https://bulma.io/documentation/components/message/#colors
 102   # for styling options.
 103   style: "is-warning"
 104   title: "Optional message!"
 105   icon: "fa fa-exclamation-triangle"
 106   content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
 107
 108   # Can optionally fetch information from an endpoint to override value below.
 109   # url: "https://<my-api-endpoint>"
 110   # mapping: # Select the appropriate fields from the response object.
 111   #   title: 'id'       # Use value from field 'id' as title
 112   #   content: 'value'  # Use value from field 'value' as content
 113   # refreshInterval: 10000 # Optional: time interval to refresh message
 114   #
 115   # Real example using chucknorris.io for showing Chuck Norris facts:
 116   # url: https://api.chucknorris.io/jokes/random
 117   # mapping:
 118   #   title: 'id'
 119   #   content: 'value'
 120   # refreshInterval: 10000
 121
 122 # Optional navbar
 123 # Specify [] for navbar (dark mode, layout, and search) without any links
 124 # links: []
 125 links:
 126   - name: "Link 1"
 127     icon: "fab fa-github"
 128     url: "https://github.com/bastienwirtz/homer"
 129     target: "_blank" # optional html tag target attribute
 130   - name: "link 2"
 131     icon: "fas fa-book"
 132     url: "https://github.com/bastienwirtz/homer"
 133   # Urls starting with # will link to additional Homer pages. Passing "#page2"
 134   # will load config from page2.yml as overrides on top of the default values
 135   # set in this config.yml.
 136   - name: "Second Page"
 137     icon: "fas fa-file-alt"
 138     url: "#page2"
 139
 140 # Services
 141 # First level array represents a group. Use only an "items" key if not using
 142 # groups (name, icon, & tagstyle are optional; section separation will not be
 143 # displayed).
 144 services:
 145   - name: "Application"
 146     icon: "fas fa-code-branch"
 147     # A path to an image can also be provided. Note that icon will take
 148     # precedence if both icon and logo are set.
 149     # logo: "path/to/logo"
 150     items:
 151       - name: "Awesome app"
 152         logo: "assets/tools/sample.png"
 153         # Alternatively a fa icon can be provided:
 154         # icon: "fab fa-jenkins"
 155         subtitle: "Bookmark example"
 156         tag: "app"
 157         url: "https://www.reddit.com/r/selfhosted/"
 158         # Optional: HTML <a> tag target attribute
 159         target: "_blank"
 160       - name: "Another one"
 161         logo: "assets/tools/sample2.png"
 162         subtitle: "Another application"
 163         tag: "app"
 164         # Optional tagstyle
 165         tagstyle: "is-success"
 166         url: "#"
 167   - name: "Other group"
 168     icon: "fas fa-heartbeat"
 169     items:
 170       - name: "Pi-hole"
 171         logo: "assets/tools/sample.png"
 172         # Optional: If no subtitle is defined, PiHole statistics will be shown.
 173         # subtitle: "Network-wide Ad Blocking"
 174         tag: "other"
 175         url: "http://192.168.0.151/admin"
 176         # Optional: Loads a specific component that provides extra features.
 177         # MUST MATCH a file name (without file extension) available in
 178         # `src/components/services`
 179         type: "PiHole"
 180         # Optional: HTML <a> tag target attribute
 181         target: "_blank"
 182         # Optional: Custom CSS class for card, useful with custom stylesheet
 183         # class: "green"
 184         # Optional: Set background color directly without custom stylesheet
 185         # background: red
 186 ```
 187
 188 View [Custom Services](custom_services.md) for details about all available
 189 custom services (like PiHole) and how to configure them.
 190
 191 If you choose to fetch message information from an endpoint, the output format
 192 should be as follows (or you can
 193 [custom map fields as shown in tips and tricks](tips_and_tricks#mapping-fields)):
 194
 195 ```json
 196 {
 197   "style": null,
 198   "title": "Lorem ipsum 42",
 199   "content": "LA LA LA Lorem ipsum dolor sit amet, ....."
 200 }
 201 ```
 202
 203 `null` value or missing keys will be ignored and value from the `config.yml`
 204 will be used if available. Empty values (either in `config.yml` or the endpoint
 205 data) will hide the element (ex: set `"title": ""` to hide the title bar).
 206
 207 ## Style Options
 208
 209 Homer uses [Bulma CSS](https://bulma.io/), which provides a
 210 [modifiers syntax](https://bulma.io/documentation/modifiers/syntax/). You'll
 211 notice in the config there is a `tagstyle` option. It can be set to any of the
 212 bulma modifiers. You'll probably want to use one of these 4 main colors:
 213
 214 - `is-info` (blue)
 215 - `is-success` (green)
 216 - `is-warning` (yellow)
 217 - `is-danger` (red)
 218
 219 You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/)
 220 for other options regarding size, style, or state.
 221
 222 ## PWA Icons
 223
 224 In order to easily generate all required icon preset for the PWA to work, a tool
 225 like [vue-pwa-asset-generator](https://www.npmjs.com/package/vue-pwa-asset-generator)
 226 can be used:
 227
 228 ```bash
 229 npx vue-pwa-asset-generator -a {your_512x512_source_png} -o {your_output_folder}
 230 ```