homer/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):

$ 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 assests 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 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 (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:

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, 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.