Skip to main content
Version: 1.30.0

Integrations

Integrations are connections to supported third party applications. This page will describe the process of managing integrations but the process may vary depending on your specific integration. Check the available integrations for further information.

Create an integration​

To create an integration, you can choose the supported application from the dropdown at the top right:

Next, you'll need to fill out the required fields to configure the integration:

Name​

Must be at least 1 character long, can be chosen freely.

Url​

This must be the base URL of the application where Homarr should connect to. A few examples for this field include:

  • sabnzbd.example.com
  • example.com/sabnzbd

You must not append any path after the base URL. Some examples for incorrect usage:

  • sabnzbd.example.com/settings
  • example.com/sabnzbd/settings

Secrets​

An integration may or may not require secrets to function. To process to obtain them is usually documented in the integration pages. Secrets are encrypted using a symmetric encryption and stored in the database. To improve security, they will never be passed to the client and requests to the integrations are performed from the host where Hoamrr is running on.

Testing and saving integration​

It is not allowed to create an integration without passing the test. This is to ensure that you minimize the amount of broken applications on your Homarr instance. The test and create button will perform a network request to the application and authenticate if required.

Troubleshooting connection​

The connection to your integrations can fail due to many factors. Most of the time it should show you the reason why it failed. If it doesn't, you can follow these steps to troubleshoot the issue:

  1. Check whether you are using the correct URL and secrets.
    • The URL must be the base URL of the application, without any paths.
    • The secrets must be correct and have the correct permissions.
  2. If you use https to connect to the application, check the chapter below about certificate issues.
  3. Check whether you followed the Homarr documentation and didn't skip any steps. This is the most often mistake that create many noisy support requests and following all steps will often resolve the problems.
  4. Check Homarr's logs for more information. As we have no control over breaking changes in upstream APIs and third party software, they can break without notice in unexpected ways which can also lead to errors within Homarr. In such case, these occurrences must be reported and fixed within the source code of Homarr.
  5. Check whether the host can reach the destination hostname / IP using ping and curl or wget afterward. Execute this command on the host machine, not inside containers, to check whether it can connect or not.
  6. Check whether the container / pod can reach the destination hostname / IP. Execute the same commands in the shell inside the container / pod.
  7. Check your reverse proxy / authentication proxy logs for failures / hints
  8. Check your security log of tunnels and VPNs
  9. Check your router for security events
  10. Check your VLAN configuration and firewall rules
  11. Check your DNS settings for the host machine and the containers / pods and whether they can resolve the hostnames
  12. Check throughput and stability of your network connection using iperf3
  13. Check syslog / drivers of your OS for hints
  14. Check logs of your destination applications (eg. SABnzbd)
  15. Attempt to disable CSRF / tamper protections when absolutely no other workaround available -> this comes with some security implications - be careful! Re-enable if this didn't fix the issue.

If none of these troubleshooting steps worked, you can request support from our team in Discord or GitHub.

Certificate issues​

If you are using a self-signed certificate you'll need to add it to the trusted certificates in Homarr. Most of the time you should also get a button to add the certificate automatically when you try to connect to the integration. Please check that the certificate is the one you are expecting to prevent Man in the Middle attacks. For some integrations, you can find a guide on how to retrieve the certificate here.