diff options
Diffstat (limited to 'docs/versioned_docs/version-v0.26.0/14-Guides')
5 files changed, 277 insertions, 0 deletions
diff --git a/docs/versioned_docs/version-v0.26.0/14-Guides/01-legacy-container-upgrade.md b/docs/versioned_docs/version-v0.26.0/14-Guides/01-legacy-container-upgrade.md new file mode 100644 index 00000000..d95c1c1e --- /dev/null +++ b/docs/versioned_docs/version-v0.26.0/14-Guides/01-legacy-container-upgrade.md @@ -0,0 +1,66 @@ +# Legacy Container Upgrade + +Karakeep'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:${KARAKEEP_VERSION:-release} ++ image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_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:${KARAKEEP_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/versioned_docs/version-v0.26.0/14-Guides/02-search-query-language.md b/docs/versioned_docs/version-v0.26.0/14-Guides/02-search-query-language.md new file mode 100644 index 00000000..be9739b4 --- /dev/null +++ b/docs/versioned_docs/version-v0.26.0/14-Guides/02-search-query-language.md @@ -0,0 +1,71 @@ +# Search Query Language + +Karakeep provides a search query language to filter and find bookmarks. Here are all the supported qualifiers and how to use them: + +## Basic Syntax + +- Use spaces to separate multiple conditions (implicit AND) +- Use `and`/`or` keywords for explicit boolean logic +- Use parentheses `()` for grouping conditions +- Prefix qualifiers with `-` to negate them + +## Qualifiers + +Here's a comprehensive table of all supported qualifiers: + +| Qualifier | Description | Example Usage | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| `is:fav` | Favorited bookmarks | `is:fav` | +| `is:archived` | Archived bookmarks | `-is:archived` | +| `is:tagged` | Bookmarks that has one or more tags | `is:tagged` | +| `is:inlist` | Bookmarks that are in one or more lists | `is:inlist` | +| `is:link`, `is:text`, `is:media` | Bookmarks that are of type link, text or media | `is:link` | +| `url:<value>` | Match bookmarks with URL substring | `url:example.com` | +| `#<tag>` | Match bookmarks with specific tag | `#important` | +| | Supports quoted strings for tags with spaces | `#"work in progress"` | +| `list:<name>` | Match bookmarks in specific list | `list:reading` | +| | Supports quoted strings for list names with spaces | `list:"to review"` | +| `after:<date>` | Bookmarks created on or after date (YYYY-MM-DD) | `after:2023-01-01` | +| `before:<date>` | Bookmarks created on or before date (YYYY-MM-DD) | `before:2023-12-31` | +| `feed:<name>` | Bookmarks imported from a particular rss feed | `feed:Hackernews` | +| `age:<time-range>` | Match bookmarks based on how long ago they were created. Use `<` or `>` to indicate the maximum / minimum age of the bookmarks. Supported units: `d` (days), `w` (weeks), `m` (months), `y` (years). | `age:<1d` `age:>2w` `age:<6m` `age:>3y` | + +### Examples + +```plaintext +# Find favorited bookmarks from 2023 that are tagged "important" +is:fav after:2023-01-01 before:2023-12-31 #important + +# Find archived bookmarks that are either in "reading" list or tagged "work" +is:archived and (list:reading or #work) + +# Find bookmarks that are not tagged or not in any list +-is:tagged or -is:inlist +``` + +## Combining Conditions + +You can combine multiple conditions using boolean logic: + +```plaintext +# Find favorited bookmarks from 2023 that are tagged "important" +is:fav after:2023-01-01 before:2023-12-31 #important + +# Find archived bookmarks that are either in "reading" list or tagged "work" +is:archived and (list:reading or #work) + +# Find bookmarks that are not favorited and not archived +-is:fav -is:archived +``` + +## Text Search + +Any text not part of a qualifier will be treated as a full-text search: + +```plaintext +# Search for "machine learning" in bookmark content +machine learning + +# Combine text search with qualifiers +machine learning is:fav +``` diff --git a/docs/versioned_docs/version-v0.26.0/14-Guides/03-singlefile.md b/docs/versioned_docs/version-v0.26.0/14-Guides/03-singlefile.md new file mode 100644 index 00000000..c0f4e174 --- /dev/null +++ b/docs/versioned_docs/version-v0.26.0/14-Guides/03-singlefile.md @@ -0,0 +1,46 @@ +# Using Karakeep with SingleFile Extension + +Karakeep supports being a destination for the [SingleFile extension](https://github.com/gildas-lormeau/SingleFile). This has the benefit of allowing you to use the singlefile extension to hoard links as you're seeing them in the browser. This is perfect for websites that don't like to get crawled, has annoying cookie banner or require authentication. + +## Setup + +1. Install the [SingleFile extension](https://github.com/gildas-lormeau/SingleFile). +2. In the extension settings, select `Destinations`. +3. Select `upload to a REST Form API`. +4. In the URL, insert the address: `https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile`. +5. In the `authorization token` field, paste an API key that you can get from your karakeep settings. +6. Set `data field name` to `file`. +7. Set `URL field name` to `url`. +8. (Optional) Add `&ifexists=MODE` to the URL where MODE is one of `skip`, `overwrite`, `overwrite-recrawl`, `append`, or `append-recrawl`. See "Handling Existing Bookmarks" section below for details. + +Now, go to any page and click the singlefile extension icon. Once it's done with the upload, the bookmark should show up in your karakeep instance. Note that the singlefile extension doesn't show any progress on the upload. Given that archives are typically large, it might take 30+ seconds until the upload is done and starts showing up in Karakeep. + +## Handling Existing Bookmarks + +When uploading a page that already exists in your archive (same URL), you can control the behavior by setting the `ifexists` query parameter in the upload URL. The available modes are: + +- `skip` (default): If the bookmark already exists, skip creating a new one +- `overwrite`: Replace existing precrawled archive (only the most recent archive is kept) +- `overwrite-recrawl`: Replace existing archive and queue a recrawl to update content +- `append`: Add new archive version alongside existing ones +- `append-recrawl`: Add new archive and queue a recrawl + +To use these modes, append `?ifexists=MODE` to your upload URL, replacing `MODE` with your desired behavior. + +For example: +`https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile?ifexists=overwrite` + + +## Recommended settings + +In the singlefile extension, you probably will want to change the following settings for better experience: +* Stylesheets > compress CSS content: on +* Stylesheets > group duplicate stylesheets together: on +* HTML content > remove frames: on + +Also, you most likely will want to change the default `MAX_ASSET_SIZE_MB` in karakeep to something higher, for example `100`. + +:::info +Currently, we don't support screenshots for singlefile uploads, but this will change in the future. +::: + diff --git a/docs/versioned_docs/version-v0.26.0/14-Guides/04-hoarder-to-karakeep-migration.md b/docs/versioned_docs/version-v0.26.0/14-Guides/04-hoarder-to-karakeep-migration.md new file mode 100644 index 00000000..289a091c --- /dev/null +++ b/docs/versioned_docs/version-v0.26.0/14-Guides/04-hoarder-to-karakeep-migration.md @@ -0,0 +1,28 @@ +# Hoarder to Karakeep Migration + +Hoarder is rebranding to Karakeep. Due to github limitations, the old docker image might not be getting new updates after the rebranding. You might need to update your docker image to point to the new karakeep image instead by applying the following change in the docker compose file. + +```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:${HOARDER_VERSION:-release} ++ image: ghcr.io/karakeep-app/karakeep:${HOARDER_VERSION:-release} +``` + +You can also change the `HOARDER_VERSION` environment variable but if you do so remember to change it in the `.env` file as well. + +## Migrating a Baremetal Installation + +If you previously used the [Debian/Ubuntu install script](https://docs.karakeep.app/Installation/debuntu) to install Hoarder, there is an option to migrate your installation to Karakeep. + +```bash +bash karakeep-linux.sh migrate +``` + +This will migrate your installation with no user input required. After the migration, the script will also check for an update. diff --git a/docs/versioned_docs/version-v0.26.0/14-Guides/05-different-ai-providers.md b/docs/versioned_docs/version-v0.26.0/14-Guides/05-different-ai-providers.md new file mode 100644 index 00000000..33408c00 --- /dev/null +++ b/docs/versioned_docs/version-v0.26.0/14-Guides/05-different-ai-providers.md @@ -0,0 +1,66 @@ +# Configuring different AI Providers + +Karakeep uses LLM providers for AI tagging and summarization. We support OpenAI-compatible providers and ollama. This guide will show you how to configure different providers. + +## OpenAI + +If you want to use OpenAI itself, you just need to pass in the OPENAI_API_KEY environment variable. + +``` +OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +# You can change the default models by uncommenting the following lines, and choosing your model. +# INFERENCE_TEXT_MODEL=gpt-4.1-mini +# INFERENCE_IMAGE_MODEL=gpt-4o-mini +``` + +## Ollama + +Ollama is a local LLM provider that you can use to run your own LLM server. You'll need to pass ollama's address to karakeep and you need to ensure that it's accessible from within the karakeep container (e.g. no localhost addresses). + +``` +# MAKE SURE YOU DON'T HAVE OPENAI_API_KEY set, otherwise it takes precedence. + +OLLAMA_BASE_URL=http://ollama.mylab.com:11434 + +# Make sure to pull the models in ollama first. Example models: +INFERENCE_TEXT_MODEL=gemma3 +INFERENCE_IMAGE_MODEL=llava + +# If the model you're using doesn't support structured output, you also need: +# INFERENCE_OUTPUT_SCHEMA=plain +``` + +## Gemini + +Gemini has an OpenAI-compatible API. You need to get an api key from Google AI Studio. + +``` + +OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta +OPENAI_API_KEY=YOUR_API_KEY + +# Example models: +INFERENCE_TEXT_MODEL=gemini-2.0-flash +INFERENCE_IMAGE_MODEL=gemini-2.0-flash +``` + +## OpenRouter + +``` +OPENAI_BASE_URL=https://openrouter.ai/api/v1 +OPENAI_API_KEY=YOUR_API_KEY + +# Example models: +INFERENCE_TEXT_MODEL=meta-llama/llama-4-scout +INFERENCE_IMAGE_MODEL=meta-llama/llama-4-scout +``` + +## Perplexity + +``` +OPENAI_BASE_URL: https://api.perplexity.ai +OPENAI_API_KEY: Your Perplexity API Key +INFERENCE_TEXT_MODEL: sonar-pro +INFERENCE_IMAGE_MODEL: sonar-pro +``` |