Przejdź do treści
Biblioteka skilli
Programowanie · Automatyzacja

dev-env

/dev-env

Uruchamia środowisko deweloperskie Karakeep w worktree Git i loguje testowego użytkownika, gdy serwer nie chce wystartować.

Repozytorium
karakeep ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
11.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

Co robi i kiedy

Uruchamia środowisko deweloperskie Karakeep w worktree Git i loguje testowego użytkownika, gdy serwer nie chce wystartować.

Oryginalny opis (EN)

Run the Karakeep dev environment (web + workers) inside a git worktree and log in as a seeded user. Use when asked to start/run the app, verify a change in the browser, take a screenshot of the web UI, or when the dev server fails to boot (port conflicts, login redirects to another worktree, stale migrations, EMFILE watcher loops, tsx EPERM).

Jak działa

  1. 1. Start it
  2. 2. Stop it
  3. 3. Log in
  4. 4. Not running in dev
  5. 5. Troubleshooting and running pieces by hand
Sekcje z nagłówków SKILL.md, w oryginale · 74 linii, 819 słów
Podgląd SKILL.md
---
name: dev-env
description: Run the Karakeep dev environment (web + workers) inside a git worktree and log in as a seeded user. Use when asked to start/run the app, verify a change in the browser, take a screenshot of the web UI, or when the dev server fails to boot (port conflicts, login redirects to another worktree, stale migrations, EMFILE watcher loops, tsx EPERM).
---

# Running the Karakeep dev env in a worktree

Many worktrees run on this machine at the same time, often each with its own dev server. `pnpm dev:worktree` (`scripts/dev-worktree.sh`) handles the resulting conflicts. Use it rather than `pnpm web` / `pnpm workers`.

## 1. Start it

