CMS YouWebsite · 2.0.0

Устройство установки

← Все руководства

Устанавливаете сайт — начните с INSTALL.md: одна команда sudo bash install.sh делает всё, что описано ниже. Этот файл — для тех, кто хочет понять, что и зачем она делает, или поставить сайт вручную.

В каталоге — шаблоны для Ubuntu, nginx и systemd. В них example.ru — домен сайта: установка подставляет настоящий сама, при ручной установке его заменяют командой sed (ниже).

Что делает установка

Последовательность (то же делает server/site_install.py):

  1. Проверить готовую сборку в dist/. В архиве она уже есть. Если вы меняете исходники, соберите сайт на своём компьютере перед отправкой на сервер.

  2. Установить команду выкладки и выложить сборку: install -m 755 server/site_release.py /usr/local/sbin/cms-youwebsite-release, затем sudo cms-youwebsite-release dist --no-service (при первой выкладке службы ещё нет). Команда кладёт сборку в /var/www/cms-youwebsite/current/.

  3. Разместить сервер в /opt/cms-youwebsite/.

  4. Создать защищённое хранилище /var/lib/cms-youwebsite/.

  5. Скопировать service.env.example в /etc/cms-youwebsite/service.env. Обязательных заготовок в нём нет: почту сайта задают в окнах установки (она хранится в /var/lib/cms-youwebsite/mail.json и главнее строк SMTP_*), секрет входа служба создаёт сама. Строки SMTP_* заполняют только при установке без окон. Если в файле остались значения REPLACE_WITH_…, служба перечислит их в журнале (journalctl -u <служба>), а с заготовкой или коротким ADMIN_SESSION_SECRET не запустится вовсе.

  6. Файл пользователей /var/lib/cms-youwebsite/editors.json создаёт служба в окнах установки или команда из пункта 7 (владелец www-data, права 600). Файл лежит в каталоге данных, потому что админ добавляет и удаляет пользователей прямо в консоли и служба его записывает. В резервные копии он не попадает. Пароли хранятся только в виде PBKDF2-хеша (образец файла — editors.example.json).

  7. Установить команды управления пользователями и окон установки: install -m 755 server/manage_editors.py /usr/local/sbin/cms-youwebsite-users, install -m 755 server/site_setup.py /usr/local/sbin/cms-youwebsite-setup. Владельца сайта (суперадмина) и почту проще задать в окнах установки: sudo cms-youwebsite-setup выдаёт одноразовую ссылку на сутки, дальше всё в браузере (подробно — INSTALL.md, шаг 3). Вариант в терминале — sudo cms-youwebsite-users: первый пользователь — суперадмин (команда сама предлагает это, если суперадмина ещё нет). Дальше пользователей приглашает админ в консоли («Пользователи»): человек получает письмо и сам задаёт пароль. Команда на сервере нужна для восстановления доступа: пункт 9 назначает суперадмина, если прежний недоступен (уволился, потерял почту). Команда и консоль работают с одним файлом и не мешают друг другу. Входы отключённого или изменённого пользователя завершаются сразу, перезапускать службу не нужно.

    Роли: автор пишет новые публикации и правит только свои; редактор — все публикации, проверяет авторов; админ — ещё код страниц, настройки, журнал, копии и пользователи (кроме админов); суперадмин — один, назначает админов, включает проверку публикаций авторов и может передать свои права другому админу (с подтверждением обеих сторон кодами на почту).

    У каждого редактора есть постоянный идентификатор (id), не зависящий от логина и почты. У материалов сервер сам отмечает, кто их создал и кто последним изменил; эти отметки видны в консоли. При удалении редактора материалы остаются на сайте, а сам он остаётся в файле в списке deleted_editors: в отметках и в журнале он показан как «(удалён)». Если позже зарегистрировать человека с тем же логином или почтой, это будет новая учётная запись, и чужие отметки или записи журнала к нему не перейдут.

    Подпись для читателей («Пресс-служба», «Иван Петров») задаётся в форме публикации свободным текстом и с учётными записями не связана.

  8. Установить unit-файлы systemd (службу сайта и таймер ночных копий cms-youwebsite-backup.timer), конфигурацию Nginx и проверить их перед запуском.

Резервные копии, восстановление и переезд на новый сервер — в BACKUP.md.

Передача сайта клиенту

