caps_enhancer/DEPLOY.md

# Деплой CAPS Enhancer — Self-Hosted Auto-Update

## Как это работает

```
[Сервер]                          [Браузер пользователя]
  update.xml  <── Chrome опрашивает каждые ~5 часов
  caps-enhancer.crx  <── Chrome скачивает при новой версии
```

Chrome сравнивает `version` в `update.xml` с версией установленного расширения.
Если версия на сервере выше — скачивает `.crx` и устанавливает обновление автоматически.

Пользователь устанавливает расширение **один раз** через реестр Windows — дальше всё автоматически.

---

## Часть 1: Первоначальная упаковка (делается один раз)

### Шаг 1. Прописать URL обновления в manifest.json

Открой `manifest.json` и замени `YOUR_DOMAIN` на реальный домен:

```json
"update_url": "https://updates.example.com/caps-enhancer/update.xml",
```

### Шаг 2. Упаковать расширение в .crx

**Способ A — через bat-скрипт (рекомендуется):**

Запусти `pack-crx.bat` из папки проекта. Скрипт сам найдёт Chrome и упакует расширение.

**Способ B — вручную через Chrome:**

1. Открой `chrome://extensions`
2. Включи "Режим разработчика" (правый верхний угол)
3. Нажми "Упаковать расширение"
4. В поле "Корневой каталог расширения" укажи папку `caps-enhancer`
5. Поле "Файл закрытого ключа" оставь пустым при первой упаковке
6. Нажми "Упаковать расширение"

Chrome создаст два файла **в папке рядом с `caps-enhancer`**:
- `caps-enhancer.crx` — файл расширения
- `caps-enhancer.pem` — приватный ключ

> **КРИТИЧНО:** Сохрани `caps-enhancer.pem` в надёжное место!
> Этот ключ определяет ID расширения. Если потеряешь — ID изменится,
> и все установленные у пользователей копии придётся переустанавливать вручную.

### Шаг 3. Узнать ID расширения

**После первой упаковки:**

1. Открой `chrome://extensions`
2. Нажми "Загрузить распакованное расширение" → выбери папку `caps-enhancer`
3. Скопируй ID расширения (длинная строка из 32 символов, например `abcdefghijklmnopqrstuvwxyzabcdef`)

**Или через файл ключа (если Chrome уже закрыт):**

```bash
# На Linux/Mac:
openssl rsa -in caps-enhancer.pem -pubout | openssl dgst -sha256 -binary | base32 | head -c 32 | tr '[:upper:]' '[:lower:]'
```

### Шаг 4. Обновить update.xml

Открой `server/update.xml` и замени:
- `EXTENSION_ID` — ID из предыдущего шага
- `YOUR_DOMAIN` — твой домен
- `version` — текущая версия (из manifest.json)

```xml
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'>
  <app appid='abcdefghijklmnopqrstuvwxyzabcdef'>
    <updatecheck
      status='ok'
      codebase='https://updates.example.com/caps-enhancer/caps-enhancer.crx'
      version='2.7'
    />
  </app>
</gupdate>
```

---

## Часть 2: Настройка сервера

### Требования к серверу

- Любой веб-сервер (nginx, Apache, Caddy, даже GitHub Pages)
- **HTTPS обязателен** — Chrome отказывается скачивать `.crx` по HTTP
- Корректные MIME-типы (см. ниже)

### Вариант A: nginx

Скопируй `server/nginx.conf` на сервер и замени `YOUR_DOMAIN`:

```bash
sudo cp server/nginx.conf /etc/nginx/sites-available/caps-enhancer
sudo ln -s /etc/nginx/sites-available/caps-enhancer /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

Структура файлов на сервере:
```
/var/www/caps-enhancer/
└── caps-enhancer/
    ├── update.xml
    └── caps-enhancer.crx
```

### Вариант B: Apache

Добавь в `.htaccess` или конфиг:

```apache
<Directory /var/www/caps-enhancer>
    AddType application/x-chrome-extension .crx
    AddType application/xml .xml

    <Files "update.xml">
        Header set Cache-Control "no-cache, no-store, must-revalidate"
        Header set Pragma "no-cache"
        Header set Expires 0
    </Files>
</Directory>
```

### Вариант C: Caddy (самый простой, HTTPS автоматически)

```
updates.example.com {
    root * /var/www/caps-enhancer
    file_server

    @xml path *.xml
    header @xml Cache-Control "no-cache, no-store, must-revalidate"
}
```

### Вариант D: GitHub Pages / любой статический хостинг

Положи `update.xml` и `caps-enhancer.crx` в репозиторий.
GitHub Pages раздаёт файлы по HTTPS автоматически.

> Убедись что хостинг отдаёт `.crx` с типом `application/x-chrome-extension`
> или `application/octet-stream`. GitHub Pages обычно справляется.

### Загрузка файлов на сервер

```bash
# С локальной машины через scp
scp server/caps-enhancer.crx server/update.xml user@your-server:/var/www/caps-enhancer/caps-enhancer/

