4.0 KiB
Tasks: Deploy to Hosting
Date: 2025-10-15 Spec: spec.md Plan: plan.md
Implementation Strategy
The implementation is broken into phases, starting with foundational backend changes, followed by the core configuration work, and finishing with user-facing error handling and end-to-end testing. User Story 1 (Developer Configuration) contains the critical path tasks and delivers the main goal of the feature. User Story 2 adds robustness and validation.
MVP Scope: Completing all tasks in Phase 3 will deliver a configurable and deployable application.
Phase 1: Setup
Goal: Add necessary dependencies to the backend service.
| Task ID | Description | File(s) | Status |
|---|---|---|---|
| T001 | [Backend] Install cors and dotenv npm packages. |
backend/package.json |
Done |
Phase 2: Foundational Backend Configuration
Goal: Prepare the backend server to use environment variables.
| Task ID | Description | File(s) | Status |
|---|---|---|---|
| T002 | [Backend] Modify the server startup script to load environment variables from a .env file using dotenv. |
backend/src/index.ts |
Done |
Phase 3: User Story 1 - Developer Configuration
Goal: A developer can configure the application for public deployment using environment variables.
Independent Test Criteria: After completing this phase, a developer can follow quickstart.md, deploy the application to a custom domain, and access it without CORS errors.
| Task ID | Description | File(s) | Status |
|---|---|---|---|
| T003 | [Backend Test] Create a new unit test file for CORS configuration. Write tests that verify the correct origin is allowed, an incorrect origin is blocked, and the default same-origin policy is applied when no environment variable is set. | backend/tests/cors.test.ts |
Done |
| T004 | [Backend] Implement the cors middleware in the Express app. The configuration should read from process.env.CORS_ORIGIN, log rejected requests as warnings, and apply the default same-origin policy as defined in the tests. [P] |
backend/src/index.ts |
Done |
| T005 | [Frontend] Modify the API service(s) to use process.env.REACT_APP_API_URL as the base URL for all backend requests. [P] |
frontend/src/services/websocket.ts (and any other relevant services) |
Done |
| T006 | [Root] Update the docker-compose.yaml file to use env_file to pass .env files to the backend and frontend services. |
docker-compose.yaml |
Done |
Checkpoint: The core feature is implemented. The application is now configurable but lacks polished error handling for the user.
Phase 4: User Story 2 - Public Access & Polish
Goal: An end-user is gracefully notified of connection issues, and the deployment is validated. Independent Test Criteria: When the frontend is configured with an invalid backend URL, the user sees a snackbar error message. An E2E test confirms a successful deployment has no CORS errors.
| Task ID | Description | File(s) | Status |
|---|---|---|---|
| T007 | [Frontend] Implement a global error handler that displays a simple error message using the Material-UI (MUI) Snackbar component if the application fails to establish a connection with the backend. |
frontend/src/App.tsx |
Done |
| T008 | [E2E Test] Create a new end-to-end test that deploys the application with custom environment variables and verifies that the app loads without any CORS-related console errors. [P] | tests/e2e/deployment.e2e.test.ts |
Done |
| T009 | [Docs] Update the root README.md with a new "Deployment" section that links to the quickstart.md guide for configuration details. [P] |
README.md |
Done |
Dependencies
- Phase 1 & 2 must be completed before Phase 3.
- Phase 3 must be completed before Phase 4.
Parallel Execution Examples
- Within Phase 3: T004 (Backend CORS) and T005 (Frontend URL) can be worked on in parallel after the test in T003 is written.
- Within Phase 4: T008 (E2E Test) and T009 (Docs) can be worked on in parallel with T007 (Frontend UI).