92 lines
4.3 KiB
Markdown
92 lines
4.3 KiB
Markdown
# 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.
|