Роли защищают консоль, но не сервер: у кого есть доступ к серверу (SSH, root), у того есть доступ ко всем данным и к файлу пользователей. Поэтому после запуска:

  1. Суперадмином должен быть представитель клиента, а не разработчик. Если сайт запускали вы, передайте права в консоли («Пользователи» → «Передать права суперадмина») и удалите свою учётную запись.
  2. Доступ к серверу и к панели хостинга оформите на клиента: смена паролей, новый владелец ключей SSH.
  3. Удалите свои ключи из ~/.ssh/authorized_keys на сервере и из панели хостинга, если работа по поддержке не предусмотрена договором.
  4. Покажите клиенту «Шапку и меню» и «Подвал» в консоли: свой логотип, свои контакты; подпись «Сайт на CMS YouWebsite» со знаком он вправе убрать сам (галочка в «Подвале»).
  5. Передайте клиенту файл настроек (/etc/cms-youwebsite/service.env) и команды на сервере: сменить почту сайта — sudo cms-youwebsite-setup --mail, восстановить доступ — sudo cms-youwebsite-users, пункт 9.

Nginx и сертификат HTTPS

Файлы из deploy/nginx/ раскладываются так:

Файл в репозитории Куда на сервере
limits.conf /etc/nginx/conf.d/cms-youwebsite-limits.conf
security-headers.conf /etc/nginx/snippets/cms-youwebsite-security-headers.conf
tls.conf /etc/nginx/snippets/cms-youwebsite-tls.conf
acme-challenge.conf /etc/nginx/snippets/cms-youwebsite-acme-challenge.conf
site.conf /etc/nginx/sites-available/cms-youwebsite.conf (+ ссылка в sites-enabled)
first-certificate.conf только на время выпуска первого сертификата

Сертификат Let's Encrypt выпускается и продлевается в режиме --webroot: certbot кладёт проверочный файл в /var/www/letsencrypt, а nginx отдаёт его по адресу /.well-known/acme-challenge/… и по HTTP, и по HTTPS. Плагин certbot для nginx не нужен и конфигурацию не меняет.

Первый сертификат. Основной site.conf не запустится, пока файлов сертификата ещё нет, поэтому сначала включается временный файл:

sudo mkdir -p /var/www/letsencrypt
sudo cp deploy/nginx/first-certificate.conf /etc/nginx/sites-enabled/cms-youwebsite-first.conf
sudo nginx -t && sudo systemctl reload nginx
sudo certbot certonly --webroot -w /var/www/letsencrypt \
  -d example.ru -d www.example.ru \
  --deploy-hook "systemctl reload nginx"
sudo rm /etc/nginx/sites-enabled/cms-youwebsite-first.conf
sudo ln -s /etc/nginx/sites-available/cms-youwebsite.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Продление выполняет таймер certbot (systemctl list-timers certbot.timer) сам, по тем же настройкам; после продления nginx перечитывает сертификат (--deploy-hook). Проверить, что продление пройдёт, можно в любой момент:

sudo certbot renew --dry-run

Если сертификат раньше выпускался через certbot --nginx, переведите его на webroot один раз той же командой certbot certonly --webroot …, что и выше.

Кэш в браузере

Что Правило в site.conf Почему
Страницы сайта и публикаций no-cache Браузер каждый раз спрашивает, не изменилась ли страница (ответ 304 почти ничего не стоит). После выкладки новой версии старые страницы не ссылаются на удалённые файлы.
/build/ — скрипты и стили сборки год, immutable В имени отпечаток содержимого: новая версия — новое имя файла.
Картинки, значки, шрифты из public/ сутки Имя не меняется: заменённый логотип посетители увидят не позже чем через день.
Фото и документы публикаций сутки См. «Отдача файлов и корзина».

Папку /build/ задаёт assetsDir в vite.config.ts. Не кладите в public/ папку с таким именем.

Поддомены и HSTS

Сайт отдаёт заголовок HSTS с includeSubDomains (security-headers.conf): браузер, побывавший на сайте, год открывает домен и все его поддомены только по HTTPS и не даёт обойти ошибку сертификата. CMS рассчитана на отдельный сайт: наши новые сайты на поддоменах разворачиваются заново и сразу получают сертификат. Риск — чужие сервисы клиента на поддоменах без HTTPS.

Проверка. Перед запуском (сборка с indexable: true напоминает об этом) и после подключения клиентом любого нового сервиса:

python3 server/check_subdomains.py                     # домен из site.json
python3 server/check_subdomains.py --extra intranet,video

Команда находит распространённые поддомены (mail, 1c, crm, old, test и др.), а также запись «*», и проверяет на каждом HTTPS так же, как браузер: сертификат, срок, имя. Поддомены с необычными именами добавьте через --extra (полный список — в DNS у регистратора). Код выхода 1, если проблемы есть.

