From a1c62e5be4212709154337a932ec7ff8920d89a2 Mon Sep 17 00:00:00 2001 From: Mohamed Bassem Date: Sun, 29 Dec 2024 17:44:40 +0000 Subject: docs: Add troubleshooting guide --- .github/ISSUE_TEMPLATE/bug_report.yml | 12 +++- docs/docs/12-community-projects.md | 32 ----------- docs/docs/12-troubleshooting.md | 33 +++++++++++ docs/docs/13-Guides/01-legacy-container-upgrade.md | 66 ---------------------- docs/docs/13-community-projects.md | 32 +++++++++++ docs/docs/14-Guides/01-legacy-container-upgrade.md | 66 ++++++++++++++++++++++ 6 files changed, 142 insertions(+), 99 deletions(-) delete mode 100644 docs/docs/12-community-projects.md create mode 100644 docs/docs/12-troubleshooting.md delete mode 100644 docs/docs/13-Guides/01-legacy-container-upgrade.md create mode 100644 docs/docs/13-community-projects.md create mode 100644 docs/docs/14-Guides/01-legacy-container-upgrade.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index bc9de30d..7b19ef6b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -7,7 +7,7 @@ body: value: | Thanks for taking the time to fill out a bug report! Please note that this form is for reporting bugs in existing supported functionality. - + If you are reporting something that's not an issue in functionality we've previously supported and/or is simply something different to your expectations, then it may be more appropriate to raise via a feature or support request instead. - type: textarea id: description @@ -59,3 +59,13 @@ body: placeholder: (eg. v0.18.0) validations: required: true + + - type: checkboxes + id: confirm-troubleshooting + attributes: + label: Have you checked the troubleshooting guide? + description: | + We have a troubleshooting guide that you can find [here](https://docs.hoarder.app/next/troubleshooting). Please check it out as you might find a solution to your problem. + options: + - label: I have checked the troubleshooting guide and I haven't found a solution to my problem + required: true diff --git a/docs/docs/12-community-projects.md b/docs/docs/12-community-projects.md deleted file mode 100644 index 42424413..00000000 --- a/docs/docs/12-community-projects.md +++ /dev/null @@ -1,32 +0,0 @@ -# Community Projects - -This page lists community projects that are built around Hoarder, but not officially supported by the development team. - -:::warning -This list comes with no guarantees about security, performance, reliability, or accuracy. Use at your own risk. -::: - - -### Raycast Extension - -*By [@luolei](https://github.com/foru17).* - -A user-friendly Raycast extension that seamlessly integrates with Hoarder, bringing powerful bookmark management to your fingertips. Quickly save, search, and organize your bookmarks, texts, and images—all through Raycast's intuitive interface. - -Get it [here](https://www.raycast.com/luolei/hoarder). - -### Alfred Workflow - -*By [@yinan-c](https://github.com/yinan-c)* - -An Alfred workflow to quickly hoard stuff or access your hoarded bookmarks! - -Get it [here](https://www.alfredforum.com/topic/22528-hoarder-workflow-for-self-hosted-bookmark-management/). - -### Telegram Bot - -*By [@Madh93](https://github.com/Madh93)* - -A Telegram Bot for saving bookmarks to Hoarder directly through Telegram. - -Get it [here](https://github.com/Madh93/hoarderbot). diff --git a/docs/docs/12-troubleshooting.md b/docs/docs/12-troubleshooting.md new file mode 100644 index 00000000..15356309 --- /dev/null +++ b/docs/docs/12-troubleshooting.md @@ -0,0 +1,33 @@ +# Troubleshooting + +## SqliteError: no such table: user + +This usually means that there's something wrong with the database setup (more concretely, it means that the database is not initialized). This can be caused by multiple problems: +1. **Wiped DATA_DIR:** Your `DATA_DIR` got wiped (or the backing storage dir changed). If you did this intentionally, restart the container so that it can re-initalize the database. +2. **Missing DATA_DIR**: You're not using the default docker compose file, and you forgot to configure the `DATA_DIR` env var. This will result into the database getting set up in a different directory than the one used by the service. + +## Chrome Failed to Read DnsConfig + +If you see this error in the logs of the chrome container, it's a benign error and you can safely ignore it. Whatever problems you're having, is unrelated to this error. + +## AI Tagging not working (when using OpenAI) + +Check the logs of the container and this will usually tell you what's wrong. Common problems are: +1. Typo in the env variable `OPENAI_API_KEY` name resulting into logs saying something like "skipping inference as it's not configured". +2. You forgot to call `docker compose up` after configuring open ai. +3. OpenAI requires pre-charging the account with credits before using it, otherwise you'll get an error like "insufficient funds". + +## AI Tagging not working (when using Ollama) + +Check the logs of the container and this will usually tell you what's wrong. Common problems are: +1. Typo in the env variable `OLLAMA_BASE_URL` name resulting into logs saying something like "skipping inference as it's not configured". +2. You forgot to call `docker compose up` after configuring ollama. +3. You didn't change the `INFERENCE_TEXT_MODEL` env variable, resulting into hoarder attempting to use gpt models with ollama which won't work. +4. Ollama server is not reachable by the hoarder container. This can be caused by: + 1. Ollama server being in a different docker network than the hoarder container. + 2. You're using `localhost` as the `OLLAMA_BASE_URL` instead of the actual address of the ollama server. `localhost` points to the container itself, not the docker host. Check this [stackoverflow answer](https://stackoverflow.com/questions/24319662/from-inside-of-a-docker-container-how-do-i-connect-to-the-localhost-of-the-mach) to find how to correctly point to the docker host address instead. + +## Crawling not working + +Check the logs of the container and this will usually tell you what's wrong. Common problems are: +1. You changed the name of the chrome container but didn't change the `BROWSER_WEB_URL` env variable. diff --git a/docs/docs/13-Guides/01-legacy-container-upgrade.md b/docs/docs/13-Guides/01-legacy-container-upgrade.md deleted file mode 100644 index 3c86705a..00000000 --- a/docs/docs/13-Guides/01-legacy-container-upgrade.md +++ /dev/null @@ -1,66 +0,0 @@ -# Legacy Container Upgrade - -Hoarder's 0.16 release consolidated the web and worker containers into a single container and also dropped the need for the redis container. The legacy containers will stop being supported soon, to upgrade to the new container do the following: - -1. Remove the redis container and its volume if it had one. -2. Move the environment variables that you've set exclusively to the `workers` container to the `web` container. -3. Delete the `workers` container. -4. Rename the web container image from `hoarder-app/hoarder-web` to `hoarder-app/hoarder`. - -```diff -diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml -index cdfc908..6297563 100644 ---- a/docker/docker-compose.yml -+++ b/docker/docker-compose.yml -@@ -1,7 +1,7 @@ - version: "3.8" - services: - web: -- image: ghcr.io/hoarder-app/hoarder-web:${HOARDER_VERSION:-release} -+ image: ghcr.io/hoarder-app/hoarder:${HOARDER_VERSION:-release} - restart: unless-stopped - volumes: - - data:/data -@@ -10,14 +10,10 @@ services: - env_file: - - .env - environment: -- REDIS_HOST: redis - MEILI_ADDR: http://meilisearch:7700 -+ BROWSER_WEB_URL: http://chrome:9222 -+ # OPENAI_API_KEY: ... - DATA_DIR: /data -- redis: -- image: redis:7.2-alpine -- restart: unless-stopped -- volumes: -- - redis:/data - chrome: - image: gcr.io/zenika-hub/alpine-chrome:123 - restart: unless-stopped -@@ -37,24 +33,7 @@ services: - MEILI_NO_ANALYTICS: "true" - volumes: - - meilisearch:/meili_data -- workers: -- image: ghcr.io/hoarder-app/hoarder-workers:${HOARDER_VERSION:-release} -- restart: unless-stopped -- volumes: -- - data:/data -- env_file: -- - .env -- environment: -- REDIS_HOST: redis -- MEILI_ADDR: http://meilisearch:7700 -- BROWSER_WEB_URL: http://chrome:9222 -- DATA_DIR: /data -- # OPENAI_API_KEY: ... -- depends_on: -- web: -- condition: service_started - - volumes: -- redis: - meilisearch: - data: -``` diff --git a/docs/docs/13-community-projects.md b/docs/docs/13-community-projects.md new file mode 100644 index 00000000..42424413 --- /dev/null +++ b/docs/docs/13-community-projects.md @@ -0,0 +1,32 @@ +# Community Projects + +This page lists community projects that are built around Hoarder, but not officially supported by the development team. + +:::warning +This list comes with no guarantees about security, performance, reliability, or accuracy. Use at your own risk. +::: + + +### Raycast Extension + +*By [@luolei](https://github.com/foru17).* + +A user-friendly Raycast extension that seamlessly integrates with Hoarder, bringing powerful bookmark management to your fingertips. Quickly save, search, and organize your bookmarks, texts, and images—all through Raycast's intuitive interface. + +Get it [here](https://www.raycast.com/luolei/hoarder). + +### Alfred Workflow + +*By [@yinan-c](https://github.com/yinan-c)* + +An Alfred workflow to quickly hoard stuff or access your hoarded bookmarks! + +Get it [here](https://www.alfredforum.com/topic/22528-hoarder-workflow-for-self-hosted-bookmark-management/). + +### Telegram Bot + +*By [@Madh93](https://github.com/Madh93)* + +A Telegram Bot for saving bookmarks to Hoarder directly through Telegram. + +Get it [here](https://github.com/Madh93/hoarderbot). diff --git a/docs/docs/14-Guides/01-legacy-container-upgrade.md b/docs/docs/14-Guides/01-legacy-container-upgrade.md new file mode 100644 index 00000000..3c86705a --- /dev/null +++ b/docs/docs/14-Guides/01-legacy-container-upgrade.md @@ -0,0 +1,66 @@ +# Legacy Container Upgrade + +Hoarder's 0.16 release consolidated the web and worker containers into a single container and also dropped the need for the redis container. The legacy containers will stop being supported soon, to upgrade to the new container do the following: + +1. Remove the redis container and its volume if it had one. +2. Move the environment variables that you've set exclusively to the `workers` container to the `web` container. +3. Delete the `workers` container. +4. Rename the web container image from `hoarder-app/hoarder-web` to `hoarder-app/hoarder`. + +```diff +diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml +index cdfc908..6297563 100644 +--- a/docker/docker-compose.yml ++++ b/docker/docker-compose.yml +@@ -1,7 +1,7 @@ + version: "3.8" + services: + web: +- image: ghcr.io/hoarder-app/hoarder-web:${HOARDER_VERSION:-release} ++ image: ghcr.io/hoarder-app/hoarder:${HOARDER_VERSION:-release} + restart: unless-stopped + volumes: + - data:/data +@@ -10,14 +10,10 @@ services: + env_file: + - .env + environment: +- REDIS_HOST: redis + MEILI_ADDR: http://meilisearch:7700 ++ BROWSER_WEB_URL: http://chrome:9222 ++ # OPENAI_API_KEY: ... + DATA_DIR: /data +- redis: +- image: redis:7.2-alpine +- restart: unless-stopped +- volumes: +- - redis:/data + chrome: + image: gcr.io/zenika-hub/alpine-chrome:123 + restart: unless-stopped +@@ -37,24 +33,7 @@ services: + MEILI_NO_ANALYTICS: "true" + volumes: + - meilisearch:/meili_data +- workers: +- image: ghcr.io/hoarder-app/hoarder-workers:${HOARDER_VERSION:-release} +- restart: unless-stopped +- volumes: +- - data:/data +- env_file: +- - .env +- environment: +- REDIS_HOST: redis +- MEILI_ADDR: http://meilisearch:7700 +- BROWSER_WEB_URL: http://chrome:9222 +- DATA_DIR: /data +- # OPENAI_API_KEY: ... +- depends_on: +- web: +- condition: service_started + + volumes: +- redis: + meilisearch: + data: +``` -- cgit v1.2.3-70-g09d2