C9S/mono
3
0
Fork 0
Code Issues 2 Pull Requests 11 Actions Packages Projects 3 Releases Wiki Activity

docs: finalize AGENTS.md with complete Cloud setup instructions

Browse Source 
Co-authored-by: Alex Ant <dacom-dark-sun@users.noreply.github.com>
This commit is contained in:
Cursor Agent
2026-02-25 14:21:29 +00:00
parent a709e2f1e3
commit f0e7b0b63a
1 changed files with 52 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+52 -52
View File
@@ -2,26 +2,51 @@
## Cursor Cloud specific instructions
### Обзор проекта
### Обзор
Монорепозиторий «Цифровой Кооператив» (monocoop) — платформа управления кооперативами на блокчейне EOSIO. pnpm + Lerna. Компоненты в `components/`.
Монорепозиторий «Цифровой Кооператив» (monocoop) — платформа управления кооперативами на блокчейне EOSIO. pnpm v9 + Lerna. Node.js v20.
### Сервисы
| Компонент | Порт | Описание |
|-----------|------|----------|
| controller (coopback) | 2998 | NestJS GraphQL API |
| desktop | 3005 | Vue 3 + Quasar (SPA/SSR) |
| parser (cooparser) | 4000 | Индексация блокчейна через SHiP |
| node (Docker) | 8888 | EOSIO blockchain node |
| mongo (Docker) | 27017 | MongoDB (replica set) |
| redis (Docker) | 6379 | Redis |
| postgres (Docker) | 5432 | PostgreSQL 16 |
| SHiP (Docker) | 8070 | State History Plugin WebSocket |
| Компонент | Контейнер | Порт | Описание |
|-----------|-----------|------|----------|
| controller | coopback | 2998 | NestJS GraphQL API |
| desktop | desktop | 2999 | Vue 3 + Quasar SPA |
| parser | cooparser | 4000 | Индексация блокчейна через SHiP |
| blockchain | node | 8888, 8070 | EOSIO node + State History Plugin |
| MongoDB | mongo | 27017 | Основная БД (replica set) |
| Redis | monoredis | 6379 | Кэш и стримы |
| PG | (см. compose) | 5532→5432 | Реляционная БД |
### Полный цикл запуска dev-окружения
### Полный перезапуск (одна команда)
1. **Сборка shared-библиотек** (порядок важен):
```
pnpm run reboot
```
Делает: останавливает контейнеры → чистит blockchain data и volumes → поднимает инфру → ждёт готовности → `pnpm run boot` → запускает parser и controller.
### Первоначальная настройка Cloud-окружения
1. **`/etc/hosts`** — обязательно для boot (запускается на хосте, обращается к MongoDB по docker hostname):
```
echo "127.0.0.1 mongo" | sudo tee -a /etc/hosts
echo "127.0.0.1 monoredis" | sudo tee -a /etc/hosts
```
2. **WeasyPrint** — системная зависимость для генерации PDF:
```
sudo apt-get install -y python3 python3-venv libpango-1.0-0 libcairo2 libffi-dev libjpeg-dev libopenjp2-7-dev libharfbuzz-dev
sudo python3 -m venv /opt/weasyprint-venv && sudo /opt/weasyprint-venv/bin/pip install WeasyPrint==67
sudo ln -sf /opt/weasyprint-venv/bin/weasyprint /usr/local/bin/weasyprint
```
3. **Контракты** (test-режим — позволяет boot с 1 членом совета):
```
cd components/contracts && sudo rm -rf build && bash build-all.sh test
```
4. **Shared-библиотеки** (порядок важен):
```
pnpm --filter cooptypes run build
pnpm --filter @coopenomics/factory run build
@@ -29,45 +54,20 @@
pnpm --filter @coopenomics/notifications run build
```
2. **Сборка смарт-контрактов** (test-режим позволяет boot с 1 членом совета):
```
cd components/contracts && bash build-all.sh test
```
5. **`.env` файлы** — скопировать из `.env-example`, адаптировать hostnames:
- Controller/Parser (в Docker): хосты по именам контейнеров из docker-compose (порт БД 5432)
- Boot (на хосте): `127.0.0.1`, PG порт `5532`, mongo через `/etc/hosts`
- Desktop: `127.0.0.1`
- **CHAIN_ID**: берётся из `curl http://localhost:8888/v1/chain/get_info` после старта ноды
- Controller требует `VAPID_PUBLIC_KEY` и `VAPID_PRIVATE_KEY`
3. **Запуск инфраструктуры**:
```
docker compose up -d mongo postgres redis node
```
4. **Bootstrap системы**:
```
pnpm run boot
```
5. **Запуск парсера** (после boot; при первом запуске нужен `START_BLOCK=2` в `.env` для полного replay, потом вернуть `START_BLOCK=1`):
```
pnpm --filter @coopenomics/parser run dev
```
6. **Запуск controller и desktop**:
```
pnpm --filter @coopenomics/controller run dev
pnpm --filter @coopenomics/desktop run dev
```
6. **Запуск**: `pnpm run reboot`, затем `docker compose up -d --force-recreate coopback cooparser` (если .env менялись)
### Критические gotchas
- **Node.js v20** обязателен. pnpm **v9.x** (не v10).
- **`/etc/hosts`**: для Cloud-окружения нужны записи `127.0.0.1 mongo` и `127.0.0.1 monoredis` — boot запускается на хосте и обращается к MongoDB по имени контейнера (replica set инициализирован с `mongo:27017`).
- **`docker-compose.override.yaml`**: в Cloud нужен override с `postgres: image: postgres:16` — `postgres:latest` (v18+) не работает с текущей конфигурацией volumes.
- **`.env` файлы**: controller и parser запускаются в Docker — используют docker hostnames (`mongo`, `node`, `monoredis`, `postgres`). Boot запускается на хосте — использует `127.0.0.1` с хостовыми портами (postgres: 5532, mongo: 27017).
- **Полный перезапуск**: `pnpm run reboot` — всё в одну команду. После первого reboot нужно `docker compose up -d --force-recreate coopback cooparser` если .env менялись.
- **SHiP порт 8070** — конфиг ноды `state-history-endpoint = 0.0.0.0:8070`, НЕ 8080. В `.env` парсера: `SHIP=ws://127.0.0.1:8070`.
- **CHAIN_ID** должен совпадать во всех `.env` файлах. Локальный chain_id: `cae86058a6d8698833afb474ab8a5ad8599c6cf54f9ebcf275dbac7055c16fe1`. В `.env-example` desktop стоял неправильный — исправлен.
- **postgres:latest (v18+)** не работает с текущей конфигурацией volume — используется `postgres:16`.
- **WeasyPrint** — системная зависимость для генерации PDF документов. Нужен в PATH: `pip install WeasyPrint==67`.
- **SSR-режим desktop в dev** — расширения (extensions) не рендерятся в SSR dev-сервере из-за проблемы гидратации Pinia: Vue-компоненты из маршрутов расширений сериализуются в `__INITIAL_STATE__` как plain-объекты `{__name, __file}` без render/setup функций. При гидратации клиент использует эти сломанные компоненты. Production-сборка (`quasar build --mode ssr`) работает корректно. **Для dev используйте SPA-режим**: `quasar dev` (без `--mode ssr`). Корневое решение: вынести `routes` из Pinia-стейта desktop-store, чтобы они не сериализовались при SSR.
- **Парсер и START_BLOCK**: при `START_BLOCK=1` на чистой БД парсер стартует с HEAD и вызывает `initializeFromBlockchain()` (загружает только кооператив и шаблоны, НЕ аккаунты). Для полного replay данных boot установите `START_BLOCK=2`, запустите, потом верните `START_BLOCK=1`.
- **boot/wallet-data и boot/blockchain-data** — создаются Docker от root, может потребоваться `sudo chown`.
- **Reboot-скрипты** (`components/boot/scripts/reboot.sh` и др.) ссылаются на docker-compose сервисы `cooparser` и `coopback`.
- **Тестовые учётные данные** (после boot): email `ivanov@example.com`, ключ `5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3`, пользователь `ant` (председатель).
- **SHiP порт 8070** — `state-history-endpoint = 0.0.0.0:8070` в config.ini. Парсер: `SHIP=ws://node:8070`.
- **Парсер START_BLOCK**: при `START_BLOCK=1` на чистой БД стартует с HEAD и делает частичную инициализацию. Для полного replay: временно `START_BLOCK=2`, после первого запуска вернуть `1`.
- **SSR desktop в dev** — расширения не рендерятся из-за Pinia SSR-сериализации компонентов. Dev — SPA (`quasar dev`), production build SSR работает.
- **Тестовые учётные данные**: email `ivanov@example.com`, ключ — дефолтный EOSIO dev key (см. `components/boot/.env-example`), пользователь `ant` (председатель).
- **Docker hostnames**: без `network_mode: host` — контейнеры обращаются друг к другу по именам контейнеров из docker-compose.
- **Установка пакетов**: только через фильтр — `pnpm add <pkg> --filter <component>`.