Если нашёлся поддомен без рабочего HTTPS — по порядку, от лучшего:

  1. Поставить на поддомен сертификат. На нашем сервере — certbot certonly --webroot для этого имени, как в разделе выше. На хостинге или у подрядчика — включить бесплатный Let's Encrypt в панели (его дают почти все хостинги). Для почты хостинга часто проще пользоваться адресом самого хостинга (mail.хостинг.ru), а запись mail.домен-клиента убрать.
  2. Если сертификат поставить нельзя — убрать includeSubDomains из security-headers.conf и перезагрузить nginx. Это не ослабляет защиту сайта:
    • сам сайт и www по-прежнему только по HTTPS (у каждого свой заголовок);
    • cookie входа в консоль называется __Host-…: такой cookie браузер не даёт выставить или подменить ни одному поддомену, даже без HTTPS;
    • у посетителей, которые уже получили правило с поддоменами, оно снимется при их следующем заходе на сайт: браузер обновляет правило при каждом визите.
  3. Чего не делать: не отключать HSTS целиком и не ставить max-age=0 — это открывает сам сайт для подмены при первом заходе по HTTP; не размещать консоль и API на поддомене без HTTPS.

Клиент видит напоминание в консоли («Настройки» → «Подключаете сервис на адресе вида „что-то.ваш-домен“?»): прежде чем подключать что-то на поддомене, он должен сообщить администратору.

Фото и метаданные

При загрузке фото (JPG, PNG, WebP) служба удаляет из файла метаданные: EXIF с GPS-координатами, моделью камеры и датой съёмки, миниатюры, XMP, IPTC, сведения о происхождении (C2PA), комментарии и всё, что дописано после изображения. Фото не пережимается: качество и пиксели те же. Из EXIF остаётся только пометка поворота, иначе фото с телефона легли бы на бок. Редактор видит в консоли, какие сведения были удалены.

Фото, загруженные до этой версии, очищаются командой. Сначала пробный запуск — он только покажет, что найдено:

sudo -u www-data python3 /opt/cms-youwebsite/strip_metadata.py
sudo -u www-data python3 /opt/cms-youwebsite/strip_metadata.py --apply

Имена и адреса файлов не меняются; в журнале сайта появится запись «очистка метаданных у загруженных фото».

Отдача файлов и корзина

Фото и документы nginx отдаёт сам, прямо из /var/lib/cms-youwebsite/uploads/ (правило location ~ "^/api/content/media/…" в nginx/site.conf). Так PDF открываются и листаются частями, а служба сайта не тратит время на большие файлы. Отдаются только имена вида <uuid>.<расширение>, всё остальное отвечает 404. Служба создаёт файлы с правами 600 от www-data, поэтому рабочие процессы nginx тоже должны работать от www-data (в Ubuntu так по умолчанию). Браузер хранит файл не дольше суток без перепроверки.

Когда публикацию удаляют, из неё убирают фото или PDF, а документ заменяют или удаляют, файлы, на которые больше ничего не ссылается, переносятся в uploads/.trash/<дата>/ и сразу перестают открываться по ссылке. Через CONTENT_TRASH_DAYS дней (по умолчанию 30) папка дня удаляется окончательно. До этого файл можно вернуть, переложив его обратно в uploads/.

Файлы, на которые никогда не ссылалась ни одна публикация (фото загрузили, но публикацию не сохранили), находит команда. Сначала пробный запуск — он только покажет список и содержимое корзины:

sudo -u www-data python3 /opt/cms-youwebsite/cleanup_uploads.py
sudo -u www-data python3 /opt/cms-youwebsite/cleanup_uploads.py --apply

С --apply найденные файлы уходят в корзину (не удаляются сразу), а просроченные дни корзины удаляются. Файлы моложе суток команда не трогает.

Страницы публикаций

Служба пишет готовые страницы в /var/lib/cms-youwebsite/public/ (SITE_PAGES_DIR), а шаблон берёт из собранного сайта /var/www/cms-youwebsite/current/news/index.html (SITE_TEMPLATE_DIR). Nginx отдаёт оттуда /news/ и /sitemap.xml. Каталог с кодом сайта службе только для чтения.

Выкладка новой версии сайта

Новую версию сайта выкладывайте одной командой, а не копированием файлов:

sudo cms-youwebsite-release dist

