diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/1.png b/docs/public/assets/screenshots/app-troubleshooting-guide/1.png new file mode 100644 index 00000000..e6b5f311 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/1.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/10.png b/docs/public/assets/screenshots/app-troubleshooting-guide/10.png new file mode 100644 index 00000000..2d7ff54b Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/10.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/11.png b/docs/public/assets/screenshots/app-troubleshooting-guide/11.png new file mode 100644 index 00000000..c5ee1cf8 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/11.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/12.png b/docs/public/assets/screenshots/app-troubleshooting-guide/12.png new file mode 100644 index 00000000..8ca427da Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/12.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/13.png b/docs/public/assets/screenshots/app-troubleshooting-guide/13.png new file mode 100644 index 00000000..e88e1e65 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/13.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/14.png b/docs/public/assets/screenshots/app-troubleshooting-guide/14.png new file mode 100644 index 00000000..554838f5 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/14.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/15.png b/docs/public/assets/screenshots/app-troubleshooting-guide/15.png new file mode 100644 index 00000000..55ca766c Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/15.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/16.png b/docs/public/assets/screenshots/app-troubleshooting-guide/16.png new file mode 100644 index 00000000..058a6e9d Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/16.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/17.png b/docs/public/assets/screenshots/app-troubleshooting-guide/17.png new file mode 100644 index 00000000..ac82ff24 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/17.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/18.png b/docs/public/assets/screenshots/app-troubleshooting-guide/18.png new file mode 100644 index 00000000..c24e2857 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/18.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/19.png b/docs/public/assets/screenshots/app-troubleshooting-guide/19.png new file mode 100644 index 00000000..c34a77c4 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/19.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/2.png b/docs/public/assets/screenshots/app-troubleshooting-guide/2.png new file mode 100644 index 00000000..36269d59 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/2.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/20.png b/docs/public/assets/screenshots/app-troubleshooting-guide/20.png new file mode 100644 index 00000000..6f46ac7b Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/20.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/3.png b/docs/public/assets/screenshots/app-troubleshooting-guide/3.png new file mode 100644 index 00000000..58ec3ebf Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/3.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/4.png b/docs/public/assets/screenshots/app-troubleshooting-guide/4.png new file mode 100644 index 00000000..33189f33 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/4.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/5.png b/docs/public/assets/screenshots/app-troubleshooting-guide/5.png new file mode 100644 index 00000000..41604158 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/5.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/6.png b/docs/public/assets/screenshots/app-troubleshooting-guide/6.png new file mode 100644 index 00000000..5dfcac90 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/6.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/7.png b/docs/public/assets/screenshots/app-troubleshooting-guide/7.png new file mode 100644 index 00000000..50185cb3 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/7.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/8.png b/docs/public/assets/screenshots/app-troubleshooting-guide/8.png new file mode 100644 index 00000000..0209a295 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/8.png differ diff --git a/docs/public/assets/screenshots/app-troubleshooting-guide/9.png b/docs/public/assets/screenshots/app-troubleshooting-guide/9.png new file mode 100644 index 00000000..89e8efb2 Binary files /dev/null and b/docs/public/assets/screenshots/app-troubleshooting-guide/9.png differ diff --git a/docs/troubleshooting/common-issues/ApplicationErrors.md b/docs/troubleshooting/common-issues/ApplicationErrors.md new file mode 100644 index 00000000..7b83dfb5 --- /dev/null +++ b/docs/troubleshooting/common-issues/ApplicationErrors.md @@ -0,0 +1,218 @@ +# Application Troubleshooting Guide + +## Installation + +- If installation fails once, try again immediately +- If it still fails check error + - This can be done by pressing the bell icon at the top of HexOS deck + - If HexOS shows an unknown error you can find more details by entering TrueNAS and selecting the clipboard icon +::: details How to view the error in TrueNAS +1) Login to [HexOS Deck Settings](https://deck.hexos.com/settings) +2) Select the TrueNAS Button +![](../../public/assets/screenshots/app-troubleshooting-guide/1.png) +3) Login to TrueNAS + - Username: truenas_admin + - Password: What was selected when installing HexOS +![](../../public/assets/screenshots/app-troubleshooting-guide/2.png) +4) Click on the clipboard icon at the top of the screen +![](../../public/assets/screenshots/app-troubleshooting-guide/3.png) +::: + +## Updating + +An App has to be running for it to updated.
+It is good practice to update apps regularly. + +::: details How to update + +1) Open the [HexOS Deck applications](Https://deck.hexos.com/applications) section +2) Select your app +3) Select the Update button on the Application info card +![](../../public/assets/screenshots/app-troubleshooting-guide/4.png) +::: +### If an app is not working after an application update + +If your app stopped working immediately after an update you can go into TrueNAS and roll back a previous version of your app. +> Note: Some applications may have bugs when rolled back +::: details Instructions for rolling back an application + +1) Login to [HexOS Deck Settings](https://deck.hexos.com/settings) +![](../../public/assets/screenshots/app-troubleshooting-guide/1.png) +2) Select the TrueNAS Button +3) Login to TrueNAS + - Username: truenas_admin + - Password: What was selected when installing HexOS +![](../../public/assets/screenshots/app-troubleshooting-guide/2.png) +4) Navigate to the `Apps` tab on the left sidebar menu +![](../../public/assets/screenshots/app-troubleshooting-guide/5.png) +5) Click on your application +6) Select the `Rollback` option on the `Application Info` card +![](../../public/assets/screenshots/app-troubleshooting-guide/6.png) +7) Select the most recent version of the app that worked and rollback +![](../../public/assets/screenshots/app-troubleshooting-guide/7.png) +::: + +## Resetting App Curation + +If the settings on an app were changed in TrueNAS you can use `Reset App Curation` to bring it back to the HexOS default configuration. +> Note: This can be used to update your application settings if HexOS has updated the curation. +::: details How to Reset App Curation +1) Open [Hexos Deck Application](https://deck.hexos.com/application) section +2) Select the app +3) Select the `options` button on the application info card +![](../../public/assets/screenshots/app-troubleshooting-guide/8.png) +4) Select `Reset App Curation` +![](../../public/assets/screenshots/app-troubleshooting-guide/9.png) +::: + + +## Application not showing up with the bookmarked link + +- Open directly from HexOS Deck +- Check if your server's IP address has been updated + +## App not starting + +If apps are not starting after recent hardware changes you can try the following
+Motherboard changed: Try opening the app from HexOS Deck as your sever IP Address may have changed
+GPU changed: Try disabling GPU pass-through and disable using a gpu in the application configuration to troubleshoot
+::: details How to turn off GPU pass-through +1) Select the app in HexOS deck +2) Press the `options` button on the applications info card +![](../../public/assets/screenshots/app-troubleshooting-guide/20.png) +3) Press `Configure in TrueNAS` +![](../../public/assets/screenshots/app-troubleshooting-guide/11.png) +4) Scroll all the way to the bottom and uncheck GPU related options +![](../../public/assets/screenshots/app-troubleshooting-guide/12.png) +5) Press the Update button +![](../../public/assets/screenshots/app-troubleshooting-guide/13.png) +::: + +# App Specific Troubleshooting + +::: details Immich +## Immich + +> Warning: Do Not uninstall immich as a troubleshooting step unless explicitly instructed to or are planning to start again fresh + +### Installation + +If you uninstalled Immich and it is no longer re-installing +consider deleting the the old datasets and start over fresh +> Warning: Deleting the old data sets will also delete the copy of your media on the server + +### Updating Immich + +#### Firmware 1.135.0 and higher + +Coming soon + +#### Firmware below 1.135.0 + +Coming soon + +### Mobile Application not functioning + +Update the Immich app on both the server side and the mobile side + +### Immich Media not showing up + +Check the storage paths in the settings
+Uploads: (HDDs/SSDs)/Photos/immich
+Postgres: (HDDs/SSDs)/Applications/immich/postgres_data
+ + +If your storage locations do not match and you installed Immich via HexOS, are on Immich version 2.0.0+ and have not modified Immich in TrueNAS then you can `Reset App Curation` + +::: +# What to do if you need more help with apps + +Fill out the following template and share it in on [HexOS HUB](https://hub.hexos.com) or contact us at Support@hexos.com + +## Template + +TrueNAS Version:
+Application Version:
+Model of CPU:
+Model of GPU:
+Modifications made in TrueNAS:
+Description of problem:
+Troubleshooting steps attempted:
+ +::: details TrueNAS Version + +TrueNAS Version can be found by +1) Login to [HexOS Deck Settings](https://deck.hexos.com/settings) +2) Select the TrueNAS Button +![](../../public/assets/screenshots/app-troubleshooting-guide/1.png) +3) Login to TrueNAS + - Username: truenas_admin + - Password: What was selected when installing HexOS +![](../../public/assets/screenshots/app-troubleshooting-guide/2.png) +4) On the system information card you will see your TrueNAS Version +![](../../public/assets/screenshots/app-troubleshooting-guide/19.png) + +::: +::: details Application Version + +The application Version can be found by +1) Login to [HexOS Deck Settings](https://deck.hexos.com/settings) +2) Select the TrueNAS Button +![](../../public/assets/screenshots/app-troubleshooting-guide/1.png) +3) Login to TrueNAS + - Username: truenas_admin + - Password: What was selected when installing HexOS +![](../../public/assets/screenshots/app-troubleshooting-guide/2.png) +4) Navigate to the `Apps` tab on the left sidebar menu +5) Click on your application +6) On the `Application Info` card you will see an `App Version` +![](../../public/assets/screenshots/app-troubleshooting-guide/15.png) +::: + +::: details Model of CPU + +The model of the CPU in your server can be found by +1) Login to [HexOS Deck Settings](https://deck.hexos.com/settings) +2) Select the TrueNAS Button +![](../../public/assets/screenshots/app-troubleshooting-guide/1.png) +3) Login to TrueNAS + - Username: truenas_admin + - Password: What was selected when installing HexOS +![](../../public/assets/screenshots/app-troubleshooting-guide/2.png) +4) On the `CPU Model` card you will see your CPU Model +::: + +::: details Model of GPU +1) Login to [HexOS Deck Settings](https://deck.hexos.com/settings) +2) Select the TrueNAS Button +![](../../public/assets/screenshots/app-troubleshooting-guide/1.png) +3) Login to TrueNAS + - Username: truenas_admin + - Password: What was selected when installing HexOS +![](../../public/assets/screenshots/app-troubleshooting-guide/2.png) +4) Navigate to the `System` tab on the left sidebar menu +![](../../public/assets/screenshots/app-troubleshooting-guide/16.png) +5) Select `Shell` +![](../../public/assets/screenshots/app-troubleshooting-guide/17.png) +6) Type `lspci | egrep -i 'vga|3d|display'` +![](../../public/assets/screenshots/app-troubleshooting-guide/18.png) +::: +::: details Modifications made in TrueNAS + +Example modifications +- App installed via TrueNAS not HexOS +- Storage pool created in TrueNAS not HexOS +- App configuration modified in TrueNAS +::: +::: details Description of the problem + +Describe the problem +When did it start? +What steps did you take before the problem started? + +Include any errors reports that HexOS or TrueNAS informs you of in this section. +::: +::: details Troubleshooting steps attempted + +A brief overview of any steps you have tried. +:::