Playground

Playground — це живе, запущене середовище розробки. Це екземпляр Playspec, розгорнутий на Playroom — ваш код працює на реальній інфраструктурі, доступний за унікальними HTTPS URL-адресами.

Огляд

Коли ви створюєте Playground, платформа:

1. Клонує необхідні Git-гілки на віддалений хост
2. Збирає необхідні Docker-образи
3. Генерує фінальну конфігурацію Docker Compose
4. Запускає всі контейнери через docker compose up

За секунди кожен відкритий сервіс стає доступним за своїм субдоменом з автоматичним HTTPS.

Життєвий цикл

Playground проходить через такі статуси:

pending → in_progress → running
                      ↘ error → (retry) → pending
         running → has_changes → (auto-resolve) → running
         running → completed (тільки режим job)

Статус	Опис
pending	В черзі на створення
in_progress	Зараз створюється (клонування, збірка, запуск)
running	Всі контейнери запущені та працюють
error	Створення або операція не вдалася (можна повторити)
has_changes	Виявлено нові коміти, що потребують уваги
completed	Playground у режимі job завершив виконання

Етапи створення

Під час створення платформа повідомляє про прогрес через ці етапи:

1. Запуск Traefik — Переконується, що реверс-проксі працює
2. Клонування репозиторіїв — Клонує Git-гілки на віддалений хост
3. Збірка образів — Збирає Docker-образи для сервісів у Production-режимі
4. Завантаження образів — Завантажує готові образи для статичних сервісів
5. Генерація Compose — Створює фінальну конфігурацію Docker Compose
6. Запуск контейнерів — Виконує docker compose up

Якщо будь-який етап не вдається, повідомлення про помилку та мітка етапу зберігаються для налагодження.

Термін дії (TTL)

Кожен Playground має час життя (TTL):

Налаштування	За замовчуванням
Стандартний Playground	8 годин
Playground у режимі job	1 година
Без терміну дії	Встановлюється при створенні — TTL вимкнений

Коли Playground закінчується, фоновий процес Playguard очищує його контейнери та ресурси.

Ви можете продовжити термін дії у будь-який момент — продовження додає стандартний TTL до поточного часу закінчення (або до поточного часу, якщо вже закінчився).

HTTP Basic Auth

Кожен Playground захищений HTTP Basic Auth для внутрішніх сервісів:

Поле	Значення
Імʼя користувача	playground
Пароль	Автоматично згенерований (видимий у детальному перегляді Playground)

Пароль генерується при створенні, шифрується при зберіганні та може бути перегенерований у будь-який момент.

Compose Project Name

Кожен Playground ізольований через унікальне імʼя Docker Compose проєкту у форматі:

pg-{id}-{slug}

Наприклад: pg-42-my-web-app. Це забезпечує повну ізоляцію контейнерів та мереж між Playground-ами на одному Playroom.

Конфігурація сервісів

При створенні Playground ви можете налаштувати кожен сервіс:

Вибір гілки

Для динамічних сервісів ви можете обрати, яку Git-гілку використовувати:

• Гілка за замовчуванням — Успадковує від Playzone
• Конкретна гілка — Оберіть будь-яку гілку з репозиторію
• Нова гілка — Вкажіть базову гілку та назву нової; платформа створить її на віддаленому хості

Перевизначення змінних середовища

Перевизначуйте змінні середовища на двох рівнях:

• Глобальні — Застосовуються до всіх сервісів
• Для конкретного сервісу — Застосовуються тільки до конкретного сервісу

Див. Змінні середовища для повного порядку злиття.

Перевизначення субдоменів

Перевизначуйте субдомен за замовчуванням для будь-якого відкритого сервісу. Це критично при запуску кількох Playground з одного Playspec на одному Playroom — кожному потрібні унікальні субдомени.

Production-режим

Окремі динамічні сервіси можна перемкнути в Production-режим для кожного Playground. Див. Production-режим для деталей.

Dirty-сервіси

Фоновий процес платформи (Playguard) моніторить робоче дерево Git кожного динамічного сервісу:

• Clean — Немає незакомічених змін. Playguard виконає git pull та автоматично синхронізує нові коміти.
• Dirty — Виявлено незакомічені зміни (ви редагуєте код в IDE). Playguard пропускає синхронізацію, щоб не перезаписати вашу роботу.

Статус dirty кожного сервісу видимий у детальному перегляді Playground.

Stateful Playground

Коли Playspec має увімкнену функцію Persist Volumes:

• Docker-томи зберігаються при пересозданні Playground (контейнери знищуються та створюються заново, але дані у томах зберігаються)
• Дозволяється лише один Playground на комбінацію Playspec+Playroom (для запобігання конфліктів томів)
• Томи мають префікс pv-{playspec_id}-{playroom_id} для ізоляції

Пересоздання

Ви можете пересоздати запущений Playground для:

• Застосування оновлених змінних середовища
• Примусового перезапуску контейнерів
• Виправлення дрейфу або помилок

Пересоздання знищує всі контейнери та перезапускає повний цикл конфігурації. Якщо Persist Volumes увімкнено, томи зберігаються за замовчуванням.

Режим Job

Режим job створює Playground для короткотривалих, одноразових задач (наприклад, міграції бази даних, тестові набори, пайплайни збірки):

• TTL за замовчуванням — 1 година (налаштовується)
• Платформа моніторить конкретні "watched" сервіси на завершення
• Коли всі watched-сервіси успішно завершуються, Playground переходить у статус completed
• Логи watched-сервісів кешуються для подальшого перегляду
• Завершені Playground не можна пересоздати або продовжити

Build Overrides

Для складних випадків ви можете надати build overrides у вигляді YAML. Вони обʼєднуються з конфігурацією збірки Docker Compose під час виконання, дозволяючи налаштувати аргументи збірки, контекст та інші параметри.

Логи

Кожен Playground надає потокове відтворення логів у реальному часі:

• Логи Playground — Події створення та життєвого циклу (потокова передача через WebSocket)
• Логи контейнерів — Живий вихід індивідуальних контейнерів

Логи доступні у веб-інтерфейсі та через API.

Debug

Сторінка Debug надає комплексний огляд внутрішнього стану Playground — корисна для діагностики проблем з контейнерами, мережею або конфігурацією.

Веб-термінал SSH

Майданчики містять повнофункціональний веб-термінал SSH безпосередньо в браузері. Ви можете безпечно підключатися до хостів Playroom та керувати контейнерами без локальних SSH-ключів.

Playground Agent

Playground може опціонально включати AI coding agent як sidecar. Коли увімкнено, агент розгортається поряд з вашими сервісами та доступний за своїм субдоменом (agent-{project}.{domain}). Агенти можуть бути налаштовані через вбудований майстер для використання різних LLM-провайдерів і кастомних MCP.

Playguard

Playguard — це фоновий процес узгодження платформи. Він працює постійно та керує:

• Git-синхронізація — Витягує нові коміти для чистих (не dirty) гілок
• Виявлення дрейфу — Виявляє зниклі контейнери, невідповідності статусів та дрейф версій образів
• Самовідновлення — Автоматично пересоздає Playground з дрейфом
• Термін дії — Очищує прострочені Playground
• Очищення сиріт — Видаляє Docker-ресурси, не привʼязані до активних Playground
• Тригери збірки — Ініціює збірки для Production-сервісів при виявленні нових комітів

Ліміти ресурсів

Ліміт	Значення
Максимум Playground на акаунт	1 000
Максимум Playground на Playroom	100