Skip to main content
Version: v0.26.0

Setup

Quick Start​

For the fastest way to get started with development, use the one-command setup script:

./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:

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 corepack2. 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.

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:

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.

Footnotes​

  1. nvm is a node version manager. You can install it following these instructions. ↩

  2. corepack is an experimental tool to help with managing versions of your package managers. ↩