From d9b26f9fb4dd7291f203793f69dc09f57f37217c Mon Sep 17 00:00:00 2001 From: MacBook Date: Mon, 4 May 2026 05:55:46 +0200 Subject: [PATCH] docs: link Caddyfile.example and finalize website documentation --- Caddyfile.example | 37 +++++++++++++++++++++++++++++++++ README.md | 3 ++- website/README.md | 52 ++++++++++++++++++++++++----------------------- 3 files changed, 66 insertions(+), 26 deletions(-) create mode 100644 Caddyfile.example diff --git a/Caddyfile.example b/Caddyfile.example new file mode 100644 index 0000000..21e316f --- /dev/null +++ b/Caddyfile.example @@ -0,0 +1,37 @@ +# KoalaSync - Production Caddy Configuration Example +# Replace domains and paths with your actual setup. + +# 1. Marketing Website & Invitation Bridge +koalasync.shik3i.net { + root * /var/www/koalasync/website + file_server + encode zstd gzip + + # Security Headers + header { + # Prevent FLoC tracking + Permissions-Policy interest-cohort=() + # Security best practices + Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" + X-Content-Type-Options nosniff + X-Frame-Options DENY + Referrer-Policy no-referrer-when-downgrade + } +} + +# 2. Relay Server (Socket.IO / WebSocket) +sync.shik3i.net { + reverse_proxy localhost:3000 { + # Ensure WebSocket support is explicitly handled if needed + # (Caddy usually handles this automatically) + header_up Host {host} + header_up X-Real-IP {remote_host} + } + + # Security Headers for the relay + header { + X-Content-Type-Options nosniff + X-Frame-Options DENY + Referrer-Policy no-referrer + } +} diff --git a/README.md b/README.md index 34944a8..d916b6e 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ The server will be available at `ws://localhost:3000`. See [docker-compose.examp To connect your extension to a self-hosted server, open the popup → **Room** tab → select **Custom Server** → enter your server's WebSocket URL (e.g., `ws://localhost:3000`). -> **⚠️ Note**: `ws://` only works for `localhost`. If you deploy to a real domain, you **must** use `wss://` (e.g., `wss://sync.yourdomain.com`). This requires a TLS-terminating reverse proxy (e.g., Caddy, Nginx, or Traefik) in front of the relay server. +> **⚠️ Note**: `ws://` only works for `localhost`. If you deploy to a real domain, you **must** use `wss://` (e.g., `wss://sync.yourdomain.com`). This requires a TLS-terminating reverse proxy (e.g., Caddy, Nginx, or Traefik) in front of the relay server. See [Caddyfile.example](Caddyfile.example) for a production-ready template. --- @@ -80,6 +80,7 @@ To connect your extension to a self-hosted server, open the popup → **Room** t - **[HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**: Step-by-step walkthrough of the complete user flow. - **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Deep-dive into the two-phase sync and heartbeat logic. - **[SECURITY.md](SECURITY.md)**: Disclosure policy and security practices. +- **[Caddyfile.example](Caddyfile.example)**: Production Caddy configuration for website and relay. --- diff --git a/website/README.md b/website/README.md index 1cd52b7..9cc5c8c 100644 --- a/website/README.md +++ b/website/README.md @@ -1,31 +1,39 @@ -# KoalaSync Landing Page +# KoalaSync Website & Invitation Bridge -This directory contains the static marketing website for KoalaSync. It is built using vanilla HTML, CSS, and JavaScript to ensure maximum performance, zero tracking, and easy hosting. +This directory contains the KoalaSync website. It serves a dual purpose: it is both the **marketing landing page** and the **technical bridge** for joining synchronized rooms. -## Features -- **Privacy First**: No external fonts, scripts, or trackers. -- **Modern Tech Aesthetic**: Pure CSS animated gradients and glassmorphism. -- **Smart Join**: Integrated bridge for communication with the KoalaSync browser extension. +## Core Roles + +### 1. Marketing & Onboarding +Provides a premium, bilingual (EN/DE) overview of features, setup instructions, and direct links to the extension stores. + +### 2. The Invitation Bridge (`join.html`) +The website handles incoming invitation links. When a user clicks a link like `koalasync.shik3i.net/join.html#join:roomID:pass`, the website: +- **Detects the Extension**: Verifies if KoalaSync is installed via the `bridge.js` content script. +- **Privacy-First Handshake**: The room credentials (ID/Password) are stored in the **URL Hash (#)**. This ensures the sensitive credentials **never reach the web server** and are processed entirely within the user's browser. +- **Auto-Join**: If the extension is detected, it automatically triggers the join flow without requiring user input. + +## Architecture + +The website is 100% **Static HTML, CSS, and JS**. +- **Zero Backend**: No Node.js, PHP, or databases are required to host the website. +- **Zero Tracking**: All assets (fonts, icons) are self-hosted to prevent third-party tracking. +- **Responsive**: Fully optimized for mobile with a native-feel hamburger menu. ## Hosting with Caddy -Caddy is the recommended web server for KoalaSync due to its automatic HTTPS and simple configuration. +Caddy is the recommended web server. It provides automatic HTTPS and high-performance static file serving. -### Example Caddyfile +### Recommended Caddyfile -To host the website on `koalasync.shik3i.net`, you can use the following configuration: +For a more comprehensive configuration that includes the Relay Server reverse proxy, see the root [Caddyfile.example](../Caddyfile.example). ```caddy koalasync.shik3i.net { - # Path to the website directory root * /var/www/koalasync/website - - # Enable static file serving file_server - - # Enable Gzip/Zstd compression encode zstd gzip - + # Security Headers header { # Prevent FLoC tracking @@ -36,16 +44,10 @@ koalasync.shik3i.net { X-Frame-Options DENY Referrer-Policy no-referrer-when-downgrade } - - # Custom 404 page - handle_errors { - rewrite * /{err.status_code}.html - file_server - } } ``` -### Deployment Steps -1. Copy the contents of this folder to `/var/www/koalasync/website` on your server. -2. Update the path in your `Caddyfile`. -3. Reload Caddy: `caddy reload`. +## Local Development + +1. Open `index.html` directly in any browser. +2. To test the invitation flow locally, use a local server (e.g., `npx serve .`) and navigate to `http://localhost:5000/join.html#join:test-room:test-pass`.