Обновление целиком (программа и сайт из нового архива) делает sudo bash install.sh — он вызывает эту же команду. Отдельно она нужна разработчику, который выкладывает только новую сборку сайта.

Готовая сборка из архива сделана с адресом-заготовкой https://example.ru. Настоящие адрес, название и разрешение индексации лежат на сервере в /etc/cms-youwebsite/site.json (их записывает установка): команда подставляет их в копию сборки — в canonical, заголовки страниц, метатег robots, robots.txt и site.json — и выкладывает уже её. Сборку со своим адресом (src/content/site.ts) команда выкладывает как есть.

Команда:

  1. проверяет, что сборка целая. Если чего-то не хватает, сайт не трогает и пишет, чего именно;
  2. копирует новую версию: сначала стили и скрипты, страницы — последними;
  3. просит службу пересобрать страницы (systemctl reload). Если в site.json сменились адрес или название сайта, служба перезапускается: их она читает только при запуске. Входы редакторов сохраняются в обоих случаях (если сменился адрес — войти нужно по новому адресу);
  4. ждёт, пока страницы соберутся, и пишет «Готово» или причину ошибки;
  5. хранит стили и скрипты (/build/) трёх последних версий, остальные удаляет.

Зачем так. Служба пишет свои страницы в public/: публикации, страницы с правками кода, а если админ менял «Шапку и меню» или «Подвал» — все страницы и 404.html. В них ссылки на стили той версии, по которой они собраны. Если просто скопировать новую сборку и удалить старые стили, эти страницы откроются без оформления, пока служба их не пересоберёт. Команда делает всё по порядку и сама: перезапускать службу вручную не нужно.

Пути команда берёт из /etc/cms-youwebsite/service.env (SITE_TEMPLATE_DIR, SITE_PAGES_DIR, CMS_YOUWEBSITE_SERVICE, по умолчанию cms-youwebsite). История выкладок — /var/www/cms-youwebsite/releases.json.

Если обновился и сервер (/opt/cms-youwebsite/), после копирования его файлов перезапустите службу: sudo systemctl restart cms-youwebsite. При запуске она тоже пересобирает все страницы. Если страницы собрать не удалось, материалы всё равно сохраняются, редактор видит предупреждение, а причина пишется в журнал службы (journalctl -u <служба>).

Подробный порядок зависит от выбранного хостинга и домена. Рабочие секреты в этот каталог не добавляются.

Установка вручную, по командам

То же, что делает sudo bash install.sh, по шагам. Команды проверены на настоящем сервере (Ubuntu 26.04, 1 ядро, 1 ГБ памяти).

1. Установить nginx (на сервере)

Все команды — на сервере, от root, в папке распакованного архива:

cd /root/cms-youwebsite-2.0.0
apt-get update && apt-get install -y nginx certbot

2. Выложить сайт

install -d /etc/cms-youwebsite
printf '{"url": "https://ВАШ-ДОМЕН", "name": "Название сайта", "indexable": false}\n' > /etc/cms-youwebsite/site.json
install -m 755 server/site_release.py /usr/local/sbin/cms-youwebsite-release
cms-youwebsite-release dist --no-service

Сайт лежит в /var/www/cms-youwebsite/current/. Адрес и название из /etc/cms-youwebsite/site.json команда подставляет в готовую сборку сама; если вы собрали сайт со своим адресом в src/content/site.ts, файл не нужен.

3. Установить службу сайта

