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

# Troubleshooting

## My docker container refuse to start / is stuck at restarting.

You might be facing a permission issue. First of all, check your container logs (adjust the container name if necessary): 

```sh
$ docker logs homer
[...]
Assets directory not writable. Check assets directory permissions & docker user or skip default assets install by setting the INIT_ASSETS env var to 0
```

In this case you need to make sure your mounted assets directory have the same GID / UID the container user have (default 1000:1000), and that the read and write permission is granted for the user or the group.

You can either: 
- Update your assets directory permissions (ex: `chown -R 1000:1000 /your/assets/folder/`, `chmod -R u+rw /your/assets/folder/`)
- Change the docker user by using the `--user` arguments with docker cli or `user: 1000:1000` with docker compose.

⚠️ Notes: 

- **Do not** use env var to set the GID / UID of the user running container. Use the Docker `user` option.
- **Do not** use 0:0 as a user value, it would be a security risk, and it's not guaranty to work.

Check this [thread](https://github.com/bastienwirtz/homer/issues/459) for more information about debugging
permission issues.

## My custom service card doesn't work, nothing appears or offline status is displayed (pi-hole, sonarr, ping, ...)

You might be facing a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (Cross Origin Request Sharing) issue.
It happens when the targeted service is hosted on a different domain or port.
Web browsers will not allow to fetch information from a different site without explicit permissions (the targeted service
must include a special `Access-Control-Allow-Origin: *` HTTP headers).
If this happens your web console (`ctrl+shift+i` or `F12`) will be filled with this kind of errors:

```text
Access to fetch at 'https://<target-service>' from origin 'https://<homer>' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
```

To resolve this, you can either:

* Host all your target service under the same domain & port.
* Modify the target server configuration so that the response of the server included following header- `Access-Control-Allow-Origin: *` (<https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests>). It might be an option in the targeted service, otherwise depending on how the service is hosted, the proxy or web server can seamlessly add it.
* Use a cors proxy server like [`cors-container`](https://github.com/imjacobclark/cors-container), [`cors-anywhere`](https://github.com/Rob--W/cors-anywhere) or many others.

## I am using an authentication proxy and homer says I am offline

This should be a configuration issue.
* Make sure the option `connectivityCheck` is set to `true` in configuration.
* Check your proxy configuration, the expected behavior is to redirect user using a 302 to the login page when user is not authenticated.

## I put my API key into the OpenWeather service and it still isn't working

If you have just made an OpenWeatherMap account and/or a newly-made API key, there is a high chance that you need to wait for it to be activated (often a few hours). If after waiting it still doesn't work, make sure to check the location you have provided since it may be an invalid location.

For some basic debugging steps, you can: 
* Check with a large city such as Amsterdam as the specified location within your configuration.
* Make sure your web browser is running the latest version of the homer configuration after updating the location (Ctrl + Shift + R).
* Check for errors within the browser console (Ctrl + Shift + I) relating to api.openweathermap.org
Commit	Line	Data
7129af3b BW	1	# Troubleshooting
7129af3b BW	2
b5bf9774 BW	3	## My docker container refuse to start / is stuck at restarting.
	4
	5	You might be facing a permission issue. First of all, check your container logs (adjust the container name if necessary):
	6
	7	```sh
	8	$ docker logs homer
	9	[...]
	10	Assets directory not writable. Check assets directory permissions & docker user or skip default assets install by setting the INIT_ASSETS env var to 0
	11	```
	12
05912080	13	In this case you need to make sure your mounted assets directory have the same GID / UID the container user have (default 1000:1000), and that the read and write permission is granted for the user or the group.
b5bf9774 BW	14
	15	You can either:
	16	- Update your assets directory permissions (ex: `chown -R 1000:1000 /your/assets/folder/`, `chmod -R u+rw /your/assets/folder/`)
	17	- Change the docker user by using the `--user` arguments with docker cli or `user: 1000:1000` with docker compose.
	18
	19	⚠️ Notes:
	20
	21	- Do not use env var to set the GID / UID of the user running container. Use the Docker `user` option.
	22	- Do not use 0:0 as a user value, it would be a security risk, and it's not guaranty to work.
	23
	24	Check this [thread](https://github.com/bastienwirtz/homer/issues/459) for more information about debugging
	25	permission issues.
	26
7129af3b BW	27	## My custom service card doesn't work, nothing appears or offline status is displayed (pi-hole, sonarr, ping, ...)
7129af3b BW	28
b5bf9774	29	You might be facing a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (Cross Origin Request Sharing) issue.
7129af3b BW	30	It happens when the targeted service is hosted on a different domain or port.
	31	Web browsers will not allow to fetch information from a different site without explicit permissions (the targeted service
	32	must include a special `Access-Control-Allow-Origin: *` HTTP headers).
e4b07784	33	If this happens your web console (`ctrl+shift+i` or `F12`) will be filled with this kind of errors:
7129af3b BW	34
	35	```text
	36	Access to fetch at 'https://<target-service>' from origin 'https://<homer>' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
	37	```
	38
	39	To resolve this, you can either:
	40
	41	* Host all your target service under the same domain & port.
e4b07784 SB	42	* Modify the target server configuration so that the response of the server included following header- `Access-Control-Allow-Origin: *` (<https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests>). It might be an option in the targeted service, otherwise depending on how the service is hosted, the proxy or web server can seamlessly add it.
e4b07784 SB	43	* Use a cors proxy server like [`cors-container`](https://github.com/imjacobclark/cors-container), [`cors-anywhere`](https://github.com/Rob--W/cors-anywhere) or many others.
95249e11 P	44
	45	## I am using an authentication proxy and homer says I am offline
	46
	47	This should be a configuration issue.
	48	* Make sure the option `connectivityCheck` is set to `true` in configuration.
	49	* Check your proxy configuration, the expected behavior is to redirect user using a 302 to the login page when user is not authenticated.
3ed40599 C	50
	51	## I put my API key into the OpenWeather service and it still isn't working
	52
	53	If you have just made an OpenWeatherMap account and/or a newly-made API key, there is a high chance that you need to wait for it to be activated (often a few hours). If after waiting it still doesn't work, make sure to check the location you have provided since it may be an invalid location.
	54
	55	For some basic debugging steps, you can:
	56	* Check with a large city such as Amsterdam as the specified location within your configuration.
	57	* Make sure your web browser is running the latest version of the homer configuration after updating the location (Ctrl + Shift + R).
	58	* Check for errors within the browser console (Ctrl + Shift + I) relating to api.openweathermap.org