Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Development and deployment tutorials leave file storage enabled but unconfigured, so pnpm dev crashes and deployed file uploads target localhost

Aperta Adatta ai principianti
  • Qualcosa non va?
#1,787 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
72/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
docker-compose, typescript
Ambito
documentation

Direzione di ricerca

Leggi in docs/en/2-tutorials/2.0-development.mdx la sezione Configuration e la configurazione di MongoDB, e il passaggio 4 di docs/en/2-tutorials/2.1-deployment.md; confronta le istruzioni con le impostazioni predefinite di archiviazione in .env.template e docker-compose.yaml. Aggiorna entrambi i tutorial per trattare l’archiviazione in sviluppo e l’endpoint pubblico per il deployment, quindi verifica che le impostazioni documentate corrispondano alla configurazione prevista; docs/ non ha un test runner, quindi l’issue suggerisce di seguire ciascun tutorial su un clone appena creato.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Area: Outreach Bug Difficulty: Low Priority: High

The Development and Deployment tutorials never mention file storage, but the .env they tell you to generate turns it on. Following either tutorial as written gives a broken instance. .env.template sets STORAGE_ENABLED=true with STORAGE_ENDPOINT=http://localhost:9000, and generate-env.sh fills in the keys, so the env schema passes.

  • Development. docker-compose.dev.yaml starts only MongoDB, and nothing listens on port 9000. StorageService.onModuleInit sends HeadBucketCommand, catches the failure, and then sends an unguarded CreateBucketCommand, which also rejects. The api exits during boot. Turbo stops the gateway and web dev servers with it, so the tutorial's final pnpm dev ends in ERROR run failed, and the setup screen never appears. The error never mentions storage. (.agents/docs/playbooks/run-locally.md documents this trap for agents, step 4, but the public tutorial does not.)
  • Deployment. The stack starts, because Compose provides rustfs. The api, however, signs file URLs with STORAGE_PUBLIC_ENDPOINT, and docker-compose.yaml defaults that to http://localhost:${APP_PORT}/storage. The tutorial says to "leave the other settings as the default values", so every presigned upload and download URL sent to a browser points at http://localhost:5500/storage/.... That URL means the user's own machine. Every file instrument fails on a deployment that follows the guide. The changelog's 2.0.0 notes say to set STORAGE_PUBLIC_ENDPOINT "for real deployments", but the tutorial never does.

Where

.env.template:78 and :87:

STORAGE_ENABLED=true
...
STORAGE_PUBLIC_ENDPOINT=

apps/api/src/storage/storage.service.ts:93-103:

async onModuleInit(): Promise<void> {
  if (!this.enabled || this.configService.get('NODE_ENV') === 'test') {
    return;
  }
  const { bucket, s3 } = this.requireStorage();
  try {
    await s3.send(new HeadBucketCommand({ Bucket: bucket }));
  } catch {
    await s3.send(new CreateBucketCommand({ Bucket: bucket }));
  }
}

docker-compose.yaml:43:

- STORAGE_PUBLIC_ENDPOINT=${STORAGE_PUBLIC_ENDPOINT:-http://localhost:${APP_PORT}/storage}

docs/en/2-tutorials/2.0-development.mdx:63-69 (Configuration) and :93-112 (MongoDB only), then :172-176 (pnpm dev). docs/en/2-tutorials/2.1-deployment.md:83-97, where Step 4 edits only SITE_ADDRESS, GATEWAY_SITE_ADDRESS, APP_PORT and GATEWAY_PORT:

For the purposes of this guide, we will leave the other settings as the default values.

Reproduce

Development:

  1. On a fresh clone, follow the Development tutorial: ./scripts/generate-env.sh, start the dev MongoDB, initiate the replica set, pnpm install, pnpm dev.

Actual: the api crashes on boot with a connection error to localhost:9000, turbo stops all three apps, and http://localhost:3000 never serves the setup screen.
Expected: following the tutorial ends at the setup screen.

Deployment:

  1. Follow the Deployment tutorial on a server with SITE_ADDRESS=myplatform.com.
  2. Sign in from another computer and complete a file instrument, such as the demo ARBITRARY_SINGLE_FILE.

Actual: the browser PUTs the file to http://localhost:5500/storage/open-data-capture/..., which is the user's own computer, and the upload fails.
Expected: the presigned URL uses https://myplatform.com/storage/..., which Caddy proxies to rustfs.

Tests

docs/ has no test runner (docs/AGENTS.md). Verify by following each tutorial on a fresh clone: pnpm dev reaches the setup screen, and a file instrument completes on a deployment that follows the guide.

Suggested fix

  • Development tutorial: add a step after "Configuration" to set STORAGE_ENABLED=false in .env, saying that file instruments then answer 503. Alternatively, add a rustfs service to docker-compose.dev.yaml and say that it provides storage.
  • Deployment tutorial, Step 4: add STORAGE_PUBLIC_ENDPOINT=https://myplatform.com/storage to the block of settings to change, and explain that it must be the public address of the core site.

This is separate from #1752, where rustfs itself fails to start on Linux because of a root-owned data directory. With that fixed, the deployment still hands browsers localhost URLs.

Lingua principale
TypeScript
Stelle
119
Fork
19
Merge medio
18h 50m
PR unite (30g)
36

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di DouglasNeuroInformatics/OpenDataCapture

Tutte le issue di DouglasNeuroInformatics/OpenDataCapture

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.