Thomas Camlong
6692acbd33
- Remove 179 format-only file changes (docs, migrations, plex, patchmon, CSS) - Delete .cursor/goal files from git tracking - Delete 4 dead /api/about routes (unused, data loaded from static JSON) - Fix resolveAlias to use absolute paths (CodeRabbit) - Fix Tailwind classes in Mantine app layout fallback (CodeRabbit) - Return stale data during cache revalidation (CodeRabbit)
98 lines
5.5 KiB
Plaintext
98 lines
5.5 KiB
Plaintext
---
|
|
tags:
|
|
- Integrations
|
|
- Data sources
|
|
- Connections
|
|
---
|
|
|
|
# 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](/docs/category/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:
|
|
- http://sabnzbd.example.com
|
|
- https://example.com/sabnzbd
|
|
|
|
You must not append any path after the base URL. Some examples for incorrect usage:
|
|
- http://sabnzbd.example.com/settings
|
|
- https://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](/docs/category/integrations).
|
|
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 Homarr is running on.
|
|
|
|
### Linking applications
|
|
|
|
During the creation of an integration you can choose to add / link an application to the integration.
|
|
If you want to add one, you can simply specify the app url which will be used for opening the application from Homarr.
|
|
The linked application will also be used for any links the integration widget contains.
|
|
If you already have an application created, you can also link it to the integration by selecting it from the dropdown.
|
|
On the edit page you can always change or remove the linked application.
|
|
|
|
### 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.
|
|
|
|
## Managing permissions
|
|
|
|
On the edit page of an integration, you can manage which users / groups can
|
|
|
|
- **Select the integration in items:** Allows users to select the integration and showing data on their board.
|
|
- **Interact with the integration:** Allows users to perform actions on the integration, such as pausing a download.
|
|
- **Full control over the integration:** Allows users to modify the integration properties, including the URL and secrets.
|
|
|
|
|
|
|
|
## 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](#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](../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](../certificates/#obtaining-certificates). |