DinD HostingПосібник
ENУК
Огляд/Посібник/Збірка й розгортання
РОЗДІЛ 05

Довідник platform.yaml

Маніфест необов'язковий — голе дерево вихідного коду визначається за його файлами. Додайте platform.yaml, коли потрібно обрати середовище виконання, зафіксувати версію, підключити базу даних або змінити спосіб запуску застосунку.

Огляд файлу#

Покладіть platform.yaml у корінь вихідного коду. Усі ключі необов'язкові; невідомі ключі відхиляються, тому помилка в написанні призводить до збою розгортання, а не ігнорується мовчки.

platform.yaml — усі ключі
runtime: auto            # auto | static | node | python | php
version: "22"            # випуск середовища виконання: "22" | "22.12" | "22.12.1"  — завжди беріть у лапки
port: 3000               # зафіксувати порт, який слухає застосунок (типово: виділяється автоматично, доступний як $PORT)
site_dir: .              # лише static — папка, яку віддавати
spa: true                # лише static — для невідомих шляхів повертати /index.html
docroot: public          # лише php — веброкіт усередині вихідного коду
install_cmd: null        # перевизначити крок встановлення
build_cmd: null          # перевизначити крок збірки (node)
start_cmd: null          # перевизначити команду запуску
env: {KEY: value}        # статичні змінні середовища, зберігаються разом із вихідним кодом
s3: true                 # додати S3_* з обліковими даними вашого особистого бакета
databases: [main]        # підключити бази даних проєкту → DB_MAIN_HOST / PORT / USER / PASSWORD / NAME
resources: {cpu: "1.0", memory: 512m}
volumes: [{name: data, path: /app/data}]

Довідник ключів#

Ключ Тип · обмеження Типове значення Застосовується до
runtime auto, static, node, python, php auto — визначити за файлами усі
version рядок із 1–3 чисел через крапку, ≤ 24 символи залежить від середовища, див. версії усі
port ціле число 1–65535 виділяється з діапазону 10000–19999 у межах демона усі
site_dir відносний шлях, без .. . static
spa булеве значення false static
docroot відносний шлях, без .. public php
install_cmd рядок ≤ 2000 символів типове для середовища виконання усі
build_cmd рядок ≤ 2000 символів npm run build, якщо такий скрипт існує node
start_cmd рядок ≤ 2000 символів типове для середовища виконання node, python
env map; ключі [A-Za-z_][A-Za-z0-9_]*, значення перетворюються на рядки {} усі
s3 булеве значення false усі
databases список із ≤ 16 імен [a-z0-9][a-z0-9_-]{0,39} [] усі
resources.cpu число 0.01–64, записане рядком типове значення платформи усі
resources.memory цифри + b, k, m або g (512m) типове значення платформи усі
volumes ≤ 8 × {name, path}; name [a-z0-9][a-z0-9._-]*, path абсолютний, без .. немає усі

port і $PORT#

Платформа вибирає вільний порт у вашому демоні й передає його застосунку у змінній середовища PORT. Застосунок має слухати 0.0.0.0:$PORT. Задавайте port: лише тоді, коли потрібен фіксований номер; якщо цей порт у вашому демоні зайнятий, розгортання буде відхилено.

resources#

resources обмежує контейнер цього застосунку. Якщо ключ не вказано, діють типові обмеження платформи (їх задає адміністратор). Використовуйте його, щоб дати важкій збірці більше пам'яті — або щоб невеликий сайт залишався невеликим.

volumes#

yaml
volumes:
  - name: uploads
    path: /app/uploads

Том — це іменований том Docker у вашому демоні, змонтований за адресою path. Він зберігається між розгортаннями та перестворенням і входить до резервних копій проєкту. Усе, що поза томом, видаляється разом із контейнером.

env, s3 і databases#

env — найпростіше місце для несекретних сталих значень. Справжнім секретам місце в змінних проєкту. s3: true і databases: [name] змушують платформу додавати облікові дані у змінних S3_* та DB_<NAME>_* — див. Бази даних і Файлове сховище.

Спершу створіть базу даних

databases: [main] додає змінні лише для бази даних, яка вже існує в проєкті. Якщо її немає, розгортання все одно завершиться успішно, але змінних DB_MAIN_* не буде. Створіть базу даних, а потім розгорніть застосунок або перестворіть його.

Чотири середовища виконання#

static

базовий образ
nginx:<v>-alpine (1.27)
визначається за
index.html
віддає
site_dir через nginx
додатково
spa: true → перехід на /index.html; gzip увімкнено

node

