starred/karakeep

Fork 0

mirror of https://github.com/karakeep-app/karakeep.git synced 2026-04-26 00:16:03 +03:00

[GH-ISSUE #1673] release Docker image runs with tsx index.ts (development mode), causing high CPU usage and poor performance #1044

New issue

Closed

opened 2026-03-02 11:54:36 +03:00 by kerem · 2 comments

kerem commented

2026-03-02 11:54:36 +03:00

Owner

Originally created by @seferdemirci on GitHub (Jun 24, 2025).
Original GitHub issue: https://github.com/karakeep-app/karakeep/issues/1673

Describe the Bug

The officially published release image on GHCR (ghcr.io/karakeep-app/karakeep:release) appears to run the application using tsx index.ts, resulting in on-the-fly TypeScript transpilation at runtime. This behavior is consistent with development mode, not production.

This leads to consistently high CPU usage and poor performance, especially on resource-constrained hardware such as Intel NUCs. We observed tsx, esbuild, and next-server processes consuming large amounts of CPU time, even during idle periods.

Expected behaviour for a release image is to run precompiled JavaScript (e.g., via node apps/web/server.js), not live compilation via tsx.

Steps to Reproduce

Create a docker-compose.yml using the image ghcr.io/karakeep-app/karakeep:release
Deploy the stack using docker-compose up -d
docker exec into the hoarder_web_1 container
Run top or htop and observe high CPU usage from tsx, esbuild, and next-server
Check the process list and find that the entry point is tsx index.ts, not a precompiled server

Expected Behaviour

The release image should run precompiled production code without invoking tsx, esbuild, or any other live compilation tooling at runtime. This is critical for performance, particularly in production environments.
Expected entrypoint: node apps/web/server.js

Screenshots or Additional Context

We validated that:

The image used is ghcr.io/karakeep-app/karakeep:release (image hash: 755dcc8a2355)
No local mounts or overrides were involved
Container file system shows a monorepo structure, with index.ts as the main entrypoint

Device Details

Intel NUC5CPYH, CPU: Intel Celeron N3050 (2 cores), RAM: 8GB, OS: Ubuntu Server 24.04

Exact Karakeep Version

v0.25.0

Have you checked the troubleshooting guide?

I have checked the troubleshooting guide and I haven't found a solution to my problem

Originally created by @seferdemirci on GitHub (Jun 24, 2025). Original GitHub issue: https://github.com/karakeep-app/karakeep/issues/1673 ### Describe the Bug The officially published `release` image on GHCR (`ghcr.io/karakeep-app/karakeep:release`) appears to run the application using `tsx index.ts`, resulting in on-the-fly TypeScript transpilation at runtime. This behavior is consistent with development mode, not production. This leads to consistently high CPU usage and poor performance, especially on resource-constrained hardware such as Intel NUCs. We observed `tsx`, `esbuild`, and `next-server` processes consuming large amounts of CPU time, even during idle periods. Expected behaviour for a `release` image is to run precompiled JavaScript (e.g., via `node apps/web/server.js`), not live compilation via `tsx`. ### Steps to Reproduce 1. Create a `docker-compose.yml` using the image `ghcr.io/karakeep-app/karakeep:release` 2. Deploy the stack using `docker-compose up -d` 3. `docker exec` into the `hoarder_web_1` container 4. Run `top` or `htop` and observe high CPU usage from `tsx`, `esbuild`, and `next-server` 5. Check the process list and find that the entry point is `tsx index.ts`, not a precompiled server ### Expected Behaviour The `release` image should run precompiled production code without invoking tsx, esbuild, or any other live compilation tooling at runtime. This is critical for performance, particularly in production environments. Expected entrypoint: `node apps/web/server.js` ### Screenshots or Additional Context <img width="1046" alt="Image" src="https://github.com/user-attachments/assets/8f4a43e3-658e-409c-9b23-ef7b8913899d" /> We validated that: - The image used is ghcr.io/karakeep-app/karakeep:release (image hash: 755dcc8a2355) - No local mounts or overrides were involved - Container file system shows a monorepo structure, with index.ts as the main entrypoint ### Device Details Intel NUC5CPYH, CPU: Intel Celeron N3050 (2 cores), RAM: 8GB, OS: Ubuntu Server 24.04 ### Exact Karakeep Version v0.25.0 ### Have you checked the troubleshooting guide? - [x] I have checked the troubleshooting guide and I haven't found a solution to my problem

kerem

2026-03-02 11:54:36 +03:00

closed this issue
added the
bug

status/untriaged
labels

kerem commented

2026-03-02 11:54:37 +03:00

Author

Owner

@teynar commented on GitHub (Jun 25, 2025):

Following up on the issue creator's report and according to the tsx documentation:

Compiling your TypeScript files to JavaScript is not handled by tsx, but it's a necessary step in most setups.

Should I publish TypeScript files?

No. While tsx is capable of running TypeScript files in dependencies if need be (e.g. monorepos), it's highly discouraged to publish uncompiled TypeScript. Source files require a specific compilation configuration in tsconfig.json which may not be read, and TypeScript performance will degrade.

@teynar commented on GitHub (Jun 25, 2025): Following up on the issue creator's report and according to the [tsx documentation](https://tsx.is/compilation): > Compiling your TypeScript files to JavaScript is not handled by tsx, but it's a necessary step in most setups. > > Should I publish TypeScript files? > > No. While tsx is capable of running TypeScript files in dependencies if need be (e.g. monorepos), it's **highly discouraged** to publish uncompiled TypeScript. Source files require a specific compilation configuration in tsconfig.json which may not be read, and [TypeScript performance will degrade](https://x.com/atcb/status/1705675335814271157).

kerem commented

2026-03-02 11:54:37 +03:00

Author

Owner

@seferdemirci commented on GitHub (Jun 26, 2025):

The following Dockerfile might be a temporary solution for now;

# Use the official image as the base
FROM ghcr.io/karakeep-app/karakeep:release

# Override the entrypoint to explicitly run the precompiled Next.js server.
# This assumes the 'server.js' file is directly executable by 'node'.
# The previous `ENTRYPOINT ["/init"]` from s6-overlay will be overridden.
# I explicitly set CMD to ensure the command is what we expect.
# The original image's s6-overlay logic for starting 'svc-web' will no longer apply for *this* container.
# If other s6 services (like db migration or workers) are needed within this *single* container,
# they would need to be started explicitly here or a more complex s6-overlay override would be required.
# Given the problem is specifically the web app's high CPU, this direct approach is best.
ENTRYPOINT ["node", "/app/apps/web/server.js"]

EXPOSE 3000

@seferdemirci commented on GitHub (Jun 26, 2025): The following Dockerfile might be a temporary solution for now; ``` # Use the official image as the base FROM ghcr.io/karakeep-app/karakeep:release # Override the entrypoint to explicitly run the precompiled Next.js server. # This assumes the 'server.js' file is directly executable by 'node'. # The previous `ENTRYPOINT ["/init"]` from s6-overlay will be overridden. # I explicitly set CMD to ensure the command is what we expect. # The original image's s6-overlay logic for starting 'svc-web' will no longer apply for *this* container. # If other s6 services (like db migration or workers) are needed within this *single* container, # they would need to be started explicitly here or a more complex s6-overlay override would be required. # Given the problem is specifically the web app's high CPU, this direct approach is best. ENTRYPOINT ["node", "/app/apps/web/server.js"] EXPOSE 3000 ```

kerem referenced this issue

2026-03-02 11:59:05 +03:00

[PR #1228] [MERGED] feat: add support for filtering by bookmark age #1764

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#1044

No description provided.

Rows
Columns