mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-07-27 20:39:10 +00:00
KoalaDev
75 lines
4.1 KiB
Markdown
75 lines
4.1 KiB
Markdown
# KoalaSync Website & Invitation Bridge
|
|
|
|
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.
|
|
|
|
## Core Roles
|
|
|
|
### 1. Marketing & Onboarding
|
|
Provides a premium, multi-language (EN/DE/FR/ES/PT-BR/RU) 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 `sync.koalastuff.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**.
|
|
- **Static i18n Compiler**: The site uses a lightweight, zero-dependency Node.js compiler (`build.js`) to parse dictionary files inside `/locales/` against a single source-of-truth template (`template.html`), outputting the fully deployable static folder to `/www/`.
|
|
- **Build-time Minification**: `build.js` automatically minifies CSS and JS during compilation using a built-in state-machine tokenizer (no npm dependencies). Source files are written unminified (`style.css`, `app.js`, `lang-init.js`) — always edit source files, never the generated `.min.*` files in `www/`.
|
|
- **Zero Backend**: No Node.js, PHP, or databases are required to host the compiled 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. It provides automatic HTTPS and high-performance static file serving.
|
|
|
|
### Recommended Caddyfile
|
|
|
|
For a more comprehensive configuration that includes the Relay Server reverse proxy, see the root [Caddyfile.example](../examples/Caddyfile.example).
|
|
|
|
```caddy
|
|
sync.koalastuff.net {
|
|
root * /var/www/koalasync/website/www
|
|
file_server
|
|
encode zstd gzip
|
|
|
|
# Static Caching for high-performance PageSpeed (1 year with validation)
|
|
@static {
|
|
file
|
|
path *.ico *.css *.js *.png *.svg *.webp
|
|
}
|
|
header @static Cache-Control "public, max-age=31536000, must-revalidate"
|
|
|
|
# Security Headers & Content Security Policy (CSP)
|
|
header {
|
|
# Strict Content Security Policy (restricts scripts and connections to self, forbids frames)
|
|
Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; object-src 'none'; frame-ancestors 'none';"
|
|
# 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
|
|
}
|
|
}
|
|
```
|
|
|
|
## Local Development & Compilation
|
|
|
|
1. Run the compilation script from the repository root to generate the `/website/www` folder:
|
|
```bash
|
|
node website/build.js
|
|
```
|
|
2. Serve the compiled `/www` directory using any local development server:
|
|
```bash
|
|
npx serve website/www
|
|
```
|
|
3. To test the invitation flow locally, navigate to `http://localhost:5000/join.html#join:test-room:test-pass`.
|
|
|
|
> [!IMPORTANT]
|
|
> **Never edit files inside `website/www/` directly.** This directory is fully auto-generated by `build.js`. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, locale files in `locales/`) and re-run `node website/build.js` to apply changes. CSS and JS are output as `style.min.css`, `app.min.js`, and `lang-init.min.js` — the `.min.*` naming makes it visually obvious these are build artifacts. Editing minified files in `www/` will result in lost changes on the next build.
|