unisono/specs/008-deploy-to-hosting/spec.md

Feature Specification: Deploy to Hosting

Document Status: DRAFT Last Updated: 2025-10-15

1. Introduction

1.1. Feature Name

Deploy to Hosting

1.2. User Problem

The application is currently restricted to running on localhost. This prevents access from the internet and leads to Cross-Origin Resource Sharing (CORS) violations when the frontend and backend are not served from the exact same origin. Users need to deploy the application to a custom, internet-accessible host (like a NAS with DDNS) and have it function correctly.

1.3. Goals

• Enable the application to be deployed to a host other than localhost.
• Ensure the application works seamlessly without CORS errors when accessed from a public domain.
• Maintain the existing Docker-based deployment method.

2. Clarifications

Session 2025-10-15

• Q: What should the user see if the frontend application fails to connect to the configured backend URL? → A: Show a simple error message in a standard snackbar.
• Q: How should the backend log rejected cross-origin (CORS) requests? → A: Log as WARN.
• Q: How should the backend behave if the list of allowed CORS origins is not configured or is empty? → A: Default to same-origin only.

3. User Experience and Design

3.1. User Scenarios

• Scenario 1: Developer Configuration

  • Actor: A developer or system administrator.
  • Action: The developer configures the application with the public domain names for the frontend and backend services. They then deploy the application using the existing Docker setup.
  • Outcome: The application starts successfully, configured to run on the specified public host.

• Scenario 2: Public Access

  • Actor: An end-user.
  • Action: The user navigates to the application's public URL (e.g., https://app.my-nas.com).
  • Outcome: The application loads and is fully functional. All API requests from the frontend to the backend succeed without any CORS-related errors.

4. Functional Requirements

4.1. Configuration

• FR1: The backend server must allow its CORS policy to be configured to accept requests from a specified list of origins.
• FR2: The frontend application must be configurable to direct its API requests to a specified backend URL.
• FR3: The Docker deployment configuration must use environment variables to set all host-specific values, such as domain names and ports.

4.2. Operation

• FR4: The application must function correctly when both frontend and backend are accessed over a secure (HTTPS) connection.
• FR5: All application features available on localhost must be available and work identically when deployed to a custom host.

4.3. Error Handling

• FR6: If the frontend application cannot connect to the configured backend API, it must display a non-intrusive snackbar notification with a simple error message (e.g., "Error: Could not connect to the server.").

5. Non-Functional Requirements

5.1. Security

• NFR1: If the list of allowed CORS origins is not configured or is left empty, the system must default to a "same-origin" policy, blocking all cross-origin requests.

5.2. Observability

• NFR2: Rejected cross-origin (CORS) requests must be logged at a WARN level to facilitate troubleshooting.

6. Success Criteria

• SC1: The application is fully accessible and functional when deployed to a public domain with a valid HTTPS certificate.
• SC2: No CORS errors are present in the browser's developer console during normal application use.
• SC3: A developer can successfully deploy the application to a new host by solely updating environment variables and re-running the standard docker-compose up command.

7. Assumptions and Dependencies

7.1. Assumptions

• The underlying infrastructure (e.g., NAS, Docker environment, DDNS, and reverse proxy for SSL/HTTPS termination) is already configured and managed by the user.
• The user is familiar with managing environment variables for Docker containers.

7.2. Dependencies

• This feature depends on a hosting environment that supports Docker and Docker Compose.

8. Out of Scope

• The setup or configuration of the hosting environment (NAS, DDNS, firewalls, SSL certificates).
• The creation of automated deployment (CI/CD) pipelines.