### Manual Server Setup

Source: https://github.com/shik3i/koalasync/blob/main/server/README.md

Steps for manually installing and starting the KoalaSync server using npm. This involves navigating to the server directory, installing dependencies, and starting the application.

```bash
cd server
npm install
npm start
```

--------------------------------

### Start Docker Compose Server

Source: https://github.com/shik3i/koalasync/blob/main/docs/AI_INIT.md

Initiate the server environment using Docker Compose.

```bash
docker-compose up --build
```

--------------------------------

### Install Dependencies and Build Extension

Source: https://github.com/shik3i/koalasync/blob/main/CONTRIBUTING.md

Clone the repository, install Node.js dependencies, and build the browser extension. Ensure Node.js v18+ is installed.

```bash
git clone https://github.com/Shik3i/KoalaSync.git
cd KoalaSync
npm install
node scripts/build-extension.cjs
```

--------------------------------

### Serve Website Locally (Python)

Source: https://github.com/shik3i/koalasync/blob/main/docs/AI_INIT.md

Start a local HTTP server using Python 3 to test the website.

```bash
python3 -m http.server 8080 -d website/www
```

--------------------------------

### Build KoalaSync Extension

Source: https://github.com/shik3i/koalasync/blob/main/extension/README.md

Run this command to prepare the extension for installation. It builds the extension from the repository root.

```bash
npm run build:extension
```

--------------------------------

### Build KoalaSync Extension from Source

Source: https://github.com/shik3i/koalasync/blob/main/README.md

Installs dependencies and builds the browser extension. Compiled artifacts are placed in the 'dist/' directory.

```bash
npm install
npm run build:extension
```

--------------------------------

### Deploy KoalaSync Relay Server with Docker

Source: https://github.com/shik3i/koalasync/blob/main/README.md

Pulls the latest KoalaSync Docker image and starts a private relay server using a Caddy example compose file. The server will be accessible at ws://localhost:3000.

```bash
# Pull the latest image
docker pull ghcr.io/shik3i/koalasync:latest

# Or use our example compose file
cp examples/docker-compose.caddy.example.yml docker-compose.yml
docker-compose up -d
```

--------------------------------

### Website Language Metadata Example

Source: https://github.com/shik3i/koalasync/blob/main/docs/TRANSLATION.md

When creating a new language for the website, configure the metadata at the top of the JSON file. This includes the language code, HTML class, canonical path, language toggle URL, and text.

```json
{
  "LANG_CODE": "it",
  "HTML_CLASS": "lang-it",
  "CANONICAL_PATH": "it/",
  "LANG_TOGGLE_URL": "../",
  "LANG_TOGGLE_TEXT": "EN"
}
```

--------------------------------

### Clone Your Fork

Source: https://github.com/shik3i/koalasync/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine to start making changes.

```git
git clone https://github.com/YOUR-USERNAME/KoalaSync.git
```

--------------------------------

### Server Environment Configuration

Source: https://github.com/shik3i/koalasync/blob/main/server/README.md

Configure server settings by copying and modifying the .env.example file. These variables control port, room limits, peer limits, and logging.

```bash
PORT="3000"
MAX_ROOMS="1000"
MAX_PEERS_PER_ROOM="25"
MIN_VERSION="1.0.0"
# Optional: enables aggregate-only admin metrics on /health with Authorization: Bearer <token>
# Use a long random token, 32+ characters recommended.
ADMIN_METRICS_TOKEN=""

# Optional: set to "1" to enable verbose connection, room-join/leave, and CORS logs in the console. Default is "0" (disabled).
DEBUG_LOGGING="0"
```

--------------------------------

### Run Beta Relay Server with Docker

Source: https://github.com/shik3i/koalasync/blob/main/docs/host-control-mode-TESTING.md

This snippet shows how to log in to GHCR, pull the beta server image, and run it as a Docker container. Ensure you replace placeholders with your actual user and choose a server salt.