# Или через rsync
rsync -av server/caps-enhancer.crx server/update.xml user@your-server:/var/www/caps-enhancer/caps-enhancer/
```

### Проверка сервера

После загрузки проверь:

```bash
# update.xml должен вернуть XML с версией
curl -I https://updates.example.com/caps-enhancer/update.xml

# .crx должен вернуть 200 и Content-Type: application/x-chrome-extension
curl -I https://updates.example.com/caps-enhancer/caps-enhancer.crx
```

---

## Часть 3: Установка на компьютеры пользователей

Chrome не позволяет устанавливать сторонние расширения вручную через stable-канал.
Единственный способ — через **Windows Policy (реестр)**.

### Способ A: .reg файл (для ручной установки)

1. Открой `server/install-client.reg`
2. Замени `EXTENSION_ID` и `YOUR_DOMAIN`
3. Дай пользователю этот файл
4. Пользователь дважды кликает на `.reg` → соглашается → перезапускает Chrome

```reg
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist]
"1"="abcdefghijklmnopqrstuvwxyzabcdef;https://updates.example.com/caps-enhancer/update.xml"
```

> Требует прав администратора (HKLM).
> Для установки без прав — использовать HKCU (только для текущего пользователя).

### Способ B: PowerShell скрипт

Отредактируй `server/install-client.ps1` (замени ID и домен), запусти от имени администратора:

```powershell
# Запуск от имени администратора:
Start-Process powershell -Verb RunAs -ArgumentList "-File C:\path\to\install-client.ps1"
```

### Способ C: Групповые политики (GPO) — для домена

1. Открой **Group Policy Management Console** (gpmc.msc)
2. Создай или отредактируй GPO
3. Перейди: `Computer Configuration` → `Administrative Templates` → `Google` → `Google Chrome` → `Extensions`
4. Включи политику **"Configure the list of force-installed apps and extensions"**
5. Добавь строку: `abcdefghijklmnopqrstuvwxyzabcdef;https://updates.example.com/caps-enhancer/update.xml`

> Если шаблонов Google нет — скачай ADMX: https://chromeenterprise.google/intl/ru/browser/download/

### Что видит пользователь после установки

- Chrome автоматически устанавливает расширение при следующем запуске
- Иконка появляется в панели расширений
- Пользователь **не может удалить** принудительно установленное расширение (managed)

---

## Часть 4: Выпуск обновления

При каждом обновлении расширения:

### 1. Обнови версию в manifest.json

```json
"version": "2.8"
```

### 2. Упакуй расширение с тем же ключом

Запусти `pack-crx.bat` — скрипт автоматически использует существующий `caps-enhancer.pem`.

### 3. Обнови update.xml

```xml
<updatecheck
  status='ok'
  codebase='https://updates.example.com/caps-enhancer/caps-enhancer.crx'
  version='2.8'
/>
```

### 4. Загрузи на сервер

```bash
scp caps-enhancer.crx update.xml user@your-server:/var/www/caps-enhancer/caps-enhancer/
```

### 5. Готово

Chrome проверяет обновления примерно каждые **5 часов** в фоне.
Обновление применяется при следующем перезапуске браузера (или при перезагрузке расширения).

Форсировать проверку обновлений вручную можно в `chrome://extensions` → "Обновить расширения".

---

## Итоговая структура файлов

```
caps-enhancer/
├── manifest.json              ← update_url прописан
├── pack-crx.bat               ← запускать для упаковки
├── caps-enhancer.pem          ← ХРАНИТЬ В БЕЗОПАСНОМ МЕСТЕ (создаётся при первой упаковке)
├── DEPLOY.md                  ← эта инструкция
├── ...остальные файлы расширения...
└── server/
    ├── update.xml             ← загружать на сервер при каждом обновлении
    ├── caps-enhancer.crx      ← загружать на сервер при каждом обновлении
    ├── nginx.conf             ← конфиг для nginx (один раз)
    ├── deploy.sh              ← скрипт деплоя на сервере
    ├── install-client.reg     ← раздать пользователям для установки
    └── install-client.ps1     ← альтернатива .reg файлу
```

---

## Troubleshooting

| Проблема | Причина | Решение |
|----------|---------|---------|
| Chrome не устанавливает расширение | Нет ключа реестра | Проверь `HKLM\SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist` |
| "Extension not from Chrome Web Store" | Расширение установлено не через policy | Используй реестр, не ручную установку |
| Обновление не прилетает | update.xml закэширован или неверный ID | Очисти кэш, проверь EXTENSION_ID в update.xml |
| Chrome отказывается качать .crx | HTTP вместо HTTPS | Настрой SSL на сервере |
| .crx не скачивается | Неверный MIME-тип | Добавь `application/x-chrome-extension` для `.crx` |
| ID расширения изменился | Потерян .pem файл | Перераспространить .reg с новым ID |