Развёртывание проекта Astro с использованием Dokploy и Nixpacks с оптимизацией кэша для ускорения сборки

1. Конфигурация Dokploy

Dokploy — это платформа развёртывания с открытым исходным кодом, которую можно разместить самостоятельно. Она разработана как бесплатная альтернатива Heroku, Vercel и Netlify и основана на Docker и Traefik.

1. Создайте новый проект и подключите репозиторий GitHub

2. Установите переменные окружения

NIXPACKS_NODE_VERSION=22
NIXPACKS_PNPM_STORE_PATH=/root/.local/share/pnpm/store/v3
NIXPACKS_INSTALL_CACHE_DIRS=/app/node_modules
NIXPACKS_BUILD_CACHE_DIRS=/app/node_modules/.cache,/app/astro_cache

3. Отключите очистку кэша

Сервис проекта → Clean Cache: отключено
Веб-сервер → Daily Docker Cleanup: отключено

2. Сборочный движок Nixpacks

Nixpacks — это инструмент с открытым исходным кодом от Railway, который превращает исходный код в стандартные Docker-образы. Dokploy использует Nixpacks в качестве сборочного движка по умолчанию. Конфигурация возможна через файл nixpacks.toml или nixpacks.json.

Создайте файл nixpacks.toml в корневом каталоге проекта и укажите директории для кэширования.

Приоритет конфигурации (от низкого к высокому):

Логика по умолчанию от провайдера
nixpacks.toml
Переменные окружения
Параметры CLI

Переменная	Описание
`NIXPACKS_INSTALL_CMD`	Пользовательская команда установки
`NIXPACKS_BUILD_CMD`	Пользовательская команда сборки
`NIXPACKS_START_CMD`	Пользовательская команда запуска
`NIXPACKS_PKGS`	Дополнительные пакеты Nix
`NIXPACKS_APT_PKGS`	Дополнительные пакеты Apt
`NIXPACKS_INSTALL_CACHE_DIRS`	Директории кэша на этапе установки
`NIXPACKS_BUILD_CACHE_DIRS`	Директории кэша на этапе сборки
`NIXPACKS_NO_CACHE`	Отключение кэширования (не рекомендуется)
`NIXPACKS_CONFIG_FILE`	Указание файла конфигурации
`NIXPACKS_DEBIAN`	Использование базового образа Debian

3. Конфигурация проекта Astro

Astro — это современный веб-фреймворк, ориентированный на контентные сайты: блоги, лендинги и e-commerce. Большое количество изображений и ресурсов может замедлить сборку. Включив кэш, вы значительно ускорите процесс.

1. Укажите директорию для кэша сборки

В файле astro.config.mjs укажите директорию, где будут сохраняться кэш-файлы. Путь может быть относительным или абсолютным.

// astro.config.mjs
export default defineConfig({
  cacheDir: './astro_cache',
});

2. Файл конфигурации кэша Nixpacks

Создайте файл nixpacks.toml в корне проекта Astro, задав директории кэша и команды сборки.

# Использовать конкретные версии Node.js и pnpm
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# Установка зависимостей с использованием кэша pnpm
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Сборка проекта и кэширование node_modules/.cache и astro_cache
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# Команда запуска (заглушка, предполагается использование NGINX)
[start]
cmd = "echo 'Сборка завершена. Обслуживайте директорию dist с помощью NGINX.'"

4. Оптимизация контекста сборки Docker

Добавьте файл .dockerignore в корневую директорию проекта:

node_modules
astro_cache
dist
*.log
.DS_Store
.vscode
.env*

5. Развёртывание и проверка

После автоматического развёртывания на Dokploy проверьте журналы сборки. Убедитесь, что используются кэш-директории:

1. Команда сборки монтирует кэш-директории

RUN --mount=type=cache,id=xxxx-node_modules/cache,target=/app/node_modules/.cache \
    --mount=type=cache,id=xxxx-astro_cache,target=/app/astro_cache \
    pnpm run build

2. Повторное использование кэш-файлов в Astro (например, для оптимизации изображений)

▶ /_astro/202409272055577_Z2smeTW.avif (reused cache entry)
▶ /_astro/202409272055575_Z2wPyJN.avif (reused cache entry)
▶ /_astro/202409272055577_1IgP6g.avif (reused cache entry)

✅ Если вы видите --mount=type=cache и reused cache entry, кэш работает корректно и сборка ускорена.

🎉 Во вкладке Deployments в Dokploy вы увидите, что время сборки сократилось с 31 минуты до 3 минут — экономия времени и трафика.

6. Важно помнить

Убедитесь, что значения cacheDir (Astro) и cacheDirectories (Nixpacks) совпадают
Для каждой стадии сборки указывайте директории кэша явно
nixpacks.toml поддерживает "..." для объединения с переменными окружения
По умолчанию node_modules/.astro не кэшируется — добавьте его вручную в astro_cache