Run from the worktree root, in the background (it doesn't return until stopped):

```sh
# run_in_background: true
pnpm dev:worktree >| $TMPDIR/karakeep-$(basename $PWD)-dev.out 2>&1
```

Then wait for it to report readiness:

```sh
for i in $(seq 1 150); do grep -qE "is ready|exited|didn't become" $TMPDIR/karakeep-$(basename $PWD)-dev.out && break; sleep 2; done; tail -20 $TMPDIR/karakeep-$(basename $PWD)-dev.out
```

The script:

1. Sets up only the pieces that are missing: runs `pnpm install`, writes `.env` (random `NEXTAUTH_SECRET`, absolute `DATA_DIR`), symlinks `.env` into `apps/web`, `apps/workers` and `packages/db`, and applies the seed snapshot into `data/`.
2. Migrates the main DB and the queue DB. The seed snapshot is older than HEAD, so this always runs.
3. Picks the first free port in 3100–3199 and sets `NEXTAUTH_URL` to match.
4. Starts the workers, then `next dev` with `WATCHPACK_POLLING=true`, and waits until `/signin` returns 200.
5. Prints the URL, the seed users, and the log paths (`$TMPDIR/karakeep-dev-<worktree>/{web,workers}.log`).

Overrides: `PORT=3105`, `DEV_HOST=<host>` (see step 3), and `WATCHPACK_POLLING=false`. `pnpm dev:worktree setup` does steps 1–2 without starting anything.

Web changes hot-reload. Worker changes don't: restart the script.

## 2. Stop it

Stop the background task (TaskStop). The script stops both services on exit. Don't touch processes from other worktrees; to check which worktree owns a process, run `lsof -a -p <pid> -d cwd`.

## 3. Log in

Seed users (all share the password `test1234`):

| Email | Role | Data |
| --- | --- | --- |
| `test1@example.com` | admin | 24 bookmarks (links, notes, an image, a PDF), highlights, rules, prompts, a feed, a webhook; shares "Reading Queue" |
| `test2@example.com` | user | 7 bookmarks (incl. an import session), editor on test1's "Reading Queue" |
| `test3@example.com` | user | empty, with a pending invite to "Reading Queue" |

Login flow with any browser automation tool:

1. Navigate to `http://localhost:$PORT/signin`.
2. Type the email into `input[type='email']` and the password into `input[type='password']`, then press Enter.
3. Wait for the URL to contain `/dashboard` and the page to show `Seed snapshot bookmark`.

Browser gotchas:

- **The browser must use the host in `NEXTAUTH_URL`.** If your browser tool reaches the app through something other than `localhost`, such as a LAN IP like `http://10.0.10.13:3100`, restart with `DEV_HOST=<that host>`. Otherwise sign-in goes to the wrong place, and Next blocks HMR and fonts for that origin. The same applies to `127.0.0.1`.
- **Cookies are per host, not per port.** Worktrees share cookies. With the per-worktree random secret, another worktree's session cookie is rejected: you land on `/signin`, and the web log shows `JWT_SESSION_ERROR` until you log in. That's expected. If `.env` has a shared secret such as `test1234`, another worktree's session is valid on yours, so open `/logout` first.
- The dashboard's accessibility tree is large. If your screenshot tool returns it with the image, save the snapshot to a file and read only the PNG.

## 4. Not running in dev

- **Meilisearch**: without `MEILI_ADDR`, search is disabled. Start it with `docker run -p 7700:7700 getmeili/meilisearch:v1.55.0` and set `MEILI_ADDR=http://127.0.0.1:7700` only if you need search. Port 7700 may already belong to another worktree's container.
- **Crawling**: the workers run in "browserless mode" with no `BROWSER_WEB_URL`. The seed data is already crawled, so this only matters for newly added links.
- **Inference**: no `OPENAI_API_KEY`, so no auto-tagging.

## 5. Troubleshooting and running pieces by hand

- **`listen EPERM ... tsx-*/*.pipe`**: the bare `tsx` CLI opens an IPC socket that the Claude Code sandbox blocks. Run the file through node's loader instead, e.g. `(cd packages/db && node --import tsx migrate.ts)`. The repo's package scripts (`pnpm db:migrate`, `pnpm seed:apply`, …) already do this.
- **`EMFILE: too many open files, watch`**: native file watching is blocked in the sandbox. For `next dev` this shows up as `.next/dev` "was deleted" and endless restarts; keep `WATCHPACK_POLLING=true`. `pnpm workers` (`node --watch`) fails the same way; use `pnpm dev:worktree`, which runs the workers without watching.
- **A stray `packages/db/db.db`**: migrations ran with an empty `DATA_DIR`. Scripts must `import "dotenv/config"` before `@karakeep/shared/config`, which parses `process.env` at import time. Delete the stray file and re-run.
- **Jobs never run / queue errors**: `queue.db` needs `pnpm db:migrate:queue` (or `(cd apps/workers && node --import tsx scripts/migrateQueue.ts)`). The workers also migrate it on startup; the web app never does.
- **Reset the data**: stop the script, then run `(cd tools/seed-snapshot && node --import tsx src/apply.ts --force)`.
- **Never copy `.env` or `data/` from the main checkout**: the seed gives every worktree the same known state.
- **`$TMPDIR` is shared by all agent sessions**: generic names like `web.log` collide with other worktrees, and zsh `noclobber` refuses to overwrite them. Put the worktree name in log file names and use `>|`.

Wersje

W bazie nie ma innych skilli o nazwie dev-env.

Migawka bazy z 13.11.2026 · wersja paczki cba0f7efdb3f (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100setting-up-dev-env
    Przygotowuje checkout lub worktree do pracy i zarządza serwerem deweloperskim: uruchamia go, czeka na gotowość i nie zabija cudzych serwerów.
  • 100worktree
    Uruchamia, sprawdza i czyści worktree git dla sesji, pilnując zasady jedna sesja, jeden worktree i jedna gałąź.
  • 100bifrost-debug
    Uruchamia izolowane środowisko deweloperskie Bifrost dla bieżącego worktree, by przeglądać interfejs w przeglądarce.
  • 93dev-server
    Zarządza serwerami deweloperskimi Next.js i git worktree: tworzy (wt new), znajduje zakończone (wt stale) i usuwa (wt rm), uruchamia serwery i czyta ich logi.
  • 95worktree
    Tworzy nowy git worktree z plikami .env, instaluje zależności i generuje klienta Prisma do pracy równoległej.
  • 100worktree
    Zarządza worktree gita z własnymi portami dev, dowiązanymi plikami env i piaskownicą, przy tworzeniu i usuwaniu.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.