Karakeep on StartOS

Upstream repo: https://github.com/karakeep-app/karakeep

Karakeep is a self-hosted bookmark manager with AI-powered automatic tagging. Save links, notes, and screenshots and find them later with full-text search or AI tags.

---

Table of Contents

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Network Access and Interfaces
• Actions (StartOS UI)
• Backups and Restore
• Health Checks
• Dependencies
• Limitations and Differences
• What Is Unchanged from Upstream
• Contributing
• Quick Reference for AI Consumers

---

Image and Container Runtime

Property	Value
Image	ghcr.io/karakeep-app/karakeep:0.32.0
Architectures	x86_64, aarch64
Entrypoint	/init (s6-overlay, manages web + workers + db migration internally)

---

Volume and Data Layout

Volume	Mount Point	Purpose
main	/data	Database, assets, and package state (store.json)

---

Installation and First-Run Flow

1. On fresh install, setupOnInit generates a random NEXTAUTH_SECRET and writes it to store.json on the main volume.
2. The service starts; s6-overlay runs the DB migration oneshot, then starts the web server and background workers.
3. The user visits the web UI and creates their account on first access (registration is open by default).

---

Configuration Management

No user-configurable settings file. All configuration is via environment variables injected at startup:

Variable	Value	Notes
DATA_DIR	/data	Hardcoded to the volume mountpoint
NEXTAUTH_SECRET	Random 32-char string	Generated at install, stored in store.json
NEXTAUTH_URL_INTERNAL	http://localhost:3000	Baked into the upstream image
DISABLE_NEW_RELEASE_CHECK	true	StartOS manages updates

---

Network Access and Interfaces

Interface	Port	Protocol	Purpose
Web UI	3000	HTTP	Karakeep web interface

Access methods:

• LAN IP with unique port
• <hostname>.local with unique port
• Tor .onion address
• Custom domains (if configured)

---

Actions (StartOS UI)

None.

---

Backups and Restore

Included in backup:

• main volume (database, assets, and store.json)

Restore behavior: Volume is fully restored before the service starts.

---

Health Checks

Check	Method	Messages
Web Interface	Port listening (3000)	Success: "The web interface is ready" / Error: "The web interface is not ready"

---

Dependencies

None.

---

Limitations and Differences

1. AI features require an external LLM — Ollama or OpenAI key can be configured by editing a config file inside the container; there is no StartOS UI for this yet.
2. No browser sidecar — automatic link screenshots (BROWSER_WEB_URL) are not configured; link previews use metadata only.
3. No Meilisearch — full-text search uses the built-in SQLite FTS; Meilisearch integration is not configured.

---

What Is Unchanged from Upstream

The service runs the official upstream Docker image without modification. No patches are applied.

---

Contributing

See CONTRIBUTING.md for build instructions and development workflow.

---

Quick Reference for AI Consumers

package_id: karakeep
image: ghcr.io/karakeep-app/karakeep:0.32.0
architectures: [x86_64, aarch64]
volumes:
  main: /data
ports:
  ui: 3000
dependencies: none
startos_managed_env_vars:
  DATA_DIR: /data
  NEXTAUTH_SECRET: generated at install, stored in main/store.json
  DISABLE_NEW_RELEASE_CHECK: "true"
actions: none