базовий образ
node:<v>-alpine (24 LTS)
визначається за
package.json
встановлення
npm ci, а якщо не вдалося — npm install
запуск
npm run start, інакше server.js / index.js / dist/main.js

python

базовий образ
python:<v>-slim (3.12)
визначається за
requirements.txt, pyproject.toml
встановлення
pip install -r requirements.txt або pip install .
запуск
start_cmd, інакше uvicorn main:app / app.main:app

php

базовий образ
php:<v>-fpm-alpine (8.5) + nginx + supervisor
визначається за
composer.json, public/index.php
встановлення
composer install --no-dev, якщо є composer.json і немає vendor/
віддає
docroot через fpm на unix-сокеті

Приклади#

platform.yaml
runtime: static
site_dir: dist          # папка, яку створила ваша збірка і яку ви закомітили або заархівували
spa: true               # маршрутизація на клієнті: невідомі шляхи повертають index.html
platform.yaml
runtime: node
version: "24"
install_cmd: npm ci --include=dev   # збірка нижче потребує devDependencies (tsc)
databases: [main]
s3: true
resources: {memory: 512m}
package.json (excerpt)
{ "scripts": { "build": "tsc -p .", "start": "node dist/main.js" } }
platform.yaml
runtime: python
version: "3.12"
start_cmd: uvicorn app.main:app --host 0.0.0.0 --port $PORT
databases: [main]
requirements.txt
fastapi
uvicorn[standard]
psycopg[binary]
platform.yaml
runtime: php
version: "8.5"
docroot: public
volumes:
  - {name: storage, path: /var/www/app/storage}

NODE_ENV=production під час встановлення

Згенерований Dockerfile задає NODE_ENV=production перед npm ci, тому npm пропускає devDependencies. Якщо вони потрібні кроку збірки (TypeScript, Vite, якийсь CLI), або перенесіть ці пакети в dependencies, або задайте install_cmd: npm ci --include=dev.

Версії середовища виконання#

Проєкт обирає не лише середовище виконання, а й його версію. Платформа формує тег Docker із перевіреного рядка, тому node + "22" дає node:22-alpine.

Як обирається версія#

  1. platform.yamlversion: "22" — завжди має пріоритет
  2. Підказка у вихідному кодіточна або мажорна версія в файлі, який у вас уже є
  3. Типове значення платформиnode 24 · python 3.12 · php 8.5 · nginx 1.27

Файли, які платформа розпізнає як підказки (враховується лише проста точна або мажорна версія, за потреби з початковою v; діапазони на кшталт >=18 ігноруються, про що згадується в журналі збірки):

Середовище виконання Файли-підказки
node .nvmrc, .node-version, package.json → engines.node
python .python-version
php composer.json → require.php

Допустимі значення#

22, 22.12 або 22.12.1 — від одного до трьох чисел через крапку, не більше 24 символів, лише цифри. Беріть значення в лапки.

YAML перетворює 3.10 на 3.1

Значення version: 3.10 без лапок YAML читає як число 3.1, і нуль мовчки зникає. Тому платформа відхиляє дробові числа й підказує написати version: "3.10". Ціле число без лапок, як-от version: 22, допустиме. Булеві значення також відхиляються.

Свіжа чи зафіксована?#

Офіційні теги Docker змінюються — node:22-alpine це найновіша на сьогодні версія 22.x. Платформа обробляє це явно:

Що ви вказали Поведінка
"22" або "22.12" (коротка) Плаваюча. Базовий образ завантажується знову під час кожного розгортання, тож перебудова отримує виправлення безпеки. Якщо реєстр недоступний, збірка продовжується з локальної копії й записує попередження в журнал.
"22.12.1" (три частини) Зафіксована. Завантажується лише тоді, коли її ще немає в демоні, — перебудови відтворювані.

Кожна збірка записує в журнал # base image: <ref> (<digest>), а вкладка «Застосунок» показує використаний базовий образ.

Типові версії та їх зміна#

Середовище виконання Типова версія Примітка
node 24 найновіша LTS-версія Node.js на момент задання типового значення
python 3.12
php 8.5
static (nginx) 1.27

Адміністратори можуть перевизначити типову версію для всієї платформи через PLATFORM_DEFAULT_NODE_VERSION, …_PYTHON_VERSION, …_PHP_VERSION і …_STATIC_VERSION.

Нова типова версія переносить наявні застосунки

Застосунки, що не задають version, слідують за типовим значенням. Коли воно змінюється, вони переходять на нову версію під час наступної перебудови — уже зібрані образи продовжують працювати до цього моменту. Фіксуйте version у всьому, що не має переходити на нову версію.