diff --git a/config/nginx_config_example.conf b/config/nginx_config_example.conf new file mode 100644 index 0000000..ddbf218 --- /dev/null +++ b/config/nginx_config_example.conf @@ -0,0 +1,88 @@ +server { + listen 80; + server_name yourdomain.com; + + location / { + # Redirect all HTTP requests to HTTPS for secure communication + return 301 https://$server_name$request_uri; + } +} + +server { + listen 443 ssl; + server_name yourdomain.com; + + # SSL certificate paths for secure connection + ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; + + # Configuration for serving static files + location /upload/ { + # Define the local directory containing uploaded static files + alias /home/youruser/Documents/Construction-Hazard-Detection/static/uploads/; + + # Enable directory indexing to allow viewing of all files within the directory + autoindex on; + + # Ensure unrestricted access to this location for all users + allow all; + } + + # WebSocket proxy configuration for FastAPI application + location /ws/ { + # Proxy requests to the FastAPI application running on localhost, port 8000 + proxy_pass http://127.0.0.1:8000; + + # Specify HTTP version 1.1 to ensure compatibility with WebSocket protocol + proxy_http_version 1.1; + + # Set headers for WebSocket upgrade to switch protocols as needed + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Pass the original host header to the proxied server + proxy_set_header Host $host; + + # Capture the client’s real IP address and forward it to the proxied server + proxy_set_header X-Real-IP $remote_addr; + + # Forward additional client information, including the originating IP addresses + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + # Indicate the original protocol (HTTP or HTTPS) used by the client + proxy_set_header X-Forwarded-Proto $scheme; + + # Disable buffering to immediately forward data to the client, improving real-time updates + proxy_buffering off; + } + + # General HTTP proxy configuration for FastAPI + location / { + # Proxy all other HTTP requests to the FastAPI application on localhost, port 8000 + proxy_pass http://127.0.0.1:8000; + + # Use HTTP version 1.1 for improved connection handling + proxy_http_version 1.1; + + # Forward the original host information to maintain request integrity + proxy_set_header Host $host; + + # Pass on the real IP address of the client + proxy_set_header X-Real-IP $remote_addr; + + # Add the client's forwarded IP addresses to the header + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + # Include information about the original protocol (HTTP or HTTPS) + proxy_set_header X-Forwarded-Proto $scheme; + + # Specify SSL usage for the forwarded request + proxy_set_header X-Forwarded-SSL on; + + # Include the original port number in the forwarded headers + proxy_set_header X-Forwarded-Port $server_port; + + # Disable buffering to ensure immediate data forwarding + proxy_buffering off; + } +} diff --git a/examples/streaming_web/READMD-zh-tw.md b/examples/streaming_web/READMD-zh-tw.md index 89d53a9..be27e28 100644 --- a/examples/streaming_web/READMD-zh-tw.md +++ b/examples/streaming_web/READMD-zh-tw.md @@ -1,70 +1,117 @@ -# Streaming Web 範例 -本節提供了一個 Streaming Web 應用程序的範例實作，旨在促進即時相機畫面傳輸和更新。此指南提供有關如何使用、配置和了解該應用程序功能的信息。 +🇬🇧 [English](./README.md) | 🇹🇼 [繁體中文](./README-zh-tw.md) -## 使用方式 +# 即時串流網頁範例 + +此部分提供一個即時串流網頁應用程式的實作範例，設計目的是為了實現即時的攝影機串流畫面更新。本指南提供如何使用、配置及瞭解此應用程式的特點與功能。 + +## 使用方法 1. **啟動伺服器：** ```sh python app.py ``` - 或是 - + 或者使用 Gunicorn 啟動應用程式，並設定非同步工作執行緒： ```sh gunicorn -w 1 -k eventlet -b 127.0.0.1:8000 "examples.streaming_web.app:app" ``` -2. **打開您的網頁瀏覽器並導航至：** +2. **訪問應用程式：** + 打開網頁瀏覽器，並導向以下網址： ```sh http://localhost:8000 ``` ## 功能 -- **即時流媒體**：顯示即時相機畫面，每5秒自動更新一次。 -- **WebSocket 整合**：利用 WebSocket 進行高效的即時通信。 -- **動態內容加載**：無需刷新頁面即可自動更新相機圖像。 -- **響應式設計**：適應各種屏幕尺寸，提供無縫的用戶體驗。 -- **可定制的佈局**：使用 CSS 調整佈局和樣式。 +- **即時串流**：顯示即時的攝影機畫面，每 5 秒自動更新。 +- **WebSocket 整合**：使用 WebSocket 進行高效的即時通訊。 +- **動態內容加載**：自動更新攝影機圖片，無需重新整理頁面。 +- **響應式設計**：適應不同螢幕尺寸，提供無縫的使用者體驗。 +- **可自定義的佈局**：透過 CSS 調整佈局和樣式，以符合個人需求。 -## 配置 +## 配置和檔案概覽 -可以通過以下文件配置應用程序： +此應用程式可透過以下關鍵檔案進行自訂和配置： -- **app.py**：啟動伺服器並定義路由的主要應用文件。 -- **routes.py**：定義網頁路由及其相應的處理程序。 +- **app.py**：啟動伺服器並定義路由的主要應用程式檔案。 +- **routes.py**：定義網頁路由及其相應的處理器。 - **sockets.py**：管理 WebSocket 連接和事件。 -- **utils.py**：應用程序中使用的實用函數。 -- **index.js**：處理主頁面動態圖像更新。 -- **camera.js**：管理相機圖像更新。 -- **label.js**：處理基於標籤的 WebSocket 通信和更新。 -- **styles.css**：包含網頁應用程序的樣式，確保響應式和無障礙設計。 - -## 文件概述 - -### app.py -啟動伺服器並設置路由的應用程序主入口。 - -### routes.py -定義各種網頁路由及其相應的請求處理程序。 +- **utils.py**：包含應用程式使用的實用工具函式。 +- **index.js**：處理主頁面中攝影機圖片的動態更新。 +- **camera.js**：管理攝影機畫面的更新。 +- **label.js**：處理 WebSocket 通訊和基於標籤的更新。 +- **styles.css**：包含網頁應用程式的樣式，確保響應式和可存取的設計。 + +請務必根據環境需求檢查並調整這些檔案中的配置設定。 + +## Nginx 配置範例 + +若要使用 Nginx 作為此 FastAPI 應用程式的反向代理，可以參考以下關鍵配置部分。完整的範例配置檔案請參見 `config/` 目錄中的 `nginx_config_example.conf`。 + +1. **HTTP 重定向至 HTTPS**：將所有 HTTP 請求重定向到 HTTPS，確保安全通訊。 + ```nginx + server { + listen 80; + server_name yourdomain.com; + location / { + return 301 https://$server_name$request_uri; + } + } + ``` -### sockets.py -管理 WebSocket 連接，處理連接、重新連接和更新事件。 +2. **HTTPS 配置**：啟用 SSL 憑證並代理靜態文件和 WebSocket 請求。 + ```nginx + server { + listen 443 ssl; + server_name yourdomain.com; + + # SSL 憑證路徑 + ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; + + # 靜態文件 + location /upload/ { + alias /home/youruser/Documents/Construction-Hazard-Detection/static/uploads/; + autoindex on; + allow all; + } + + # WebSocket 配置 + location /ws/ { + proxy_pass http://127.0.0.1:8000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_buffering off; + # 傳遞額外的客戶端資訊標頭 + } + + # 一般 HTTP 代理 + location / { + proxy_pass http://127.0.0.1:8000; + # 傳遞客戶端及 SSL 狀態的標頭 + } + } + ``` -### utils.py -包含應用程序中使用的實用函數。 +3. **SSL 憑證設定** -### index.js -使用 jQuery 定期更新主頁面的相機圖像。 + 若要使用 SSL 保護伺服器，可以使用 Let's Encrypt 提供的免費 SSL 憑證。建議步驟如下： -### camera.js -通過刷新圖像源每5秒更新頁面上的相機圖像。 + - **安裝 Certbot**：使用 Certbot 來自動處理 SSL 憑證的安裝和續期。 + - **取得 SSL 憑證**：使用您的網域名稱運行 Certbot 以創建 SSL 憑證： + ```sh + sudo certbot --nginx -d yourdomain.com + ``` + - **設置自動續期**：Certbot 會自動處理憑證的續期，您可以新增 Cron 排程定期檢查： + ```sh + 0 12 * * * /usr/bin/certbot renew --quiet + ``` -### label.js -管理 WebSocket 連接，處理當前頁面標籤顯示的更新。 +此配置確保 Nginx 伺服器的安全性，並自動管理 SSL 憑證。 -### styles.css -定義應用程序的樣式，包括響應式設計、強制顏色調整以確保無障礙性以及平滑的圖像過渡效果。 +## 其他注意事項 -請確保檢查並調整相應文件中的配置設置以適應您的具體需求。 +欲進一步自訂應用程式，請參考 `examples/streaming_web` 資料夾並根據專案需求調整檔案。此程式碼具有模組化設計，允許您更新或替換組件，以適應擴展性和維護性需求。 diff --git a/examples/streaming_web/README.md b/examples/streaming_web/README.md index ed6a2e6..92df657 100644 --- a/examples/streaming_web/README.md +++ b/examples/streaming_web/README.md @@ -1,3 +1,6 @@ + +🇬🇧 [English](./README.md) | 🇹🇼 [繁體中文](./README-zh-tw.md) + # Streaming Web example This section provides an example implementation of a Streaming Web application, designed to facilitate real-time camera feeds and updates. This guide provides information on how to use, configure, and understand the features of this application. @@ -9,62 +12,106 @@ This section provides an example implementation of a Streaming Web application, python app.py ``` - or - + Alternatively, use Gunicorn to start the application with an asynchronous worker: ```sh gunicorn -w 1 -k eventlet -b 127.0.0.1:8000 "examples.streaming_web.app:app" ``` -2. **Open your web browser and navigate to:** +2. **Access the application:** + Open your web browser and navigate to: ```sh http://localhost:8000 ``` ## Features -- **Real-Time Streaming**: Display real-time camera feeds with automatic updates every 5 seconds. +- **Real-Time Streaming**: Displays real-time camera feeds with automatic updates every 5 seconds. - **WebSocket Integration**: Utilises WebSocket for efficient real-time communication. -- **Dynamic Content Loading**: Automatically updates camera images without refreshing the page. +- **Dynamic Content Loading**: Automatically updates camera images without page refresh. - **Responsive Design**: Adapts to various screen sizes for a seamless user experience. -- **Customisable Layout**: Adjust layout and styles using CSS. +- **Customisable Layout**: Modify layout and styles using CSS for a tailored appearance. -## Configuration +## Configuration and File Overview -The application can be configured through the following files: +The application can be customised and configured via the following key files: - **app.py**: Main application file that starts the server and defines the routes. -- **routes.py**: Defines the web routes and their respective handlers. +- **routes.py**: Defines web routes and their respective handlers. - **sockets.py**: Manages WebSocket connections and events. -- **utils.py**: Utility functions for the application. -- **index.js**: Handles dynamic image updates for the main page. +- **utils.py**: Contains utility functions for the application. +- **index.js**: Handles dynamic image updates on the main page. - **camera.js**: Manages the camera image updates. -- **label.js**: Handles WebSocket communication and updates based on labels. -- **styles.css**: Contains the styles for the web application, ensuring a responsive and accessible design. +- **label.js**: Handles WebSocket communication and label-based updates. +- **styles.css**: Contains the styles for the web application, ensuring responsive and accessible design. -## File Overview +Ensure to review and adjust configuration settings in these files as necessary for your environment. -### app.py -The main entry point of the application that starts the server and sets up routes. +## Nginx Configuration Example -### routes.py -Defines the various web routes and their respective request handlers. +To use Nginx as a reverse proxy for this FastAPI application, you may refer to the following key configuration parts. For a complete example configuration file, see `nginx_config_example.conf` in the `config/` directory. -### sockets.py -Manages WebSocket connections, handling events such as connection, reconnection, and updates. +1. **HTTP Redirect to HTTPS**: Redirect all HTTP requests to HTTPS for secure communication. + ```nginx + server { + listen 80; + server_name yourdomain.com; + location / { + return 301 https://$server_name$request_uri; + } + } + ``` + +2. **HTTPS Configuration**: Enables SSL certificates and proxies static files and WebSocket requests. + ```nginx + server { + listen 443 ssl; + server_name yourdomain.com; + + # SSL certificate paths + ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; + + # Static files + location /upload/ { + alias /home/youruser/Documents/Construction-Hazard-Detection/static/uploads/; + autoindex on; + allow all; + } + + # WebSocket configuration + location /ws/ { + proxy_pass http://127.0.0.1:8000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_buffering off; + # Additional headers to forward client information + } + + # General HTTP proxy + location / { + proxy_pass http://127.0.0.1:8000; + # Forward headers for client and SSL status + } + } + ``` -### utils.py -Contains utility functions used across the application for various tasks. +3. **SSL Certificate Setup** -### index.js -Handles the periodic update of camera images on the main page using jQuery. + To secure the server with SSL, a free SSL certificate from Let's Encrypt can be used. Here are the recommended steps: -### camera.js -Updates the camera images on the page by refreshing the image source every 5 seconds. + - **Install Certbot**: Use Certbot to handle automatic SSL certificate installation and renewal. + - **Obtain SSL Certificates**: Run Certbot with your domain name to create SSL certificates: + ```sh + sudo certbot --nginx -d yourdomain.com + ``` + - **Set Up Automatic Renewal**: Certbot handles automatic renewal; however, you can add a Cron job to check periodically: + ```sh + 0 12 * * * /usr/bin/certbot renew --quiet + ``` -### label.js -Manages WebSocket connections, handling updates based on the current label displayed on the page. +This setup ensures secure, automatic SSL management for the Nginx server. -### styles.css -Defines the styling for the application, including responsive design, forced color adjustments for accessibility, and smooth image transitions. +## Additional Notes -Ensure to review and adjust the configuration settings in the respective files to suit your specific requirements. +For further customisation, refer to the `examples/streaming_web` folder and adjust files as per project needs. The code is modular, allowing you to update or replace components for scalability and maintenance.