Установка и настройка Decap CMS (Git-Based)
Decap CMS монтируется в существующий проект добавлением двух файлов: admin/index.html и admin/config.yml. Весь административный интерфейс загружается на клиенте — серверной части нет. Git-репозиторий выступает базой данных, коммиты — транзакциями.
Добавление в существующий проект
Для любого статического генератора или Next.js-проекта папку admin кладём в директорию статических файлов:
# Next.js
public/admin/index.html
public/admin/config.yml
# Astro
public/admin/index.html
public/admin/config.yml
# Hugo
static/admin/index.html
static/admin/config.yml
# Eleventy
_site не трогаем, исходники в корне:
admin/index.html → копируется passthrough
admin/config.yml → копируется passthrough
Для Eleventy нужно явно прописать passthrough:
// .eleventy.js
module.exports = function(eleventyConfig) {
eleventyConfig.addPassthroughCopy('admin')
}
index.html
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="robots" content="noindex" />
<title>Управление контентом</title>
</head>
<body>
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
</body>
</html>
Версию лучше зафиксировать — не ^3.0.0, а конкретную 3.1.2, чтобы не получить сюрприз при обновлении CDN.
Бэкенды аутентификации
GitHub + Netlify Identity — самый простой вариант, если хостинг на Netlify:
backend:
name: git-gateway
branch: main
publish_mode: editorial_workflow
В настройках сайта на Netlify включаем Identity и Git Gateway. Редакторы регистрируются через email — репозиторий им видеть необязательно.
GitHub OAuth без Netlify — для хостинга на Vercel, VPS, GitHub Pages:
backend:
name: github
repo: myorg/my-site
branch: main
base_url: https://cms-oauth.mysite.com
OAuth-прокси — это маленький сервер, который принимает код от GitHub и возвращает токен. Готовая реализация на Node.js:
git clone https://github.com/vencax/netlify-cms-github-oauth-provider
cd netlify-cms-github-oauth-provider
cp .env.example .env
# Заполняем GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, REDIRECT_URL
npm install
node index.js
Деплоим на Railway или как Docker-контейнер. Занимает 20–30 минут.
GitLab — аналогичная схема:
backend:
name: gitlab
repo: myorg/my-site
branch: main
auth_type: pkce
PKCE-режим позволяет авторизоваться напрямую через GitLab OAuth без прокси-сервера.
Editorial Workflow
Включаем черновики и процесс согласования:
publish_mode: editorial_workflow
После включения в CMS появляется Kanban-доска: Draft → In Review → Ready. Каждый черновик создаёт отдельную ветку, при публикации — мёрдж в main. Это превращает git-историю в историю редакционных решений.
Медиафайлы
# Локальные медиафайлы в репозитории
media_folder: public/images/uploads
public_folder: /images/uploads
# Или Cloudinary
media_library:
name: cloudinary
config:
cloud_name: my-cloud
api_key: "123456789"
Для Cloudinary нужно установить:
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
<script src="https://unpkg.com/netlify-cms-media-library-cloudinary"></script>
Локализация интерфейса
locale: ru
Это устанавливает язык UI. Для русского языка перевод встроен в Decap CMS начиная с версии 2.10.
Проверка работы локально
Decap CMS поддерживает локальный бэкенд — изменения пишутся в файловую систему без коммитов:
# Только для разработки, не коммитить в main
backend:
name: proxy
proxy_url: http://localhost:8081/api/v1
npx decap-server
# Запускает прокси на порту 8081
Теперь http://localhost:3000/admin работает без GitHub-аутентификации.
Сроки
Базовая установка с 2–3 коллекциями и GitHub OAuth: 4–6 часов. Полная настройка с Editorial Workflow, Cloudinary, локализацией и тестированием: 1–2 дня.