Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open Beginner friendly
  • Is something wrong?
#1,787 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
docker-compose, typescript
Domain
documentation

Research direction

Read docs/en/2-tutorials/2.0-development.mdx around Configuration and the MongoDB setup, and docs/en/2-tutorials/2.1-deployment.md Step 4; compare their instructions with the storage defaults in .env.template and docker-compose.yaml. Update both tutorials to address development storage and the deployment public endpoint, then verify the documented settings match the expected setup; docs/ has no test runner, so the issue suggests following each tutorial on a fresh clone.

Written by the indexing model from the issue text.

Description

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.

Dominant language
TypeScript
Stars
119
Forks
19
Avg merge
1d 2h
Merged PRs (30d)
56

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from DouglasNeuroInformatics/OpenDataCapture

All issues in DouglasNeuroInformatics/OpenDataCapture

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.