mkdir -p /opt/cms-youwebsite
cp server/*.py /opt/cms-youwebsite/
rm -f /opt/cms-youwebsite/test_*.py
install -d -m 700 -o www-data -g www-data /var/lib/cms-youwebsite
install -m 755 server/manage_editors.py /usr/local/sbin/cms-youwebsite-users
install -m 755 server/site_setup.py /usr/local/sbin/cms-youwebsite-setup
install -m 640 -o root -g www-data deploy/service.env.example /etc/cms-youwebsite/service.env

/etc/cms-youwebsite/service.env — настройки службы. Править его не нужно: почту зададите в окнах установки, секрет входа служба создаст сама.

/var/lib/cms-youwebsite/ — данные сайта: тексты, фото, пользователи, копии. Доступ — только у службы (www-data).

Стартовые публикации. Служба сама их не берёт: без этого шага сайт запустится пустым. Если в server/seed/ лежат материалы, которые должны появиться на сайте (публикации клиента или демонстрационные записи), перенесите их — только при первой установке, пока каталог данных пуст, иначе команда затрёт рабочие публикации:

test ! -e /var/lib/cms-youwebsite/content.json && \
  install -m 600 -o www-data -g www-data server/seed/content.json /var/lib/cms-youwebsite/content.json && \
  cp -R server/seed/uploads /var/lib/cms-youwebsite/uploads && \
  chown -R www-data:www-data /var/lib/cms-youwebsite/uploads

Если сайт должен начаться без публикаций, пропустите этот шаг.

4. Сертификат HTTPS и nginx

cp deploy/nginx/limits.conf /etc/nginx/conf.d/cms-youwebsite-limits.conf
cp deploy/nginx/security-headers.conf /etc/nginx/snippets/cms-youwebsite-security-headers.conf
cp deploy/nginx/tls.conf /etc/nginx/snippets/cms-youwebsite-tls.conf
cp deploy/nginx/acme-challenge.conf /etc/nginx/snippets/cms-youwebsite-acme-challenge.conf
sed 's/example\.ru/ВАШ-ДОМЕН/g' deploy/nginx/site.conf > /etc/nginx/sites-available/cms-youwebsite.conf
sed 's/example\.ru/ВАШ-ДОМЕН/g' deploy/nginx/first-certificate.conf > /etc/nginx/sites-enabled/cms-youwebsite-first.conf
rm -f /etc/nginx/sites-enabled/default
mkdir -p /var/www/letsencrypt
nginx -t && systemctl reload nginx

Вместо ВАШ-ДОМЕН — ваш домен без https://, например my-school.ru.

Перед выпуском убедитесь, что оба имени уже указывают на сервер (иначе Let's Encrypt откажет, а после нескольких отказов временно заблокирует домен):

dig +short A ВАШ-ДОМЕН; dig +short A www.ВАШ-ДОМЕН   # оба — IP сервера

Выпустите сертификат и включите сайт:

certbot certonly --webroot -w /var/www/letsencrypt -d ВАШ-ДОМЕН -d www.ВАШ-ДОМЕН \
  --deploy-hook "systemctl reload nginx"
rm /etc/nginx/sites-enabled/cms-youwebsite-first.conf
ln -s /etc/nginx/sites-available/cms-youwebsite.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

При первом запуске certbot спросит почту и согласие с условиями Let's Encrypt. Если команду запускают без терминала (скриптом), добавьте --non-interactive --agree-tos и --email АДРЕС или --register-unsafely-without-email — писем об окончании срока Let's Encrypt всё равно больше не рассылает.

Сертификат продлевается сам (таймер certbot). Проверьте продление:

certbot renew --dry-run   # «all simulated renewals succeeded»

5. Запустить службу и ночные копии

cp deploy/cms-youwebsite.service deploy/cms-youwebsite-backup.service deploy/cms-youwebsite-backup.timer /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now cms-youwebsite.service cms-youwebsite-backup.timer
journalctl -u cms-youwebsite -n 20 --no-pager

В журнале должно быть «Страницы собраны…» и «listening on http://127.0.0.1:8791». Пока владельца нет, в журнале одна подсказка — «Владельца сайта ещё нет. Выполните на сервере sudo cms-youwebsite-setup…»: это следующий шаг.

Дальше — окна установки: cms-youwebsite-setup (INSTALL.md, шаг 3).

Своя сборка из исходников

На компьютере разработчика с Node.js 20+ выполните:

npm ci
npm run check && npm run test:api && npm run build

Отправьте папку на сервер вместе с dist/, исключив node_modules, и запустите из неё sudo bash install.sh. Адрес и название из исходников-заготовки установка подставит сама. Устройство исходников описано в CUSTOMIZATION.md.

Установщик без вопросов и настройка без браузера

sudo bash install.sh --domain my-site.ru --name "Название сайта" --www --demo --yes

--yes подтверждает согласие с условиями Let's Encrypt. По необходимости укажите --no-www, --no-demo или --email АДРЕС.

Чтобы настроить почту без браузера, выполните sudo cms-youwebsite-setup --mail или заполните SMTP_HOST, SMTP_PORT, SMTP_SECURITY, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_EMAIL в /etc/cms-youwebsite/service.env, убрав у них начальный #. CONTACT_EMAIL задаёт адрес для обращений посетителей. Если оставить его пустым, используется SMTP_FROM_EMAIL. После правки файла выполните sudo systemctl restart cms-youwebsite. Настройки в mail.json имеют приоритет над файлом окружения.

Когда почта настроена, выполните sudo cms-youwebsite-users и создайте владельца. Нужны логин, почта для кодов входа и пароль от 12 символов.