diff options
| author | xuatz <xzlow10@gmail.com> | 2025-08-16 22:00:00 +0900 |
|---|---|---|
| committer | Mohamed Bassem <me@mbassem.com> | 2025-08-20 09:44:24 +0300 |
| commit | b3feee7e0d5b1733c32573d5df2af23d7c1cfca5 (patch) | |
| tree | 495c781f9d44dbd97e95020af9e40eae6fcd9a26 /docs | |
| parent | 17b59084c4a3345f127f45d3083254e060360bba (diff) | |
| download | karakeep-b3feee7e0d5b1733c32573d5df2af23d7c1cfca5.tar.zst | |
docs: rename docs into tmp name in a separate commit
Diffstat (limited to 'docs')
37 files changed, 0 insertions, 987 deletions
diff --git a/docs/docs/02-Installation/01-docker.md b/docs/docs/02-hamtaro-installation/01-docker.md index ff508b73..ff508b73 100644 --- a/docs/docs/02-Installation/01-docker.md +++ b/docs/docs/02-hamtaro-installation/01-docker.md diff --git a/docs/docs/02-Installation/02-unraid.md b/docs/docs/02-hamtaro-installation/02-unraid.md index 5ca3e027..5ca3e027 100644 --- a/docs/docs/02-Installation/02-unraid.md +++ b/docs/docs/02-hamtaro-installation/02-unraid.md diff --git a/docs/docs/02-Installation/03-archlinux.md b/docs/docs/02-hamtaro-installation/03-archlinux.md index 63db9d75..63db9d75 100644 --- a/docs/docs/02-Installation/03-archlinux.md +++ b/docs/docs/02-hamtaro-installation/03-archlinux.md diff --git a/docs/docs/02-Installation/04-kubernetes.md b/docs/docs/02-hamtaro-installation/04-kubernetes.md index b8c40551..b8c40551 100644 --- a/docs/docs/02-Installation/04-kubernetes.md +++ b/docs/docs/02-hamtaro-installation/04-kubernetes.md diff --git a/docs/docs/02-Installation/05-pikapods.md b/docs/docs/02-hamtaro-installation/05-pikapods.md index dad0785a..dad0785a 100644 --- a/docs/docs/02-Installation/05-pikapods.md +++ b/docs/docs/02-hamtaro-installation/05-pikapods.md diff --git a/docs/docs/02-Installation/06-debuntu.md b/docs/docs/02-hamtaro-installation/06-debuntu.md index 2f3d1113..2f3d1113 100644 --- a/docs/docs/02-Installation/06-debuntu.md +++ b/docs/docs/02-hamtaro-installation/06-debuntu.md diff --git a/docs/docs/02-Installation/07-minimal-install.md b/docs/docs/02-hamtaro-installation/07-minimal-install.md index 211bfb08..211bfb08 100644 --- a/docs/docs/02-Installation/07-minimal-install.md +++ b/docs/docs/02-hamtaro-installation/07-minimal-install.md diff --git a/docs/docs/02-Installation/08-truenas.md b/docs/docs/02-hamtaro-installation/08-truenas.md index 9b7989c2..9b7989c2 100644 --- a/docs/docs/02-Installation/08-truenas.md +++ b/docs/docs/02-hamtaro-installation/08-truenas.md diff --git a/docs/docs/02-installation/_category_.json b/docs/docs/02-hamtaro-installation/_category_.json index acb94a71..acb94a71 100644 --- a/docs/docs/02-installation/_category_.json +++ b/docs/docs/02-hamtaro-installation/_category_.json diff --git a/docs/docs/02-installation/01-docker.md b/docs/docs/02-installation/01-docker.md deleted file mode 100644 index ff508b73..00000000 --- a/docs/docs/02-installation/01-docker.md +++ /dev/null @@ -1,101 +0,0 @@ -# Docker Compose [Recommended] - -### Requirements - -- Docker -- Docker Compose - -### 1. Create a new directory - -Create a new directory to host the compose file and env variables. - -This is where you’ll place the `docker-compose.yml` file from the next step and the environment variables. - -For example you could make a new directory called "karakeep-app" with the following command: -``` -mkdir karakeep-app -``` - - -### 2. Download the compose file - -Download the docker compose file provided [here](https://github.com/karakeep-app/karakeep/blob/main/docker/docker-compose.yml) directly into your new directory. - -``` -wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml -``` - -### 3. Populate the environment variables - -To configure the app, create a `.env` file in the directory and add this minimal env file: - -``` -KARAKEEP_VERSION=release -NEXTAUTH_SECRET=super_random_string -MEILI_MASTER_KEY=another_random_string -NEXTAUTH_URL=http://localhost:3000 -``` - -You **should** change the random strings. You can use `openssl rand -base64 36` in a seperate terminal window to generate the random strings. You should also change the `NEXTAUTH_URL` variable to point to your server address. - -Using `KARAKEEP_VERSION=release` will pull the latest stable version. You might want to pin the version instead to control the upgrades (e.g. `KARAKEEP_VERSION=0.10.0`). Check the latest versions [here](https://github.com/karakeep-app/karakeep/pkgs/container/karakeep). - -Persistent storage and the wiring between the different services is already taken care of in the docker compose file. - -Keep in mind that every time you change the `.env` file, you'll need to re-run `docker compose up`. - -If you want more config params, check the config documentation [here](/configuration). - -### 4. Setup OpenAI - -To enable automatic tagging, you'll need to configure OpenAI. This is optional though but highly recommended. - -- Follow [OpenAI's help](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key) to get an API key. -- Add the OpenAI API key to the env file: - -``` -OPENAI_API_KEY=<key> -``` - -Learn more about the costs of using openai [here](/openai). - -<details> - <summary>If you want to use Ollama (https://ollama.com/) instead for local inference.</summary> - - **Note:** The quality of the tags you'll get will depend on the quality of the model you choose. - - - Make sure ollama is running. - - Set the `OLLAMA_BASE_URL` env variable to the address of the ollama API. - - Set `INFERENCE_TEXT_MODEL` to the model you want to use for text inference in ollama (for example: `llama3.1`) - - Set `INFERENCE_IMAGE_MODEL` to the model you want to use for image inference in ollama (for example: `llava`) - - Make sure that you `ollama pull`-ed the models that you want to use. - - You might want to tune the `INFERENCE_CONTEXT_LENGTH` as the default is quite small. The larger the value, the better the quality of the tags, but the more expensive the inference will be. - -</details> - -### 5. Start the service - -Start the service by running: - -``` -docker compose up -d -``` - -Then visit `http://localhost:3000` and you should be greeted with the Sign In page. - -### [Optional] 6. Enable optional features - -Check the [configuration docs](/configuration) for extra features to enable such as full page archival, full page screenshots, inference languages, etc. - -### [Optional] 7. Setup quick sharing extensions - -Go to the [quick sharing page](/quick-sharing) to install the mobile apps and the browser extensions. Those will help you hoard things faster! - -## Updating - -Updating Karakeep will depend on what you used for the `KARAKEEP_VERSION` env variable. - -- If you pinned the app to a specific version, bump the version and re-run `docker compose up -d`. This should pull the new version for you. -- If you used `KARAKEEP_VERSION=release`, you'll need to force docker to pull the latest version by running `docker compose up --pull always -d`. - -Note that if you want to upgrade/migrate `Meilisearch` versions, refer to the [troubleshooting](/troubleshooting) page. diff --git a/docs/docs/02-installation/02-unraid.md b/docs/docs/02-installation/02-unraid.md deleted file mode 100644 index 5ca3e027..00000000 --- a/docs/docs/02-installation/02-unraid.md +++ /dev/null @@ -1,19 +0,0 @@ -# Unraid - -## Docker Compose Manager Plugin (Recommended) - -You can use [Docker Compose Manager](https://forums.unraid.net/topic/114415-plugin-docker-compose-manager/) plugin to deploy Karakeep using the official docker compose file provided [here](https://github.com/karakeep-app/karakeep/blob/main/docker/docker-compose.yml). After creating the stack, you'll need to setup some env variables similar to that from the docker compose installation docs [here](/Installation/docker#3-populate-the-environment-variables). - -## Community Apps - -:::info -The community application template is maintained by the community. -::: - -Karakeep can be installed on Unraid using the community application plugins. Karakeep is a multi-container service, and because unraid doesn't natively support that, you'll have to install the different pieces as separate applications and wire them manually together. - -Here's a high level overview of the services you'll need: - -- **Karakeep** ([Support post](https://forums.unraid.net/topic/165108-support-collectathon-karakeep/)): Karakeep's main web app. -- **Browserless** ([Support post](https://forums.unraid.net/topic/130163-support-template-masterwishxbrowserless/)): The chrome headless service used for fetching the content. Karakeep's official docker compose doesn't use browserless, but it's currently the only headless chrome service available on unraid, so you'll have to use it. -- **MeiliSearch** ([Support post](https://forums.unraid.net/topic/164847-support-collectathon-meilisearch/)): The search engine used by Karakeep. It's optional but highly recommended. If you don't have it set up, search will be disabled. diff --git a/docs/docs/02-installation/03-archlinux.md b/docs/docs/02-installation/03-archlinux.md deleted file mode 100644 index 63db9d75..00000000 --- a/docs/docs/02-installation/03-archlinux.md +++ /dev/null @@ -1,95 +0,0 @@ -# Arch Linux - -## Installation - -> [Karakeep on AUR](https://aur.archlinux.org/packages/karakeep) is not maintained by the karakeep official. - -1. Install karakeep - - ```shell - paru -S karakeep - ``` - -2. (**Optional**) Install optional dependencies - - ```shell - # karakeep-cli: karakeep cli tool - paru -S karakeep-cli - - # ollama: for automatic tagging - sudo pacman -S ollama - - # yt-dlp: for download video - sudo pacman -S yt-dlp - ``` - - You can use Open-AI instead of `ollama`. If you use `ollama`, you need to download the ollama model. Please refer to: [https://ollama.com/library](https://ollama.com/library). - -3. Set up - - Environment variables can be set in `/etc/karakeep/karakeep.env` according to [configuration page](/configuration). **The environment variables that are not specified in `/etc/karakeep/karakeep.env` need to be added by yourself.** - -4. Enable service - - ```shell - sudo systemctl enable --now karakeep.target - ``` - - Then visit `http://localhost:3000` and you should be greated with the sign in page. - -## Services and Ports - -`karakeep.target` include 3 services: `karakeep-web.service`, `karakeep-works.service`, `karakeep-browser.service`. - -- `karakeep-web.service`: Provide karakeep webui service, uses `3000` port by default. - -- `karakeep-workers.service`: Provide karakeep workers service, no port. - -- `karakeep-browser.service`: Provide browser headless service, uses `9222` port by default. - -Now `karakeep` depends on `meilisearch`, and `karakeep-workers.service` wants `meilisearch.service`, starting `karakeep.target` will start `meilisearch.service` at the same time. - -## How to Migrate from Hoarder to Karakeep - -The PKGBUILD has been fully updated to replace all references to `hoarder` with `karakeep`. If you want to preserve your existing `hoarder` data during the upgrade, please follow the steps below: - -**1. Stop the old services** - -```shell -sudo systemctl stop hoarder-web.service hoarder-worker.service hoarder-browser.service -sudo systemctl disable --now hoarder.target -``` - -**2. Uninstall Hoarder** -After uninstalling, you can manually remove the old `hoarder` user and group if needed. -```shell -paru -R hoarder -``` - -**3. Rename the old data directory** -```shell -sudo mv /var/lib/hoarder /var/lib/karakeep -``` - -**4. Install Karakeep** -```shell -paru -S karakeep -``` - -**5. Fix ownership of the data directory** -```shell -sudo chown -R karakeep:karakeep /var/lib/karakeep -``` - -**6. Set Karakeep** -Edit `/etc/karakeep/karakeep.env` according to [configuration page](/configuration). **The environment variables that are not specified in `/etc/karakeep/karakeep.env` need to be added by yourself.** - -Or you can copy old hoarder env file to karakeep: -```shell -sudo cp -f /etc/hoarder/hoarder.env /etc/karakeep/karakeep.env -``` - -**7. Start Karakeep** -```shell -sudo systemctl enable --now karakeep.target -``` diff --git a/docs/docs/02-installation/04-kubernetes.md b/docs/docs/02-installation/04-kubernetes.md deleted file mode 100644 index b8c40551..00000000 --- a/docs/docs/02-installation/04-kubernetes.md +++ /dev/null @@ -1,112 +0,0 @@ -# Kubernetes - -### Requirements - -- A kubernetes cluster -- kubectl -- kustomize - -### 1. Get the deployment manifests - -You can clone the repository and copy the `/kubernetes` directory into another directory of your choice. - -### 2. Populate the environment variables and secrets - -To configure the app, copy the `.env_sample` to `.env` and change to your specific needs. - -You should also change the `NEXTAUTH_URL` variable to point to your server address. - -Using `KARAKEEP_VERSION=release` will pull the latest stable version. You might want to pin the version instead to control the upgrades (e.g. `KARAKEEP_VERSION=0.10.0`). Check the latest versions [here](https://github.com/karakeep-app/karakeep/pkgs/container/karakeep). - -To see all available configuration options check the [documentation](https://docs.karakeep.app/configuration). - -To configure the neccessary secrets for the application copy the `.secrets_sample` file to `.secrets` and change the sample secrets to your generated secrets. - -> Note: You **should** change the random strings. You can use `openssl rand -base64 36` to generate the random strings. - -### 3. Setup OpenAI - -To enable automatic tagging, you'll need to configure OpenAI. This is optional though but highly recommended. - -- Follow [OpenAI's help](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key) to get an API key. -- Add the OpenAI API key to the `.env` file: - -``` -OPENAI_API_KEY=<key> -``` - -Learn more about the costs of using openai [here](/openai). - -<details> - <summary>[EXPERIMENTAL] If you want to use Ollama (https://ollama.com/) instead for local inference.</summary> - - **Note:** The quality of the tags you'll get will depend on the quality of the model you choose. Running local models is a recent addition and not as battle tested as using openai, so proceed with care (and potentially expect a bunch of inference failures). - - - Make sure ollama is running. - - Set the `OLLAMA_BASE_URL` env variable to the address of the ollama API. - - Set `INFERENCE_TEXT_MODEL` to the model you want to use for text inference in ollama (for example: `mistral`) - - Set `INFERENCE_IMAGE_MODEL` to the model you want to use for image inference in ollama (for example: `llava`) - - Make sure that you `ollama pull`-ed the models that you want to use. - - -</details> - -### 4. Deploy the service - -Deploy the service by running: - -``` -make deploy -``` - -### 5. Access the service - -#### via LoadBalancer IP - -By default, these manifests expose the application as a LoadBalancer Service. You can run `kubectl get services` to identify the IP of the loadbalancer for your service. - -Then visit `http://<loadbalancer-ip>:3000` and you should be greated with the Sign In page. - -> Note: Depending on your setup you might want to expose the service via an Ingress, or have a different means to access it. - -#### Via Ingress - -If you want to use an ingress, you can customize the sample ingress in the kubernetes folder and change the host to the DNS name of your choice. - -After that you have to configure the web service to the type ClusterIP so it is only reachable via the ingress. - -If you have already deployed the service you can patch the web service to the type ClusterIP with the following command: - -` kubectl -n karakeep patch service web -p '{"spec":{"type":"ClusterIP"}}' ` - -Afterwards you can apply the ingress and access the service via your chosen URL. - -#### Setting up HTTPS access to the Service - -To access karakeep securely you can configure the ingress to use a preconfigured TLS certificate. This requires that you already have the needed files, namely your .crt and .key file, on hand. - -After you have deployed the karakeep manifests you can deploy your certificate for karakeep in the `karakeep` namespace with this example command. You can name the secret however you want. But be aware that the secret name in the ingress definition has to match the secret name. - -` $ kubectl --namespace karakeep create secret tls karakeep-web-tls --cert=/path/to/crt --key=/path/to/key ` - -If the secret is successfully created you can now configure the Ingress to use TLS via this changes to the spec: - -```` yaml - spec: - tls: - - hosts: - - karakeep.example.com - secretName: karakeep-web-tls -```` - -> Note: Be aware that the hosts have to match between the tls spec and the HTTP spec. - -### [Optional] 6. Setup quick sharing extensions - -Go to the [quick sharing page](/quick-sharing) to install the mobile apps and the browser extensions. Those will help you hoard things faster! - -## Updating - -Edit the `KARAKEEP_VERSION` variable in the `kustomization.yaml` file and run `make clean deploy`. - -If you have chosen `release` as the image tag you can also destroy the web pod, since the deployment has an ImagePullPolicy set to always the pod always pulls the image from the registry, this way we can ensure that the newest release image is pulled. diff --git a/docs/docs/02-installation/05-pikapods.md b/docs/docs/02-installation/05-pikapods.md deleted file mode 100644 index dad0785a..00000000 --- a/docs/docs/02-installation/05-pikapods.md +++ /dev/null @@ -1,32 +0,0 @@ -# PikaPods [Paid Hosting] - -:::info -Note: PikaPods shares some of its revenue from hosting Karakeep with the maintainer of this project. -::: - -[PikaPods](https://www.pikapods.com/) offers managed paid hosting for many open source apps, including Karakeep. -Server administration, updates, migrations and backups are all taken care of, which makes it well suited -for less technical users. As of Nov 2024, running Karakeep there will cost you ~$3 per month. - -### Requirements - -- A _PikaPods_ account. Can be created for free [here](https://www.pikapods.com/register). You get an initial welcome credit of $5. - -### 1. Choose app - -Choose _Karakeep_ from their [list of apps](https://www.pikapods.com/apps) or use this [direct link](https://www.pikapods.com/pods?run=hoarder). This will either -open a new dialog to add a new _Karakeep_ pod or ask you to log in. - -### 2. Add settings - -There are a few settings to configure in the dialog: - -- **Basics**: Give the pod a name and choose a region that's near you. -- **Env Vars**: Here you can disable signups or set an OpenAI API key. All settings are optional. -- **Resources**: The resources your _Karakeep_ pod can use. The defaults are fine, unless you have a very large collection. - -### 3. Start pod and add user - -After hitting _Add pod_ it will take about a minute for the app to fully start. After this you can visit -the pod's URL and add an initial user under _Sign Up_. After this you may want to disable further sign-ups -by setting the pod's `DISABLE_SIGNUPS` _Env Var_ to `true`. diff --git a/docs/docs/02-installation/06-debuntu.md b/docs/docs/02-installation/06-debuntu.md deleted file mode 100644 index 2f3d1113..00000000 --- a/docs/docs/02-installation/06-debuntu.md +++ /dev/null @@ -1,74 +0,0 @@ -# Debian 12/Ubuntu 24.04 - -:::warning -This script is a stripped-down version of those found in the [Proxmox Community Scripts](https://github.com/community-scripts/ProxmoxVE) repo. It has been adapted to work on baremetal Debian 12 or Ubuntu 24.04 installs **only**. Any other use is not supported and you use this script at your own risk. -::: - -### Requirements - -- **Debian 12** (Buster) or -- **Ubuntu 24.04** (Noble Numbat) - -The script will download and install all dependencies (except for Ollama), install Karakeep, do a basic configuration of Karakeep and Meilisearch (the search app used by Karakeep), and create and enable the systemd service files needed to run Karakeep on startup. Karakeep and Meilisearch are run in the context of their low-privilege user environments for more security. - -The script functions as an update script in addition to an installer. See **[Updating](#updating)**. - -### 1. Download the script from the [Karakeep repository](https://github.com/karakeep-app/karakeep/blob/main/karakeep-linux.sh) - -``` -wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/karakeep-linux.sh -``` - -### 2. Run the script - -> This script must be run as `root`, or as a user with `sudo` privileges. - - If this is a fresh install, then run the installer by using the following command: - - ```shell - bash karakeep-linux.sh install - ``` - -### 3. Create an account/sign in - - Then visit `http://localhost:3000` and you should be greated with the Sign In page. - -## Updating - -> This script must be run as `root`, or as a user with `sudo` privileges. - - If Karakeep has previously been installed using this script, then run the updater like so: - - ```shell - bash karakeep-linux.sh update - ``` - -## Services and Ports - -`karakeep.target` includes 4 services: `meilisearch.service`, `karakeep-web.service`, `karakeep-workers.service`, `karakeep-browser.service`. - -- `meilisearch.service`: Provides full-text search, Karakeep Workers service connects to it, uses port `7700` by default. - -- `karakeep-web.service`: Provides the karakeep web service, uses `3000` port by default. - -- `karakeep-workers.service`: Provides the karakeep workers service, no port. - -- `karakeep-browser.service`: Provides the headless browser service, uses `9222` port by default. - -## Configuration, ENV file, database locations - -During installation, the script created a configuration file for `meilisearch`, an `ENV` file for Karakeep, and located config paths and database paths separate from the installation path of Karakeep, so as to allow for easier updating. Their names/locations are as follows: - -- `/etc/meilisearch.toml` - a basic configuration for meilisearch, that contains configs for the database location, disabling analytics, and using a master key, which prevents unauthorized connections. -- `/var/lib/meilisearch` - Meilisearch DB location. -- `/etc/karakeep/karakeep.env` - The Karakeep `ENV` file. Edit this file to configure Karakeep beyond the default. The web service and the workers service need to be restarted after editing this file: - - ```shell - sudo systemctl restart karakeep-workers karakeep-web - ``` - -- `/var/lib/karakeep` - The Karakeep database location. If you delete the contents of this folder you will lose all your data. - -## Still Running Hoarder? - -There is a way to upgrade. Please see [Guides > Hoarder to Karakeep Migration](https://docs.karakeep.app/Guides/hoarder-to-karakeep-migration) diff --git a/docs/docs/02-installation/07-minimal-install.md b/docs/docs/02-installation/07-minimal-install.md deleted file mode 100644 index 211bfb08..00000000 --- a/docs/docs/02-installation/07-minimal-install.md +++ /dev/null @@ -1,49 +0,0 @@ -# Minimal Installation - -:::warning -Unless necessary, prefer the [full installation](/Installation/docker) to leverage all the features of Karakeep. You'll be sacrificing a lot of functionality if you go with the minimal installation route. -::: - -Karakeep's default installation has a dependency on Meilisearch for the full text search, Chrome for crawling and OpenAI/Ollama for AI tagging. You can however run Karakeep without those dependencies if you're willing to sacrifice those features. - -- If you run without meilisearch, the search functionality will be completely disabled. -- If you run without chrome, crawling will still work, but you'll lose ability to take screenshots of websites and websites with javascript content won't get crawled correctly. -- If you don't setup OpenAI/Ollama, AI tagging will be disabled. - -Those features are important for leveraging Karakeep's full potential, but if you're running in constrained environments, you can use the following minimal docker compose to skip all those dependencies: - -```yaml -services: - web: - image: ghcr.io/karakeep-app/karakeep:release - restart: unless-stopped - volumes: - - data:/data - ports: - - 3000:3000 - environment: - DATA_DIR: /data - NEXTAUTH_SECRET: super_random_string -volumes: - data: -``` - -Or just with the following docker command: - -```base -docker run -d \ - --restart unless-stopped \ - -v data:/data \ - -p 3000:3000 \ - -e DATA_DIR=/data \ - -e NEXTAUTH_SECRET=super_random_string \ - ghcr.io/karakeep-app/karakeep:release -``` - -:::warning -You **MUST** change the `super_random_string` to a true random string which you can generate with `openssl rand -hex 32`. -::: - -Check the [configuration docs](/configuration) for extra features to enable such as full page archival, full page screenshots, inference languages, etc. - - diff --git a/docs/docs/02-installation/08-truenas.md b/docs/docs/02-installation/08-truenas.md deleted file mode 100644 index 9b7989c2..00000000 --- a/docs/docs/02-installation/08-truenas.md +++ /dev/null @@ -1,3 +0,0 @@ -# TrueNAS - -Karakeep is available directly from TrueNAS's app catalog ([link](https://apps.truenas.com/catalog/karakeep/)). diff --git a/docs/docs/07-development/01-setup.md b/docs/docs/07-development/01-setup.md deleted file mode 100644 index 6072a377..00000000 --- a/docs/docs/07-development/01-setup.md +++ /dev/null @@ -1,178 +0,0 @@ -# Setup - -## Quick Start - -For the fastest way to get started with development, use the one-command setup script: - -```bash -./start-dev.sh -``` - -This script will automatically: -- Start Meilisearch in Docker (on port 7700) -- Start headless Chrome in Docker (on port 9222) -- Install dependencies with `pnpm install` if needed -- Start both the web app and workers in parallel -- Provide cleanup when you stop with Ctrl+C - -**Prerequisites:** -- Docker installed and running -- pnpm installed (see manual setup below for installation instructions) - -The script will output the running services: -- Web app: http://localhost:3000 -- Meilisearch: http://localhost:7700 -- Chrome debugger: http://localhost:9222 - -Press Ctrl+C to stop all services and clean up Docker containers. - -## Manual Setup - -Karakeep uses `node` version 22. To install it, you can use `nvm` [^1] - -``` -$ nvm install 22 -``` - -Verify node version using this command: -``` -$ node --version -v22.14.0 -``` - -Karakeep also makes use of `corepack`[^2]. If you have `node` installed, then `corepack` should already be -installed on your machine, and you don't need to do anything. To verify the `corepack` is installed run: - -``` -$ command -v corepack -/home/<user>/.nvm/versions/node/v22.14.0/bin/corepack -``` - -To enable `corepack` run the following command: - -``` -$ corepack enable -``` - -Then, from the root of the repository, install the packages and dependencies using: - -``` -$ pnpm install -``` - -Output of a successful `pnpm install` run should look something like: - -``` -Scope: all 20 workspace projects -Lockfile is up to date, resolution step is skipped -Packages: +3129 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Progress: resolved 0, reused 2699, downloaded 0, added 3129, done - -devDependencies: -+ @karakeep/prettier-config 0.1.0 <- tooling/prettier - -. prepare$ husky -└─ Done in 45ms -Done in 5.5s -``` - -You can now continue with the rest of this documentation. - -### First Setup - -- You'll need to prepare the environment variables for the dev env. -- Easiest would be to set it up once in the root of the repo and then symlink it in each app directory (e.g. `/apps/web`, `/apps/workers`) and also `/packages/db`. -- Start by copying the template by `cp .env.sample .env`. -- The most important env variables to set are: - - `DATA_DIR`: Where the database and assets will be stored. This is the only required env variable. You can use an absolute path so that all apps point to the same dir. - - `NEXTAUTH_SECRET`: Random string used to sign the JWT tokens. Generate one with `openssl rand -base64 36`. Logging in will not work if this is missing! - - `MEILI_ADDR`: If not set, search will be disabled. You can set it to `http://127.0.0.1:7700` if you run meilisearch using the command below. - - `OPENAI_API_KEY`: If you want to enable auto tag inference in the dev env. -- run `pnpm run db:migrate` in the root of the repo to set up the database. - -### Dependencies - -#### Meilisearch - -Meilisearch is the provider for the full text search (and at some point embeddings search too). You can get it running with `docker run -p 7700:7700 getmeili/meilisearch:v1.13.3`. - -Mount persistent volume if you want to keep index data across restarts. You can trigger a re-index for the entire items collection in the admin panel in the web app. - -#### Chrome - -The worker app will automatically start headless chrome on startup for crawling pages. You don't need to do anything there. - -### Web App - -- Run `pnpm web` in the root of the repo. -- Go to `http://localhost:3000`. - -> NOTE: The web app kinda works without any dependencies. However, search won't work unless meilisearch is running. Also, new items added won't get crawled/indexed unless workers are running. - -### Workers - -- Run `pnpm workers` in the root of the repo. - -### Mobile App (iOS & Android) - -#### Prerequisites - -To build and run the mobile app locally, you'll need: - -- **For iOS development**: - - macOS computer - - Xcode installed from the App Store - - iOS Simulator (comes with Xcode) - -- **For Android development**: - - Android Studio installed - - Android SDK configured - - Android Emulator or physical device - -For detailed setup instructions, refer to the [Expo documentation](https://docs.expo.dev/guides/local-app-development/). - -#### Running the app - -- `cd apps/mobile` -- `pnpm exec expo prebuild --no-install` to build the app. - -**For iOS:** -- `pnpm exec expo run:ios` -- The app will be installed and started in the simulator. - -**Troubleshooting iOS Setup:** -If you encounter an error like `xcrun: error: SDK "iphoneos" cannot be located`, you may need to set the correct Xcode developer directory: -```bash -sudo xcode-select -s /Applications/Xcode.app/Contents/Developer -``` - -**For Android:** -- Start the Android emulator or connect a physical device. -- `pnpm exec expo run:android` -- The app will be installed and started on the emulator/device. - -Changing the code will hot reload the app. However, installing new packages requires restarting the expo server. - -### Browser Extension - -- `cd apps/browser-extension` -- `pnpm dev` -- This will generate a `dist` package -- Go to extension settings in chrome and enable developer mode. -- Press `Load unpacked` and point it to the `dist` directory. -- The plugin will pop up in the plugin list. - -In dev mode, opening and closing the plugin menu should reload the code. - - -## Docker Dev Env - -If the manual setup is too much hassle for you. You can use a docker based dev environment by running `docker compose -f docker/docker-compose.dev.yml up` in the root of the repo. This setup wasn't super reliable for me though. - - -[^1]: [nvm](https://github.com/nvm-sh/nvm) is a node version manager. You can install it following [these -instructions](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating). - -[^2]: [corepack](https://nodejs.org/api/corepack.html) is an experimental tool to help with managing versions of your -package managers. diff --git a/docs/docs/07-development/02-directories.md b/docs/docs/07-development/02-directories.md deleted file mode 100644 index 712e86a1..00000000 --- a/docs/docs/07-development/02-directories.md +++ /dev/null @@ -1,28 +0,0 @@ -# Directory Structure - -## Apps - -| Directory | Description | -| ------------------------ | ------------------------------------------------------ | -| `apps/web` | The main web app | -| `apps/workers` | The background workers logic | -| `apps/mobile` | The react native based mobile app | -| `apps/browser-extension` | The browser extension | -| `apps/landing` | The landing page of [karakeep.app](https://karakeep.app) | - -## Shared Packages - -| Directory | Description | -| ----------------- | ---------------------------------------------------------------------------- | -| `packages/db` | The database schema and migrations | -| `packages/trpc` | Where most of the business logic lies built as TRPC routes | -| `packages/shared` | Some shared code between the different apps (e.g. loggers, configs, assetdb) | - -## Toolings - -| Directory | Description | -| -------------------- | ----------------------- | -| `tooling/typescript` | The shared tsconfigs | -| `tooling/eslint` | ESlint configs | -| `tooling/prettier` | Prettier configs | -| `tooling/tailwind` | Shared tailwind configs | diff --git a/docs/docs/07-development/03-database.md b/docs/docs/07-development/03-database.md deleted file mode 100644 index d7a15b62..00000000 --- a/docs/docs/07-development/03-database.md +++ /dev/null @@ -1,10 +0,0 @@ -# Database Migrations - -- The database schema lives in `packages/db/schema.ts`. -- Changing the schema, requires a migration. -- You can generate the migration by running `pnpm run db:generate --name description_of_schema_change` in the root dir. -- You can then apply the migration by running `pnpm run db:migrate`. - -## Drizzle Studio - -You can start the drizzle studio by running `pnpm run db:studio` in the root of the repo. diff --git a/docs/docs/07-development/04-architecture.md b/docs/docs/07-development/04-architecture.md deleted file mode 100644 index 5a864034..00000000 --- a/docs/docs/07-development/04-architecture.md +++ /dev/null @@ -1,9 +0,0 @@ -# Architecture - - - -- Webapp: NextJS based using sqlite for data storage. -- Workers: Consume the jobs from sqlite based job queue and executes them, there are three job types: - 1. Crawling: Fetches the content of links using a headless chrome browser running in the workers container. - 2. OpenAI: Uses OpenAI APIs to infer the tags of the content. - 3. Indexing: Indexes the content in meilisearch for faster retrieval during search. diff --git a/docs/docs/07-Development/01-setup.md b/docs/docs/07-hamtaro-development/01-setup.md index 6072a377..6072a377 100644 --- a/docs/docs/07-Development/01-setup.md +++ b/docs/docs/07-hamtaro-development/01-setup.md diff --git a/docs/docs/07-Development/02-directories.md b/docs/docs/07-hamtaro-development/02-directories.md index 712e86a1..712e86a1 100644 --- a/docs/docs/07-Development/02-directories.md +++ b/docs/docs/07-hamtaro-development/02-directories.md diff --git a/docs/docs/07-Development/03-database.md b/docs/docs/07-hamtaro-development/03-database.md index d7a15b62..d7a15b62 100644 --- a/docs/docs/07-Development/03-database.md +++ b/docs/docs/07-hamtaro-development/03-database.md diff --git a/docs/docs/07-Development/04-architecture.md b/docs/docs/07-hamtaro-development/04-architecture.md index 5a864034..5a864034 100644 --- a/docs/docs/07-Development/04-architecture.md +++ b/docs/docs/07-hamtaro-development/04-architecture.md diff --git a/docs/docs/07-development/_category_.json b/docs/docs/07-hamtaro-development/_category_.json index 117f7f1b..117f7f1b 100644 --- a/docs/docs/07-development/_category_.json +++ b/docs/docs/07-hamtaro-development/_category_.json diff --git a/docs/docs/14-guides/01-legacy-container-upgrade.md b/docs/docs/14-guides/01-legacy-container-upgrade.md deleted file mode 100644 index d95c1c1e..00000000 --- a/docs/docs/14-guides/01-legacy-container-upgrade.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/docs/14-guides/02-search-query-language.md b/docs/docs/14-guides/02-search-query-language.md deleted file mode 100644 index be9739b4..00000000 --- a/docs/docs/14-guides/02-search-query-language.md +++ /dev/null @@ -1,71 +0,0 @@ -# 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/docs/14-guides/03-singlefile.md b/docs/docs/14-guides/03-singlefile.md deleted file mode 100644 index c0f4e174..00000000 --- a/docs/docs/14-guides/03-singlefile.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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/docs/14-guides/04-hoarder-to-karakeep-migration.md b/docs/docs/14-guides/04-hoarder-to-karakeep-migration.md deleted file mode 100644 index 289a091c..00000000 --- a/docs/docs/14-guides/04-hoarder-to-karakeep-migration.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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/docs/14-guides/05-different-ai-providers.md b/docs/docs/14-guides/05-different-ai-providers.md deleted file mode 100644 index 33408c00..00000000 --- a/docs/docs/14-guides/05-different-ai-providers.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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 -``` diff --git a/docs/docs/14-Guides/01-legacy-container-upgrade.md b/docs/docs/14-hamtaro-guides/01-legacy-container-upgrade.md index d95c1c1e..d95c1c1e 100644 --- a/docs/docs/14-Guides/01-legacy-container-upgrade.md +++ b/docs/docs/14-hamtaro-guides/01-legacy-container-upgrade.md diff --git a/docs/docs/14-Guides/02-search-query-language.md b/docs/docs/14-hamtaro-guides/02-search-query-language.md index be9739b4..be9739b4 100644 --- a/docs/docs/14-Guides/02-search-query-language.md +++ b/docs/docs/14-hamtaro-guides/02-search-query-language.md diff --git a/docs/docs/14-Guides/03-singlefile.md b/docs/docs/14-hamtaro-guides/03-singlefile.md index c0f4e174..c0f4e174 100644 --- a/docs/docs/14-Guides/03-singlefile.md +++ b/docs/docs/14-hamtaro-guides/03-singlefile.md diff --git a/docs/docs/14-Guides/04-hoarder-to-karakeep-migration.md b/docs/docs/14-hamtaro-guides/04-hoarder-to-karakeep-migration.md index 289a091c..289a091c 100644 --- a/docs/docs/14-Guides/04-hoarder-to-karakeep-migration.md +++ b/docs/docs/14-hamtaro-guides/04-hoarder-to-karakeep-migration.md diff --git a/docs/docs/14-Guides/05-different-ai-providers.md b/docs/docs/14-hamtaro-guides/05-different-ai-providers.md index 33408c00..33408c00 100644 --- a/docs/docs/14-Guides/05-different-ai-providers.md +++ b/docs/docs/14-hamtaro-guides/05-different-ai-providers.md diff --git a/docs/docs/14-guides/_category_.json b/docs/docs/14-hamtaro-guides/_category_.json index 117f7f1b..117f7f1b 100644 --- a/docs/docs/14-guides/_category_.json +++ b/docs/docs/14-hamtaro-guides/_category_.json |