# CODEX_VPS_SETUP.md — развернуть автономный SHiNE test publisher

Цель: установить test publisher на Ubuntu VPS так, чтобы он постоянно работал через systemd, переживал reboot/сбой сети, публиковал в несколько каналов одного тестового пользователя и не требовал ручного запуска.

## Что агент должен получить от оператора
Никогда не печатай приватные ключи в лог.
1. Реальный `blockchain_name` тестового пользователя.
2. Solana-format JSON blockchain key → `keys/blockchain.json`.
3. Arweave JWK → `keys/arweave-wallet.json` (нужен только для prepare).
4. Для каждого канала реальный `channel_root_block_number` CREATE_CHANNEL.
5. Подтверждение WebSocket URL сервера (example: `wss://t3.shineup.me/ws`).

## Установка
Предполагаемый каталог: `/opt/shine-test-publisher/v2`, Linux user: `shine`.

```bash
sudo useradd --system --home /opt/shine-test-publisher --shell /usr/sbin/nologin shine 2>/dev/null || true
sudo mkdir -p /opt/shine-test-publisher
sudo chown -R shine:shine /opt/shine-test-publisher
# скопировать содержимое tools/test-publisher/v2 в /opt/shine-test-publisher/v2

cd /opt/shine-test-publisher
sudo -u shine python3 -m venv .venv
sudo -u shine .venv/bin/pip install -r v2/requirements.txt
sudo chmod 700 v2/keys
sudo chmod 600 v2/keys/*.json
```

`requirements.txt` должен содержать зависимости publisher и prepare (`cryptography`, `websockets`, `requests`, `arweave-python-client`).

## Конфиги
Скопировать:
- `config.multi.example.json` → `config.multi.json`
- `prepare.multi.example.json` → `prepare.multi.json`

Заменить placeholders. Не угадывать CREATE_CHANNEL block numbers.

Расписание по умолчанию:
- jokes: случайно 1–3 активных часа;
- остальные: случайно 3–7 активных часов;
- timezone: Europe/Warsaw;
- quiet: 22:00–08:00.

Quiet hours НЕ расходуют интервал. Если из 5 часов до ночи прошло 2 часа, после 08:00 должно остаться 3 часа.

## Подготовка media
Один раз и затем после добавления новых картинок:
```bash
cd /opt/shine-test-publisher/v2
../.venv/bin/python prepare/prepare_all_channels.py --config prepare.multi.json
```
Скрипт обязан пройти ВСЕ channels. Известный Arweave ID сначала проверяется через gateway. Существующий файл повторно не загружается. Отсутствующий — загружается и state обновляется атомарно.

После успешной подготовки JWK не нужен постоянному publisher. Для минимизации риска можно перенести JWK в защищённое offline-хранилище; тогда повторный prepare потребует вернуть его.

## Проверка до systemd
```bash
../.venv/bin/python publisher/publisher_multi.py status --config config.multi.json
../.venv/bin/python publisher/publisher_multi.py publish-now --channel jokes --config config.multi.json
```
Проверить появление блока на SHiNE server и затем в Viewer. Не запускать два экземпляра publisher для одного blockchain key.

## systemd
```bash
sudo cp systemd/shine-test-publisher-multi.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now shine-test-publisher-multi
sudo systemctl status shine-test-publisher-multi
journalctl -u shine-test-publisher-multi -f
```

Unit использует `Restart=on-failure`; publisher хранит pending/state на диске и после рестарта сверяет global head перед продолжением. При конфликте global head он обязан остановиться, а не создавать форк.

## После настройки
Проверить:
- `systemctl is-enabled` = enabled;
- `systemctl is-active` = active;
- `multi-state.json` создаётся и меняется;
- в quiet hours нет публикаций;
- reboot VPS → service возвращается в active;
- приватные JSON имеют mode 600;
- prepared queues существуют для всех пяти каналов.

## Запреты
Не коммитить/архивировать реальные keys, JWK, `multi-state.json`, `upload-state.json`.
Не запускать параллельно v1/v2 single publisher и multi publisher с одним ключом.
Не сбрасывать state ради устранения ошибки chain-head: сначала выяснить расхождение.