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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#1,787 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 3 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
72/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
docker-compose, typescript
Área
documentation

Línea de trabajo

Lee en docs/en/2-tutorials/2.0-development.mdx la sección sobre Configuration y la configuración de MongoDB, y el paso 4 de docs/en/2-tutorials/2.1-deployment.md; compara sus instrucciones con los valores predeterminados de almacenamiento en .env.template y docker-compose.yaml. Actualiza ambos tutoriales para que aborden el almacenamiento para desarrollo y el endpoint público de despliegue, y luego verifica que la configuración documentada coincida con la configuración esperada; docs/ no tiene un ejecutor de pruebas, así que el issue sugiere seguir cada tutorial en un clon nuevo.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
119
Forks
19
Merge medio
6 d 16 min
PR fusionados (30 d)
34

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de DouglasNeuroInformatics/OpenDataCapture

Todos los issues de DouglasNeuroInformatics/OpenDataCapture

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.