```bash
# Log in (the package is private → PAT with read:packages)
echo "$GHCR_PAT" | docker login ghcr.io -u <your-gh-user> --password-stdin

# Pull + (re)create — NOTE: `docker restart` does NOT pick up a new image,
you must remove and re-run (or use compose / Watchtower).
docker pull ghcr.io/shik3i/koalasync:beta
docker rm -f koala-beta 2>/dev/null || true
docker run -d --name koala-beta -p 3000:3000 \
  -e SERVER_SALT='choose-your-own-salt' \
  ghcr.io/shik3i/koalasync:beta
```

--------------------------------

### Build and Serve Website Locally

Source: https://github.com/shik3i/koalasync/blob/main/CONTRIBUTING.md

Compile the static site and serve it locally using Node.js and Python's http.server. Useful for testing website changes.

```bash
node website/build.cjs           # Compile static site → www/
python3 -m http.server 8080 -d website/www  # Serve locally
```

--------------------------------

### Serve Compiled Website Locally

Source: https://github.com/shik3i/koalasync/blob/main/website/README.md

Use this command to serve the compiled `/www` directory using a local development server. This is useful for testing the website before deployment.

```bash
npx serve website/www
```

--------------------------------

### Build Website with Translations

Source: https://github.com/shik3i/koalasync/blob/main/docs/TRANSLATION.md

This command builds the website, incorporating your new translations. It's essential to run this to verify the final output of your localization efforts.

```bash
node website/build.cjs
```

--------------------------------

### Docker Image Pull and Build

Source: https://github.com/shik3i/koalasync/blob/main/server/README.md

Instructions for pulling the pre-built KoalaSync server image from GHCR or building it locally from the repository.

```bash
# Pull from GHCR
docker pull ghcr.io/shik3i/koalasync:latest

# Or build from the repository root
docker build -t koala-sync-server -f server/Dockerfile .
```

--------------------------------

### Run KoalaSync Build Script

Source: https://github.com/shik3i/koalasync/blob/main/docs/SYNC_GUIDE.md

Execute the Node.js build script from the repository root to synchronize protocol constants and prepare the extension.

```bash
node scripts/build-extension.cjs
```

```bash
npm run build:extension
```

--------------------------------

### Data Flow Summary Diagram

Source: https://github.com/shik3i/koalasync/blob/main/docs/HOW_IT_WORKS.md

Illustrates the communication path between browser extensions and the relay server for synchronization.

```text
┌─────────────┐     WebSocket      ┌──────────────┐     WebSocket      ┌─────────────┐
│  Extension  │ ←─────────────────→│  Relay Server │←──────────────────→│  Extension  │
│  (User A)   │   JOIN_ROOM        │  (RAM only)   │   JOIN_ROOM        │  (User B)   │
│             │   PLAY/PAUSE/SEEK  │               │   PLAY/PAUSE/SEEK  │             │
│             │   FORCE_SYNC_*     │  Sanitizes &  │   FORCE_SYNC_*     │             │
│             │   PEER_STATUS      │  relays only  │   PEER_STATUS      │             │
│             │   EPISODE_*        │               │   EPISODE_*        │             │
└──────┬──────┘                    └───────────────┘                    └──────┬──────┘
       │                                                                      │
  ┌────┴─────┐                                                          ┌─────┴────┐
  │ content  │  Listens to <video> events                               │ content  │
  │   .js    │  Controls playback                                       │   .js    │
  └──────────┘                                                          └──────────┘
```

--------------------------------

### Verify Extension Locales

Source: https://github.com/shik3i/koalasync/blob/main/docs/TRANSLATION.md

Run this command to test the extension's locale files for missing keys or syntax errors. Ensure all translations are complete and valid before proceeding.

```bash
node scripts/test-locales.cjs
```

--------------------------------

### Verify Website Locales

Source: https://github.com/shik3i/koalasync/blob/main/docs/TRANSLATION.md

