starred/karakeep

Fork 0

mirror of https://github.com/karakeep-app/karakeep.git synced 2026-04-25 07:56:05 +03:00

[PR #2149] feat: freshen up docker-compose.yml for local dev purposes #2001

New issue

Open

opened 2026-03-02 12:00:08 +03:00 by kerem · 0 comments

kerem commented

2026-03-02 12:00:08 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/karakeep-app/karakeep/pull/2149
Author: @xuatz
Created: 11/17/2025
Status: 🔄 Open

Base: main ← Head: feat/docker-compose-dev

📝 Commits (2)

8729a55 docker-compose.yml for dev
e67c75b move the dev compose back to docker/

📊 Changes

4 files changed (+114 additions, -43 deletions)

View changed files

📝 docker/Dockerfile (+2 -2)
📝 docker/Dockerfile.dev (+1 -1)
📝 docker/docker-compose.dev.yml (+58 -20)
📝 docs/docs/08-development/01-setup.md (+53 -20)

📄 Description

Summary

duplicate/related to:

#584
#580

opinionatedly renamed and moved docker-compose.dev.yml to root as docker-compose.yml
applied the principles from start-dev.sh on docker-compose.yml
defined naive defaults, so that anybody can do docker compose up without even setting up a .env file to have a simple dev instance running
- still supports out of the box root .env overwrites due to the side-effect of having the .env in the the same dir as docker-compose.yml
handles prep container execution and DATA_DIR init
ensured that data is persisted across subsequent docker compose up
ensured that fast reload works for dev server

Details

First and foremost, why all the refactoring when there is already a docker-compose.dev.yml?

The "improvement" is proposed for 2 reasons:

i naively try to use docker compose -f docker/docker-compose.dev.yml up but there was an error on the latest main

! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-9.15.9.tgz
Scope: all 24 workspace projects

   ╭───────────────────────────────────────────────────────────────────╮
   │                                                                   │
   │                Update available! 9.15.9 → 10.22.0.                │
   │   Changelog: https://github.com/pnpm/pnpm/releases/tag/v10.22.0   │
   │            Run "corepack use pnpm@10.22.0" to update.             │
   │                                                                   │
   ╰───────────────────────────────────────────────────────────────────╯


> karakeep@0.1.0 db:migrate /app
> pnpm --filter @karakeep/db run migrate


> @karakeep/db@0.1.0 migrate /app/packages/db
> tsx migrate.ts


node:internal/modules/run_main:123
    triggerUncaughtException(
    ^
Error [TransformError]: 
You installed esbuild for another platform than the one you're currently using.
This won't work because esbuild is written with native code and needs to
install a platform-specific binary executable.

Specifically the "@esbuild/darwin-arm64" package is present but this platform
needs the "@esbuild/linux-arm64" package instead. People often get into this
situation by installing esbuild on Windows or macOS and copying "node_modules"
into a Docker image that runs Linux, or by copying "node_modules" between
Windows and WSL environments.

If you are installing with npm, you can try not copying the "node_modules"
directory when you copy the files over, and running "npm ci" or "npm install"
on the destination platform after the copy. Or you could consider using yarn
instead of npm which has built-in support for installing a package on multiple
platforms simultaneously.

If you are installing with yarn, you can try listing both this platform and the
other platform in your ".yarnrc.yml" file using the "supportedArchitectures"
feature: https://yarnpkg.com/configuration/yarnrc/#supportedArchitectures
Keep in mind that this means multiple copies of esbuild will be present.

Another alternative is to use the "esbuild-wasm" package instead, which works
the same way on all platforms. But it comes with a heavy performance cost and
can sometimes be 10x slower than the "esbuild" package, so you may also not
want to do that.

    at generateBinPath (/app/node_modules/esbuild/lib/main.js:1737:17)
    at esbuildCommandAndArgs (/app/node_modules/esbuild/lib/main.js:1818:33)
    at ensureServiceIsRunning (/app/node_modules/esbuild/lib/main.js:1975:25)
    at transform (/app/node_modules/esbuild/lib/main.js:1876:37)
    at file:///app/node_modules/tsx/dist/index-7AaEi15b.mjs:14:2865
    at applyTransformers (file:///app/node_modules/tsx/dist/index-7AaEi15b.mjs:14:1266)
    at transform (file:///app/node_modules/tsx/dist/index-7AaEi15b.mjs:14:2812)
    at load (file:///app/node_modules/tsx/dist/esm/index.mjs?1763396486478:2:2415)
    at async nextLoad (node:internal/modules/esm/hooks:748:22)
    at async Hooks.load (node:internal/modules/esm/hooks:385:20)

Node.js v22.21.1
/app/packages/db:
 ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL  @karakeep/db@0.1.0 migrate: `tsx migrate.ts`
Exit status 1
 ELIFECYCLE  Command failed with exit code 1.

because @MohamedBassem himself said that "This setup wasn't super reliable for me though."

and a bonus 3rd point, I wanted to deploy a staging version of karakeep to run my own nightly, but built from my own source code (unmerged changes), so I needed a docker-compose.yml that I was comfortable and familiar with, and hence this PR.

So with that out of the way, I will explain a little why I moved and renamed the docker-compose.yml.

The purpose of docker compose up in a repo, in my opinion, is to have a fast way to get dev started.

As a result, it should not use a custom name docker-compose.dev.yml, or be in a non-root path, because that would go against the idea of "getting started fast".

Having the docker-compose.yml in the root also allow us to share .env that would be used if the developer chooses to run the application on nodejs directly.

But of course, having a docker folder still serves it's purpose, for organisational purposes, to put the Dockerfile variants and or docker-compose variants such as more importantly a docker-compose.prod.yml example for people who want to run prod instances with a docker-compose file, which is common for selfhosters. But for the purposes for making the life easier for contributors and maintainers, I think it makes sense to have a root docker-compose.yml for that sake.

Notes

Btw, the docs update is entirely AI tweaked, and it's not my intention to keep it that way.
If/When this PR is approved, I plan to revisit the docs and give it a human touch lol.

docs/docs/07-development/01-setup.md
docs/docs/02-installation/01-docker.md

Duplicate PR?

btw, I am aware of https://github.com/karakeep-app/karakeep/pull/584, but it's opened a year ago and activity seems to have died down due to various reasons.

I took a stab at it and I believe I should have address the PR change requests and concerns

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/karakeep-app/karakeep/pull/2149 **Author:** [@xuatz](https://github.com/xuatz) **Created:** 11/17/2025 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/docker-compose-dev` --- ### 📝 Commits (2) - [`8729a55`](https://github.com/karakeep-app/karakeep/commit/8729a556fec9ee30f379039b71043802841b19cc) docker-compose.yml for dev - [`e67c75b`](https://github.com/karakeep-app/karakeep/commit/e67c75b800c62dbf2fe43929ca240066c8062664) move the dev compose back to docker/ ### 📊 Changes **4 files changed** (+114 additions, -43 deletions) <details> <summary>View changed files</summary> 📝 `docker/Dockerfile` (+2 -2) 📝 `docker/Dockerfile.dev` (+1 -1) 📝 `docker/docker-compose.dev.yml` (+58 -20) 📝 `docs/docs/08-development/01-setup.md` (+53 -20) </details> ### 📄 Description ## Summary duplicate/related to: * #584 * #580 --- * opinionatedly renamed and moved `docker-compose.dev.yml` to root as `docker-compose.yml` * applied the principles from `start-dev.sh` on `docker-compose.yml` * defined naive defaults, so that anybody can do `docker compose up` without even setting up a .env file to have a simple dev instance running * still supports out of the box root `.env` overwrites due to the side-effect of having the `.env` in the the same dir as docker-compose.yml * handles `prep` container execution and `DATA_DIR` init * ensured that data is persisted across subsequent `docker compose up` * ensured that fast reload works for dev server ## Details First and foremost, why all the refactoring when there is already a `docker-compose.dev.yml`? The "improvement" is proposed for 2 reasons: 1. i naively try to use `docker compose -f docker/docker-compose.dev.yml up` but there was an error on the latest main ``` ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-9.15.9.tgz Scope: all 24 workspace projects ╭───────────────────────────────────────────────────────────────────╮ │ │ │ Update available! 9.15.9 → 10.22.0. │ │ Changelog: https://github.com/pnpm/pnpm/releases/tag/v10.22.0 │ │ Run "corepack use pnpm@10.22.0" to update. │ │ │ ╰───────────────────────────────────────────────────────────────────╯ > karakeep@0.1.0 db:migrate /app > pnpm --filter @karakeep/db run migrate > @karakeep/db@0.1.0 migrate /app/packages/db > tsx migrate.ts node:internal/modules/run_main:123 triggerUncaughtException( ^ Error [TransformError]: You installed esbuild for another platform than the one you're currently using. This won't work because esbuild is written with native code and needs to install a platform-specific binary executable. Specifically the "@esbuild/darwin-arm64" package is present but this platform needs the "@esbuild/linux-arm64" package instead. People often get into this situation by installing esbuild on Windows or macOS and copying "node_modules" into a Docker image that runs Linux, or by copying "node_modules" between Windows and WSL environments. If you are installing with npm, you can try not copying the "node_modules" directory when you copy the files over, and running "npm ci" or "npm install" on the destination platform after the copy. Or you could consider using yarn instead of npm which has built-in support for installing a package on multiple platforms simultaneously. If you are installing with yarn, you can try listing both this platform and the other platform in your ".yarnrc.yml" file using the "supportedArchitectures" feature: https://yarnpkg.com/configuration/yarnrc/#supportedArchitectures Keep in mind that this means multiple copies of esbuild will be present. Another alternative is to use the "esbuild-wasm" package instead, which works the same way on all platforms. But it comes with a heavy performance cost and can sometimes be 10x slower than the "esbuild" package, so you may also not want to do that. at generateBinPath (/app/node_modules/esbuild/lib/main.js:1737:17) at esbuildCommandAndArgs (/app/node_modules/esbuild/lib/main.js:1818:33) at ensureServiceIsRunning (/app/node_modules/esbuild/lib/main.js:1975:25) at transform (/app/node_modules/esbuild/lib/main.js:1876:37) at file:///app/node_modules/tsx/dist/index-7AaEi15b.mjs:14:2865 at applyTransformers (file:///app/node_modules/tsx/dist/index-7AaEi15b.mjs:14:1266) at transform (file:///app/node_modules/tsx/dist/index-7AaEi15b.mjs:14:2812) at load (file:///app/node_modules/tsx/dist/esm/index.mjs?1763396486478:2:2415) at async nextLoad (node:internal/modules/esm/hooks:748:22) at async Hooks.load (node:internal/modules/esm/hooks:385:20) Node.js v22.21.1 /app/packages/db: ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL @karakeep/db@0.1.0 migrate: `tsx migrate.ts` Exit status 1 ELIFECYCLE Command failed with exit code 1. ``` 2. because @MohamedBassem himself said that "This setup wasn't super reliable for me though." and a bonus 3rd point, I wanted to deploy a staging version of karakeep to run my own nightly, but built from my own source code (unmerged changes), so I needed a docker-compose.yml that I was comfortable and familiar with, and hence this PR. --- So with that out of the way, I will explain a little why I moved and renamed the docker-compose.yml. The purpose of `docker compose up` in a repo, in my opinion, is to have a fast way to get dev started. As a result, it should not use a custom name `docker-compose.dev.yml`, or be in a non-root path, because that would go against the idea of "getting started fast". Having the docker-compose.yml in the root also allow us to share `.env` that would be used if the developer chooses to run the application on nodejs directly. But of course, having a `docker` folder still serves it's purpose, for organisational purposes, to put the Dockerfile variants and or docker-compose variants such as more importantly a `docker-compose.prod.yml` example for people who want to run prod instances with a docker-compose file, which is common for selfhosters. But for the purposes for making the life easier for contributors and maintainers, I think it makes sense to have a root docker-compose.yml for that sake. ## Notes Btw, the docs update is entirely AI tweaked, and it's not my intention to keep it that way. If/When this PR is approved, I plan to revisit the docs and give it a human touch lol. - [ ] docs/docs/07-development/01-setup.md - [ ] docs/docs/02-installation/01-docker.md ### Duplicate PR? btw, I am aware of https://github.com/karakeep-app/karakeep/pull/584, but it's opened a year ago and activity seems to have died down due to various reasons. I took a stab at it and I believe I should have address the PR change requests and concerns --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem added the

pull-request

label

2026-03-02 12:00:08 +03:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/karakeep#2001

No description provided.

Rows
Columns