Self-hosted worker container crash-loops: dist/WorkerEntrypoint.js missing from fluxer-api:v1 image

Summary

Following the official self-hosting guide exactly (unmodified docker-compose.yml, Caddyfile, livekit.yaml, .env.example from deploy/self-hosting/ on main), the worker container crash-loops immediately after docker compose up -d. Every other service starts and reports healthy.

Steps to reproduce

Download docker-compose.yml, Caddyfile, livekit.yaml, .env.example from deploy/self-hosting/.
Fill in .env per the instructions (domain, secrets via openssl rand, VAPID keys via the web-push CLI).
docker compose pull && docker compose up -d
docker compose ps -a shows the worker service Restarting.
Logs from the worker container:

Error: Cannot find module '/usr/src/app/fluxer_api/dist/WorkerEntrypoint.js'
    at Module._resolveFilename (node:internal/modules/cjs/loader:1564:15)
    at wrapResolveFilename (node:internal/modules/cjs/loader:1118:27)
    at defaultResolveImplForCJSLoading (node:internal/modules/cjs/loader:1142:10)
    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1169:12)
    at Module._load (node:internal/modules/cjs/loader:1341:5)
    at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
    at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
    at node:internal/main/run_main_module:33:47 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

Environment

Ubuntu 26.04 LTS, fresh instance
Docker 29.7.2, API 1.55
Image: ghcr.io/fluxerapp/fluxer-api:v1 (the default via .env.example's FLUXER_IMAGE_TAG=v1)

Analysis

docker-compose.yml on main defines worker as:

working_dir: /usr/src/app/fluxer_api
command: ["node", "dist/WorkerEntrypoint.js"]
image: ${FLUXER_REGISTRY:-ghcr.io/${FLUXER_REGISTRY_OWNER:-fluxerapp}}/fluxer-api:${FLUXER_IMAGE_TAG:-v1}

fluxer_api/Dockerfile does build and COPY --from=deploy /usr/src/app/fluxer_api/dist ./dist, and the source tree has a separate tsconfig.worker.json, implying WorkerEntrypoint is meant to be its own compiled build target distinct from dist/AppEntrypoint.js. But the currently-published v1 tag on GHCR does not contain dist/WorkerEntrypoint.js. This looks like a regression since #714 ("[Selfhosted] Worker component is private," closed 2026-07-08), where maintainers confirmed worker used the same image and default command as api, distinguished only by environment variables (FLUXER_API_WORKER_MODE=all_lanes, etc.) — no separate compiled entrypoint was involved at that time. It appears worker was later split into its own entrypoint on main, but the v1 tag hasn't been rebuilt to include it (or the build pipeline isn't producing that file for whatever v1 currently points to). The GHCR tag list for fluxer-api includes many date-stamped build tags (e.g. 2026.815.131154) alongside v1/latest, confirming v1 floats rather than pinning a single release. As a possible workaround, we tried pinning FLUXER_IMAGE_TAG to a specific dated tag, but that doesn't work either — the same timestamp tag exists for fluxer-api but returns 404 for fluxer-media-proxy and fluxer-gateway, so each service image appears to be built/tagged independently rather than as a synchronized release train.

Impact

Blocks the official self-hosting docker-compose stack from working out of the box. worker (background job processing, cron scheduling, voice reconciliation per its env vars) never starts.

1 comment

HampusStaff 1 vote 1mo ago originally by @hampus-fluxer on GitHub

Hi there, sorry about this – you'll have to download the compose file from an older revision – I was in the middle of doing a bunch of changes without building new images just yet, directly on main, and the docs unfortunately pointed to the latest version on main rather than a point-in-time SHA. Please use this version of the Compose file instead for the time being: https://github.com/fluxerapp/fluxer/blob/3b1eb56713d59181823df284b9646c890d2a3cba/deploy/self-hosting/docker-compose.yml. I'll get the docs updated for the time being to reduce confusion whilst I finalise the new builds.