# 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.