first commit

README.md

@@ -0,0 +1,103 @@
+# ADa Workshop
+
+Минимальный каталог сервисов для CTF Attack-Defense. Пользователь видит
+сервисы, фильтрует их, выбирает для игры и загружает ZIP-архив. Метаданные
+хранятся в PostgreSQL, а сам ZIP — в S3-совместимом хранилище Backblaze B2.
+
+## Что необходимо
+
+- Python 3.11 или новее;
+- запущенный PostgreSQL и созданная пустая база данных;
+- бакет Backblaze B2 и Application Key с правами **Read and Write**;
+- файлы проекта:
+
+```text
+Workshop/
+├── main.py           # Запуск FastAPI и отдача страницы
+├── routers.py        # API каталога, проверка ZIP и загрузка в B2
+├── database.py       # Модели и подключение PostgreSQL
+├── workshop.html     # Интерфейс мастерской
+├── requirements.txt  # Python-зависимости
+└── .evn              # Локальные настройки и секреты, в Git не добавлять
+```
+
+Папки `.venv/` и `backups/` для запуска не нужны: первая создаётся командами
+ниже, вторая содержит резервные копии разработки.
+
+## Настройка `.evn`
+
+Создай в папке `Workshop` файл именно с именем `.evn` и заполни его:
+
+```env
+DATABASE_URL=postgresql+psycopg://POSTGRES_USER:POSTGRES_PASSWORD@localhost:5432/WORKSHOP_DB
+
+S3_ENDPOINT_URL=https://s3.YOUR_REGION.backblazeb2.com
+S3_REGION=YOUR_REGION
+S3_BUCKET=YOUR_BUCKET_NAME
+S3_ACCESS_KEY=YOUR_B2_keyID
+S3_SECRET_KEY=YOUR_B2_applicationKey
+```
+
+Для Backblaze B2:
+
+- `S3_ACCESS_KEY` — поле **keyID** созданного Application Key;
+- `S3_SECRET_KEY` — поле **applicationKey**;
+- `S3_REGION` — регион из S3 Endpoint, например `eu-central-003`;
+- `S3_BUCKET` — имя бакета, например `workshop-ada`.
+
+Не публикуй `.evn`, `keyID` или `applicationKey`.
+
+## Запуск на Windows
+
+Открой PowerShell в папке проекта и выполни:
+
+```powershell
+cd C:\путь\к\Workshop
+py -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -r requirements.txt
+.\.venv\Scripts\python.exe -m uvicorn main:app --reload
+```
+
+Открой в браузере: http://127.0.0.1:8000
+
+## Запуск на macOS
+
+Открой Terminal в папке проекта и выполни:
+
+```bash
+cd /путь/к/Workshop
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+python -m uvicorn main:app --reload
+```
+
+Открой в браузере: http://127.0.0.1:8000
+
+Для остановки сервера в обоих случаях нажми `Ctrl+C`.
+
+## Формат загружаемого ZIP
+
+Архив должен содержать файлы в корне архива, без внешней папки `ada/`:
+
+```text
+ada.zip
+├── checker/
+│   └── checker.py
+└── service/
+    ├── docker-compose.yml
+    ├── Dockerfile.api
+    └── ...
+```
+
+Обязательны `checker/checker.py`, `service/docker-compose.yml` и
+`service/Dockerfile.api`. Максимальный размер ZIP — 5 МБ; все файлы должны
+лежать только внутри `checker/` или `service/`.
+
+## Если что-то не работает
+
+- `503 S3-хранилище недоступно` — проверь значения B2 в `.evn` и перезапусти
+  сервер.
+- `InvalidAccessKeyId` — в `S3_ACCESS_KEY` нужен `keyID`, а не имя ключа.
+- `422` при загрузке — проверь структуру ZIP и обязательные файлы.
+- Карточки сервисов не пропадают после очистки БД — обнови страницу браузера.