[github/bastienwirtz/homer.git] / docs / configuration.md

# Configuration

Title, icons, links, colors, and services can be configured in the `config.yml` file (located in `/assets` directory once built, or in the `public/assets` directory in development mode), using [yaml](http://yaml.org/) format.

```yaml
---
# Homepage configuration
# See https://fontawesome.com/icons for icons options

# Optional: Use external configuration file.
# Using this will ignore remaining config in this file
# externalConfig: https://example.com/server-luci/config.yaml

title: "App dashboard"
subtitle: "Homer"
# documentTitle: "Welcome" # Customize the browser tab text
logo: "assets/logo.png"
# Alternatively a fa icon can be provided:
# icon: "fas fa-skull-crossbones"

header: true # Set to false to hide the header
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.

columns: "3" # "auto" or number (must be a factor of 12: 1, 2, 3, 4, 6, 12)
connectivityCheck: true # whether you want to display a message when the apps are not accessible anymore (VPN disconnected for example)

# Optional: Proxy / hosting option
proxy:
  # NOT All custom services implements this new option YET. Support will be extended very soon.
  useCredentials: false # send cookies & authorization headers when fetching service specific data. Set to `true` if you use an authentication proxy. Can be overrided on service level. 

# Optional theming
theme: default # 'default' or one of the themes available in 'src/assets/themes'.

# Optional custom stylesheet
# Will load custom CSS files. Especially useful for custom icon sets.
# stylesheet:
#   - "assets/custom.css"

# Here is the exhaustive 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: "#3273dc"
    link-hover: "#363636"
    background-image: "assets/your/light/bg.png"
  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: "#3273dc"
    link-hover: "#ffdd57"
    background-image: "assets/your/dark/bg.png"

# Optional message
message:
  # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below.
  # mapping: # allows to map fields from the remote format to the one expected by Homer
  #   title: 'id' # use value from field 'id' as title
  #   content: 'value' # value from field 'value' as content
  # refreshInterval: 10000 # Optional: time interval to refresh message
  #
  # Real example using chucknorris.io for showing Chuck Norris facts as messages:
  # url: https://api.chucknorris.io/jokes/random
  # mapping:
  #   title: 'id'
  #   content: 'value'
  # refreshInterval: 10000
  style: "is-warning"
  title: "Optional message!"
  icon: "fa fa-exclamation-triangle"
  content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."

# Optional navbar
# links: [] # Allows for navbar (dark mode, layout, and search) without any links
links:
  - name: "Link 1"
    icon: "fab fa-github"
    url: "https://github.com/bastienwirtz/homer"
    target: "_blank" # optional html tag target attribute
  - name: "link 2"
    icon: "fas fa-book"
    url: "https://github.com/bastienwirtz/homer"
  # this will link to a second homer page that will load config from page2.yml and keep default config values as in config.yml file
  # see url field and assets/page.yml used in this example:
  - name: "Second Page"
    icon: "fas fa-file-alt"
    url: "#page2"

# Services
# First level array represents a group.
# Leave only a "items" key if not using group (group name, icon & tagstyle are optional, section separation will not be displayed).
services:
  - name: "Application"
    icon: "fas fa-code-branch"
    # A path to an image can also be provided. Note that icon take precedence if both icon and logo are set.
    # logo: "path/to/logo"
    items:
      - name: "Awesome app"
        logo: "assets/tools/sample.png"
        # Alternatively a fa icon can be provided:
        # icon: "fab fa-jenkins"
        subtitle: "Bookmark example"
        tag: "app"
        url: "https://www.reddit.com/r/selfhosted/"
        target: "_blank" # optional html tag target attribute
      - name: "Another one"
        logo: "assets/tools/sample2.png"
        subtitle: "Another application"
        tag: "app"
        # Optional tagstyle
        tagstyle: "is-success"
        url: "#"
  - name: "Other group"
    icon: "fas fa-heartbeat"
    items:
      - name: "Pi-hole"
        logo: "assets/tools/sample.png"
        # subtitle: "Network-wide Ad Blocking" # optional, if no subtitle is defined, PiHole statistics will be shown
        tag: "other"
        url: "http://192.168.0.151/admin"
        type: "PiHole" # optional, loads a specific component that provides extra features. MUST MATCH a file name (without file extension) available in `src/components/services`
        target: "_blank" # optional html a tag target attribute
        # class: "green" # optional custom CSS class for card, useful with custom stylesheet
        # background: red # optional color for card to set color directly without custom stylesheet
```

View [Custom Services](customservices.md) for details about all available custom services (like PiHole) and how to configure them.

If you choose to fetch message information from an endpoint, the output format should be as follows (or you can [custom map fields as shown in tips-and-tricks](./tips-and-tricks.md#mapping-fields)):

```json
{
  "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.

## PWA Icons

In order to easily generate all required icon preset for the PWA to work, a tool like [vue-pwa-asset-generator](https://www.npmjs.com/package/vue-pwa-asset-generator) can be used:

```bash
npx vue-pwa-asset-generator -a {your_512x512_source_png} -o {your_output_folder}
```

## Supported services

Currently the following services are supported for showing quick infos on the card. They can be used by setting the type to one of the following values at the item.

- PiHole
- AdGuardHome
- PaperlessNG
- Mealie

## Additional configuration

### Paperless

For Paperless you need an API-Key which you have to store at the item in the field `apikey`.

### Mealie

First off make sure to remove an existing `subtitle` as it will take precedence if set. Setting `type: "Mealie"` will then show the number of recipes Mealie is keeping organized or the planned meal for today if one is planned. You will have to set an API key in the field `apikey` which can be created in your Mealie installation.
Commit	Line	Data
1d3287dc	1	# Configuration
1bc75494	2
2662b170	3	Title, icons, links, colors, and services can be configured in the `config.yml` file (located in `/assets` directory once built, or in the `public/assets` directory in development mode), using [yaml](http://yaml.org/) format.
1bc75494 BW	4
	5	```yaml
	6	---
	7	# Homepage configuration
	8	# See https://fontawesome.com/icons for icons options
	9
fd12de9e	10	# Optional: Use external configuration file.
1bc75494 BW	11	# Using this will ignore remaining config in this file
	12	# externalConfig: https://example.com/server-luci/config.yaml
	13
	14	title: "App dashboard"
	15	subtitle: "Homer"
a02961b7	16	# documentTitle: "Welcome" # Customize the browser tab text
ffe3404a	17	logo: "assets/logo.png"
1bc75494 BW	18	# Alternatively a fa icon can be provided:
	19	# icon: "fas fa-skull-crossbones"
	20
	21	header: true # Set to false to hide the header
	22	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.
	23
	24	columns: "3" # "auto" or number (must be a factor of 12: 1, 2, 3, 4, 6, 12)
	25	connectivityCheck: true # whether you want to display a message when the apps are not accessible anymore (VPN disconnected for example)
	26
fea0f090 BW	27	# Optional: Proxy / hosting option
fea0f090 BW	28	proxy:
66a434e7 BW	29	# NOT All custom services implements this new option YET. Support will be extended very soon.
66a434e7 BW	30	useCredentials: false # send cookies & authorization headers when fetching service specific data. Set to `true` if you use an authentication proxy. Can be overrided on service level.
fea0f090	31
1bc75494	32	# Optional theming
86f4680a	33	theme: default # 'default' or one of the themes available in 'src/assets/themes'.
1bc75494	34
71cf63eb	35	# Optional custom stylesheet
8e5ee54a GC	36	# Will load custom CSS files. Especially useful for custom icon sets.
	37	# stylesheet:
	38	# - "assets/custom.css"
71cf63eb	39
86f4680a	40	# Here is the exhaustive list of customization parameters
1bc75494 BW	41	# However all value are optional and will fallback to default if not set.
	42	# if you want to change only some of the colors, feel free to remove all unused key.
	43	colors:
	44	light:
	45	highlight-primary: "#3367d6"
	46	highlight-secondary: "#4285f4"
	47	highlight-hover: "#5a95f5"
	48	background: "#f5f5f5"
	49	card-background: "#ffffff"
	50	text: "#363636"
	51	text-header: "#424242"
	52	text-title: "#303030"
	53	text-subtitle: "#424242"
	54	card-shadow: rgba(0, 0, 0, 0.1)
3faeac7e	55	link: "#3273dc"
1bc75494	56	link-hover: "#363636"
154e6efe	57	background-image: "assets/your/light/bg.png"
1bc75494 BW	58	dark:
	59	highlight-primary: "#3367d6"
	60	highlight-secondary: "#4285f4"
	61	highlight-hover: "#5a95f5"
	62	background: "#131313"
	63	card-background: "#2b2b2b"
	64	text: "#eaeaea"
	65	text-header: "#ffffff"
	66	text-title: "#fafafa"
	67	text-subtitle: "#f5f5f5"
	68	card-shadow: rgba(0, 0, 0, 0.4)
3faeac7e	69	link: "#3273dc"
1bc75494	70	link-hover: "#ffdd57"
154e6efe	71	background-image: "assets/your/dark/bg.png"
1bc75494 BW	72
	73	# Optional message
	74	message:
	75	# url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below.
6d29bc27	76	# mapping: # allows to map fields from the remote format to the one expected by Homer
	77	# title: 'id' # use value from field 'id' as title
	78	# content: 'value' # value from field 'value' as content
9542de6e	79	# refreshInterval: 10000 # Optional: time interval to refresh message
6d29bc27	80	#
	81	# Real example using chucknorris.io for showing Chuck Norris facts as messages:
	82	# url: https://api.chucknorris.io/jokes/random
	83	# mapping:
	84	# title: 'id'
	85	# content: 'value'
1ddf3941	86	# refreshInterval: 10000
1bc75494 BW	87	style: "is-warning"
1bc75494 BW	88	title: "Optional message!"
0e045b4c	89	icon: "fa fa-exclamation-triangle"
1bc75494 BW	90	content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
	91
	92	# Optional navbar
	93	# links: [] # Allows for navbar (dark mode, layout, and search) without any links
	94	links:
	95	- name: "Link 1"
	96	icon: "fab fa-github"
	97	url: "https://github.com/bastienwirtz/homer"
	98	target: "_blank" # optional html tag target attribute
	99	- name: "link 2"
	100	icon: "fas fa-book"
	101	url: "https://github.com/bastienwirtz/homer"
e3bd2ecc	102	# this will link to a second homer page that will load config from page2.yml and keep default config values as in config.yml file
	103	# see url field and assets/page.yml used in this example:
	104	- name: "Second Page"
	105	icon: "fas fa-file-alt"
c6267296	106	url: "#page2"
1bc75494 BW	107
1bc75494 BW	108	# Services
86f4680a	109	# First level array represents a group.
1bc75494 BW	110	# Leave only a "items" key if not using group (group name, icon & tagstyle are optional, section separation will not be displayed).
	111	services:
	112	- name: "Application"
62ec6fa0	113	icon: "fas fa-code-branch"
8e093313 GC	114	# A path to an image can also be provided. Note that icon take precedence if both icon and logo are set.
8e093313 GC	115	# logo: "path/to/logo"
1bc75494 BW	116	items:
	117	- name: "Awesome app"
	118	logo: "assets/tools/sample.png"
	119	# Alternatively a fa icon can be provided:
	120	# icon: "fab fa-jenkins"
	121	subtitle: "Bookmark example"
	122	tag: "app"
	123	url: "https://www.reddit.com/r/selfhosted/"
	124	target: "_blank" # optional html tag target attribute
	125	- name: "Another one"
	126	logo: "assets/tools/sample2.png"
	127	subtitle: "Another application"
	128	tag: "app"
	129	# Optional tagstyle
	130	tagstyle: "is-success"
	131	url: "#"
	132	- name: "Other group"
	133	icon: "fas fa-heartbeat"
	134	items:
9a14de00	135	- name: "Pi-hole"
1bc75494	136	logo: "assets/tools/sample.png"
c5eab80d	137	# subtitle: "Network-wide Ad Blocking" # optional, if no subtitle is defined, PiHole statistics will be shown
1bc75494	138	tag: "other"
9a14de00 BW	139	url: "http://192.168.0.151/admin"
9a14de00 BW	140	type: "PiHole" # optional, loads a specific component that provides extra features. MUST MATCH a file name (without file extension) available in `src/components/services`
e9afa4d7 TP	141	target: "_blank" # optional html a tag target attribute
e9afa4d7 TP	142	# class: "green" # optional custom CSS class for card, useful with custom stylesheet
be308259	143	# background: red # optional color for card to set color directly without custom stylesheet
1bc75494 BW	144	```
1bc75494 BW	145
9e0ef05e	146	View [Custom Services](customservices.md) for details about all available custom services (like PiHole) and how to configure them.
fd12de9e	147
9542de6e	148	If you choose to fetch message information from an endpoint, the output format should be as follows (or you can [custom map fields as shown in tips-and-tricks](./tips-and-tricks.md#mapping-fields)):
1bc75494 BW	149
	150	```json
	151	{
	152	"style": null,
	153	"title": "Lorem ipsum 42",
	154	"content": "LA LA LA Lorem ipsum dolor sit amet, ....."
	155	}
	156	```
	157
	158	`null` value or missing keys will be ignored and value from the `config.yml` will be used if available.
	159	Empty values (either in `config.yml` or the endpoint data) will hide the element (ex: set `"title": ""` to hide the title bar).
	160
1d3287dc	161	## Style Options
1bc75494 BW	162
	163	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:
	164
	165	- `is-info` (blue)
	166	- `is-success` (green)
	167	- `is-warning` (yellow)
	168	- `is-danger` (red)
	169
	170	You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers/syntax/) for other options regarding size, style, or state.
d1b9dea2	171
1d3287dc	172	## PWA Icons
d1b9dea2 BW	173
	174	In order to easily generate all required icon preset for the PWA to work, a tool like [vue-pwa-asset-generator](https://www.npmjs.com/package/vue-pwa-asset-generator) can be used:
	175
	176	```bash
	177	npx vue-pwa-asset-generator -a {your_512x512_source_png} -o {your_output_folder}
	178	```
c3878bca	179
1d3287dc	180	## Supported services
c3878bca AW	181
	182	Currently the following services are supported for showing quick infos on the card. They can be used by setting the type to one of the following values at the item.
	183
	184	- PiHole
	185	- AdGuardHome
	186	- PaperlessNG
	187	- Mealie
	188
1d3287dc BW	189	## Additional configuration
	190
	191	### Paperless
c3878bca	192
c3878bca AW	193	For Paperless you need an API-Key which you have to store at the item in the field `apikey`.
c3878bca AW	194
1d3287dc BW	195	### Mealie
1d3287dc BW	196
4386cd09	197	First off make sure to remove an existing `subtitle` as it will take precedence if set. Setting `type: "Mealie"` will then show the number of recipes Mealie is keeping organized or the planned meal for today if one is planned. You will have to set an API key in the field `apikey` which can be created in your Mealie installation.