Execute this command to check the website's locale files for any missing keys or syntax errors. This step is crucial for ensuring translation consistency.

```bash
node scripts/test-website-locales.mjs
```

--------------------------------

### Simple Caddyfile Configuration for KoalaSync

Source: https://github.com/shik3i/koalasync/blob/main/website/template.html

A basic Caddyfile configuration for KoalaSync, setting up the root directory for website assets and enabling compression. It also includes a reverse proxy for the sync server.

```caddy
sync.koalastuff.net {
    root * /var/www/koalasync/website/www
    encode zstd gzip
    
    # Clean URLs support (no .html required)
    try_files {path} {path}.html {path}/
    file_server
}

syncserver.koalastuff.net {
    reverse_proxy localhost:3000
}
```

--------------------------------

### Check JavaScript Files

Source: https://github.com/shik3i/koalasync/blob/main/docs/AI_INIT.md

Verify the integrity of generated JavaScript files for the application and language initialization.

```bash
node --check website/www/app.js && node --check website/www/lang-init.js
```

--------------------------------

### Update Minimum Server Version

Source: https://github.com/shik3i/koalasync/blob/main/docs/AI_INIT.md

Modify the MIN_VERSION in the .env file to enforce a minimum client version.

```bash
Update MIN_VERSION in the server's .env file
```

--------------------------------

### Recommended Caddyfile Configuration

Source: https://github.com/shik3i/koalasync/blob/main/website/README.md

This Caddyfile configuration is recommended for hosting the KoalaSync website. It includes static file serving, caching, security headers, and a Content Security Policy.

```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
    }
}
```

--------------------------------

### Advanced Caddyfile Configuration with Security Headers

Source: https://github.com/shik3i/koalasync/blob/main/website/template.html

An advanced Caddyfile configuration that includes security headers for enhanced protection, such as HSTS, X-Frame-Options, and Content-Security-Policy. It also configures caching for static assets.

```caddy
(security_headers) {
    header {
        # Enable HTTP Strict Transport Security (HSTS)
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        # Prevent clickjacking attacks (Sameorigin)
        X-Frame-Options "SAMEORIGIN"
        # Prevent MIME-sniffing
        X-Content-Type-Options "nosniff"
        # Enable browser XSS protection
        X-XSS-Protection "1; mode=block"
        # Control referrer information
        Referrer-Policy "strict-origin-when-cross-origin"
        # Hide Caddy server stamp signature
        -Server
    }
}

sync.koalastuff.net {
    encode zstd gzip
    root * /var/www/koalasync/website/www

    # Clean URLs: Resolves paths without .html in the URL
    try_files {path} {path}.html {path}/
    file_server

    # Static Caching for high performance
    @static {
        file
        path *.ico *.css *.js *.png *.svg *.webp *.avif
    }
    header @static Cache-Control "public, max-age=31536000, must-revalidate"

    # Hardened Security & Permission Policies
    import security_headers
    header {
        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'; base-uri 'none'; form-action 'none';"
        Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()"
    }
}

syncserver.koalastuff.net {
    import security_headers
    encode zstd gzip
    reverse_proxy KoalaSync:3000
}
```

--------------------------------

### Verify Extension Binary Attestations

Source: https://github.com/shik3i/koalasync/blob/main/README.md

Verifies the integrity of a browser extension binary artifact using GitHub's `gh attestation verify` command, ensuring it was built from the specified repository's source code.

```bash
gh attestation verify dist/koalasync-chrome.zip \
  -R Shik3i/KoalaSync
```

--------------------------------

### SSH Tunnel for Local Connection

Source: https://github.com/shik3i/koalasync/blob/main/docs/host-control-mode-TESTING.md

Use this command to SSH tunnel a remote port to your local machine, allowing the extension to connect to a non-TLS beta server as if it were local.

```bash
ssh -L 3000:localhost:3000 your-beta-server
```