Установка Monica Personal CRM на Debian 12

О чём эта инструкция

Monica — открытое приложение Personal CRM для управления контактами и отношениями с близкими. В отличие от бизнес-ориентированных CRM, Monica ориентирована на частных пользователей: семейные связи, друзья, заметки и напоминания.

Определение: CRM — система для управления взаимодействиями с людьми; здесь она используется для личных связей и заметок.

В этой статье вы найдёте подробную поэтапную инструкцию по установке Monica на Debian 12, а также дополнительные рекомендации по безопасности, резервному копированию, обновлению и устранению неполадок.

Что вы получите

• Полный план установки Monica на Debian 12.
• Команды и конфигурации для Nginx, PHP-FPM, MariaDB, Composer, Node.js, Yarn.
• Настройку SSL через Certbot и автоматическое обновление.
• Инструкции по бэкапу, откату и обновлению.

Быстрый обзор шагов

1. Подготовка сервера и пакетов.
2. Настройка брандмауэра UFW.
3. Установка Git, Node.js, Yarn, Nginx, PHP, Composer и MariaDB.
4. Клонирование Monica, установка зависимостей и сборка фронтенда.
5. Настройка Nginx и SSL через Certbot.
6. Настройка cron для фоновых задач.
7. Резервное копирование и обновления.

Требования к окружению

• Сервер с Debian 12 и минимум 1.5 ГБ RAM. Если памяти меньше — Yarn во время установки фронтенда вероятно упадёт. Рекомендуется 2+ ГБ для плавной работы.
• Нелокальный пользователь с sudo-привилегиями.
• Uncomplicated Firewall (UFW) включён и настроен.
• Полное доменное имя (FQDN), например monica.example.com, указывающее на сервер.
• SMTP-аккаунт для отправки почты (Amazon SES, Mailgun или любой другой SMTP).
• Система обновлена. Пример обновления:

$ sudo apt update && sudo apt upgrade

• Набор базовых пакетов. Пример установки:

$ sudo apt install curl wget nano software-properties-common dirmngr apt-transport-https ca-certificates lsb-release debian-archive-keyring gnupg2 ufw unzip -y

Важно: команды и пакеты в примерах сохраняйте без изменений. Если вы локализуете пути — корректируйте явно.

Важно: Перед продолжением убедитесь, что ваш FQDN указывает на IP сервера и что порты 80 и 443 доступны извне или через проброс.

Шаг 1 — Настройка брандмауэра

Разрешите HTTP и HTTPS трафик в UFW.

Проверка статуса:

$ sudo ufw status

Пример вывода:

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)

Разрешаем HTTP/HTTPS:

$ sudo ufw allow http
$ sudo ufw allow https

Проверяем ещё раз:

$ sudo ufw status
Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443/tcp                    ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443/tcp (v6)               ALLOW       Anywhere (v6)

Совет: если вы используете нестандартные порты или провайдер блокирует 80/443, настройте соответствующие правила перед установкой Certbot.

Шаг 2 — Установка Git

Git обычно уже установлен на Debian 12. Если нет, установите:

$ sudo apt install git -y

Проверка версии:

$ git --version
git version 2.39.2

Настройка имени и почты:

$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"

Шаг 3 — Установка Node.js

Monica требует Node.js для сборки фронтенда. Мы используем Node 18 LTS из-за совместимости с Yarn.

Импортируйте GPG-ключ Nodesource:

$ curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg

Создаём источник репозитория для Node 18:

$ NODE_MAJOR=18
$ echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

Обновляем индекс и ставим nodejs:

$ sudo apt update
$ sudo apt install nodejs -y

Проверка:

$ node --version
v18.18.2

Обновление npm:

$ sudo npm install -g npm@latest
$ npm --version
10.2.4

Примечание: если в будущем вы будете использовать Node 20+, убедитесь в совместимости с Yarn и пакетов фронтенда.

Шаг 4 — Установка Yarn

Yarn используется для управления фронтенд-зависимостями Monica.

Установка глобально через npm:

$ sudo npm install --global yarn

Проверка:

$ yarn --version
1.22.21

Примечание: при проблемах с правами используйте npx или локальную установку в проекте, но глобальная установка упрощает сборку.

Шаг 5 — Установка Nginx

Чтобы получить свежую версию Nginx, подключаем официальный репозиторий.

Импорт ключа:

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Добавляем stable-репозиторий:

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

Устанавливаем Nginx:

$ sudo apt update
$ sudo apt install nginx

Проверка версии (требуется sudo на Debian):

$ sudo nginx -v
nginx version: nginx/1.24.0

Запускаем сервис и проверяем статус:

$ sudo systemctl start nginx
$ sudo systemctl status nginx

Откройте IP сервера в браузере. Вы должны увидеть страницу по умолчанию Nginx.

Alt: Страница по умолчанию Nginx с текстом “Welcome to nginx” и базовой информацией.

Шаг 6 — Установка PHP и расширений

Debian 12 поставляется с PHP 8.2. Установим PHP-FPM и нужные расширения для Monica.

$ sudo apt install php php-bcmath php-cli php-curl php-common \
    php-fpm php-gd php-gmp php-intl php-json php-mbstring \
    php-mysql php-opcache php-redis php-xml php-zip

Если вы хотите управлять несколькими версиями PHP или всегда быть на актуальной версии, добавьте репозиторий Ondřej Sury:

$ sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
$ sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
$ sudo apt update
$ sudo apt upgrade

Установка конкретно PHP 8.2 и расширений:

$ sudo apt install php8.2 php8.2-bcmath php8.2-cli php8.2-curl php8.2-common \
    php8.2-fpm php8.2-gd php8.2-gmp php8.2-intl php8.2-mbstring \
    php8.2-mysql php8.2-opcache php8.2-redis php8.2-xml php8.2-zip

Проверка:

$ php --version
PHP 8.2.12 (cli) (built: Oct 27 2023 13:00:10) (NTS)

Шаг 7 — Настройка PHP-FPM

Откройте файл конфигурации php.ini для FPM:

$ sudo nano /etc/php/8.2/fpm/php.ini

Настройте лимиты загрузки файлов и память. По умолчанию установим 10M для загружаемых файлов:

$ sudo sed -i 's/upload_max_filesize = 2M/upload_max_filesize = 10M/' /etc/php/8.2/fpm/php.ini
$ sudo sed -i 's/post_max_size = 8M/post_max_size = 10M/' /etc/php/8.2/fpm/php.ini
$ sudo sed -i 's/memory_limit = 128M/memory_limit = 256M/' /etc/php/8.2/fpm/php.ini

Откройте пул PHP-FPM:

$ sudo nano /etc/php/8.2/fpm/pool.d/www.conf

Измените пользователя и группу на nginx, чтобы совпадало с владельцем веб-сервера:

user = nginx
group = nginx

Также установите владельца слушателя сокета:

listen.owner = nginx
listen.group = nginx

Сохраните файл и перезапустите PHP-FPM:

$ sudo systemctl restart php8.2-fpm

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

Шаг 8 — Установка Composer

Composer — менеджер зависимостей PHP и инструмент Laravel.

Скачиваем инсталлятор:

$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

Проверяем хэш инсталлятора (пример из исходного руководства):

$ php -r "if (hash_file('sha384', 'composer-setup.php') === 'e21205b207c3ff031906575712edab6f13eb0b361f2085f1f1237b7126d785e826a450292b6cfd1d64d92e6563bbde02') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

Устанавливаем Composer:

$ php composer-setup.php
$ php -r "unlink('composer-setup.php');"
$ sudo mv composer.phar /usr/local/bin/composer

Проверка:

$ composer --version
Composer version 2.6.5 2023-10-06 10:11:52

Шаг 9 — Установка MariaDB

MariaDB — замена MySQL. По умолчанию Debian 12 поставляет MariaDB 10.11.x. Для актуальной версии используйте официальный репозиторий MariaDB.

Импорт ключа и добавление репозитория:

$ sudo curl -o /usr/share/keyrings/mariadb-keyring.pgp 'https://mariadb.org/mariadb_release_signing_key.pgp'
$ echo "deb [signed-by=/usr/share/keyrings/mariadb-keyring.pgp] https://deb.mariadb.org/10.11/debian `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/mariadb-server.list
$ sudo apt update
$ sudo apt install mariadb-server -y

Проверка:

$ mysql --version

Пример вывода:

mysql  Ver 15.1 Distrib 10.11.6-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper

Проведите базовую настройку безопасности:

$ sudo mariadb-secure-installation

Интерактивный мастер задаст вопросы о смене аутентификации unix_socket и установке пароля root. В Debian стандартная конфигурация привязана к системным учётным записям; если вы не уверенны — отвечайте согласно подсказкам мастера (в исходной инструкции рекомендуют не менять unix_socket для системного root).

После завершения можно войти в консоль MariaDB:

$ sudo mysql
MariaDB [(none)]>

Шаг 10 — Настройка базы данных для Monica

Внутри MariaDB создайте базу и пользователя для Monica:

$ sudo mysql
MariaDB> CREATE DATABASE monica CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
MariaDB> CREATE USER 'monicauser'@'localhost' IDENTIFIED BY 'yourpassword';
MariaDB> GRANT ALL PRIVILEGES ON monica.* TO 'monicauser'@'localhost';
MariaDB> GRANT ALL ON *.* TO 'admin'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION;
MariaDB> FLUSH PRIVILEGES;
MariaDB> exit

Замените monica, monicauser и yourpassword на свои значения. Выберите сложный пароль.

Ключевые рекомендации по безопасности БД:

• Не используйте root-пароль ОС как пароль БД.
• Ограничьте доступ по сети — пользователь должен подключаться только с localhost, если нет кластерной архитектуры.

Шаг 11 — Клонирование Monica

Создаём корневую папку для веба и клонируем репозиторий.

$ sudo mkdir /var/www/html -p
$ sudo chown -R $USER:$USER /var/www/html
$ cd /var/www/html
$ git clone https://github.com/monicahq/monica.git
$ cd monica
$ git fetch

Выбираем нужную версию (замените тег на актуальный):

$ git checkout tags/v4.0.0

Примечание: вы окажетесь в detached HEAD состоянии — это нормально для развёртывания конкретной версии. Для разработки создавайте ветку.

Шаг 12 — Установка Monica и зависимостей

Перейдите в директорию проекта и создайте .env на базе примера:

$ cd /var/www/html/monica
$ cp .env.example .env

Откройте .env и внесите изменения:

• APP_ENV=production
• APP_URL=https://monica.example.com
• DB_DATABASE, DB_USERNAME, DB_PASSWORD — по вашей конфигурации
• MAIL_* — данные вашего SMTP-провайдера

Пример набора переменных в .env (часть):

APP_ENV=production
APP_URL=https://monica.example.com
DB_DATABASE=monicadb
DB_USERNAME=monicauser
DB_PASSWORD=YourPassword23!
MAIL_MAILER=smtp
MAIL_HOST=email-smtp.us-west-2.amazonaws.com
MAIL_PORT=587
MAIL_USERNAME=SESID
MAIL_PASSWORD=SESKey
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=[email protected]
MAIL_FROM_NAME="Monica CRM"
MAIL_ADMIN_ADDRESS=[email protected]

Установка PHP-зависимостей с Composer (без dev-зависимостей):

$ composer install --no-interaction --no-dev

Установка фронтенд-зависимостей и сборка ассетов:

$ yarn install
$ yarn run production

Генерация секретного ключа приложения:

$ php artisan key:generate

Запуск начальной настройки: миграции, сиды и создание пользователя:

$ php artisan setup:production [email protected] --password=yourpassword -v

Ожидаемый выход:

Monica v4.0.0 is set up, enjoy.
? Filling database
   INFO  Seeding database.

-----------------------------
|
| Welcome to Monica v4.0.0
|
-----------------------------
| You can now sign in to your account:
| username: [email protected]
| password: 
| URL:      https://monica.example.com
-----------------------------
Setup is done. Have fun.

Если вы используете другую версию Monica, названия команд и флаги могут немного отличаться — смотрите документацию проекта.

Шаг 13 — Установка SSL через Certbot

Рекомендуем установить Certbot через snapd для актуальности:

$ sudo apt install snapd
$ sudo snap install core && sudo snap refresh core
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot
$ certbot --version
certbot 2.7.4

Получение сертификата (пример для nginx):

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d monica.example.com

Сертификат появится в /etc/letsencrypt/live/monica.example.com.

Сделаем Diffie-Hellman параметры для повышения безопасности:

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Проверим планировщик обновления Certbot:

$ sudo systemctl list-timers

И выполним пробное обновление сертификатов:

$ sudo certbot renew --dry-run

Если ошибок нет — автоматическое обновление настроено.

Шаг 14 — Настройка Nginx для Monica

Убедимся, что nginx может читать файлы Monica и выставим права:

$ sudo chown -R nginx:nginx /var/www/html/monica
$ sudo chmod -R 775 /var/www/html/monica/storage

Внесём небольшое изменение в /etc/nginx/nginx.conf перед строкой include /etc/nginx/conf.d/*.conf;

server_names_hash_bucket_size  64;

Создаём конфигурацию /etc/nginx/conf.d/monica.conf и вставляем блок ниже (замените monica.example.com на ваш домен):

server {

    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name monica.example.com;
    root /var/www/html/monica/public;

    index index.php;
    client_max_body_size 10M;

    access_log  /var/log/nginx/monica.access.log;
    error_log   /var/log/nginx/monica.error.log;

    ssl_certificate      /etc/letsencrypt/live/monica.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/monica.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/monica.example.com/chain.pem;
    
    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;
    
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_index index.php;
        fastcgi_split_path_info ^(.+\.php)(.*)$;
        fastcgi_keep_conn on;
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}
# enforce HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name  monica.example.com;
    return 301   https://$host$request_uri;
}

Проверяем конфигурацию Nginx и перезапускаем сервис:

$ sudo nginx -t
$ sudo systemctl restart nginx

Шаг 15 — Доступ к Monica

Откройте https://monica.example.com в браузере. Вы увидите страницу входа.

Alt: Форма входа Monica CRM с полями Email и Password и кнопкой Login.

После входа вы попадёте на приветственный экран.

Alt: Главная панель Monica CRM с набором меню и списком контактов.

Шаг 16 — Настройка Cron для фоновых задач

Monica использует планировщик Laravel. Настройте cron, чтобы запускать задачи каждую минуту.

$ sudo crontab -u nginx -e

Если это первый запуск — выберите редактор (nano удобнее). Добавьте строку:

* * * * * php /var/www/html/monica/artisan schedule:run >> /dev/null 2>&1

Сохраните и выйдите. Теперь задачи будут выполняться регулярно.

Шаг 17 — Резервное копирование и обновление

Бэкап данных можно сделать через UI: Settings → Export data → Export to SQL или Export to Json. Файлы будут сохранены в storage/app/public/exports.

Пример вывода каталога экспорта:

$ ls /var/www/html/monica/storage/app/public/exports -al
total 84
drwxr-xr-x 2 nginx nginx  4096 Nov 22 09:47 .
drwxrwxr-x 4 nginx nginx  4096 Nov 22 09:47 ..
-rw-r--r-- 1 nginx nginx 53712 Nov 22 09:47 cvlK5RAl7VVLdYLplnSZ8SFGHHwDZy9cjRhtoOWB.json
-rw-r--r-- 1 nginx nginx 17050 Nov 22 09:47 dgZf5T0SnXeAuZ67HfaFLu2JosyUsByJcp2C8nlv.sql

Процедура обновления:

$ cd /var/www/html/monica
$ sudo chown -R $USER:$USER /var/www/html/monica
$ git fetch
$ git checkout tags/v5.0.0-beta.3
$ composer install --no-interaction --no-dev
$ yarn install
$ yarn run production
$ php artisan monica:update --force
$ sudo chown -R nginx:nginx /var/www/html/monica

При обновлении всегда делайте бэкап БД и файлов. Тестируйте обновление на стенде перед продакшеном.

Если нужно восстановить SQL в пустую базу:

$ php artisan migrate
$ sudo mysqlimport -u monicauser -p monica /var/www/html/monica/storage/app/public/exports/dgZf5T0SnXeAuZ67HfaFLu2JosyUsByJcp2C8nlv.sql

Вас попросят ввести пароль пользователя БД.

Дополнения и лучшие практики

Факт-бокс — ключевые числа

• Минимальная RAM: 1.5 ГБ (рекомендуется 2+ ГБ).
• Размер загрузки файлов по умолчанию: 10 МБ.
• Рекомендуемые версии: PHP 8.2, Node 18 LTS, MariaDB 10.11.x, Nginx 1.24.x.

Рекомендации по безопасности

• Используйте HTTPS и включите HSTS в конфигурации Nginx при уверенности в корректности сайта.
• Ограничьте доступ к директории /var/www/html/monica только для пользователя nginx.
• Регулярно обновляйте пакеты и мониторьте обновления безопасности.
• Ограничьте доступ к базе по сети; используйте бэкапы и шифрование резервных копий.

План отката и аварийный сценарий

1. Перед обновлением сделайте резервную копию SQL и каталога storage.
2. Если миграция пошла не так — откатите код в git на предыдущий тег: git checkout .
3. Восстановите SQL: mysql -u monicauser -p monica < backup.sql.
4. Верните права nginx: sudo chown -R nginx:nginx /var/www/html/monica.
5. Перезапустите сервисы: sudo systemctl restart php8.2-fpm nginx mariadb.

Проверка работоспособности после развёртывания

• Откройте https://вашдомен и проверьте страницу логина.
• Проверьте лог Nginx и PHP-FPM на ошибки: /var/log/nginx/monica.error.log, /var/log/nginx/monica.access.log.
• Убедитесь, что задания cron выполняются (проверьте журналы Laravel или создайте тестовую задачу).

Роль‑ориентированные чек-листы

Администратор сервера:

• Проверить наличие обновлений Debian и установить критические патчи.
• Настроить брандмауэр и мониторинг.
• Создать и проверить бэкапы.

DevOps:

• Настроить CI/CD или скрипты обновления.
• Проверить права на каталог, управление секретами (.env).
• Настроить мониторинг доступности и логирование.

Разработчик:

• Тестировать миграции на staging.
• Проверять совместимость пакетов Node/Yarn.
• Не коммитить .env в репозиторий.

Пользователь Monica:

• Настроить почту в профиле, проверить отправку писем.
• Сделать экспорт данных и сохранить копию.

Критерии приёмки

• Сайт доступен по HTTPS и валидному сертификату.
• Успешный вход в систему с созданной учётной записью.
• Отправка тестового письма через настроенный SMTP работает.
• Планировщик задач Laravel выполняется (cron каждые 1 минута).
• Выполнена резервная копия базы и файлов.

Частые проблемы и как их исправить

• Проблема: 502 Bad Gateway. Причина: PHP-FPM не запущен или mismatch сокета. Решение: sudo systemctl status php8.2-fpm; проверьте fastcgi_pass в конфиге Nginx.
• Проблема: Сертификат не получен. Причина: порт 80/443 закрыт или домен не резолвится. Решение: проверьте A‑запись и UFW.
• Проблема: Ошибки при yarn install на малой памяти. Решение: добавить swap файл или увеличить RAM.

Мини‑методология обновления

1. Бэкап БД и файлов.
2. Создать ветку и тестировать обновление на staging.
3. Обновить зависимости и собрать фронтенд.
4. Выполнить миграции и кеш‑очистки.
5. Мониторить логи 24–48 часов.

Глоссарий (1‑строчные определения)

• FQDN — полное доменное имя, например monica.example.com.
• PHP-FPM — FastCGI Process Manager для PHP.
• Composer — менеджер зависимостей PHP.
• Yarn — менеджер пакетов JavaScript.

Заключение

Вы развернули Monica Personal CRM на Debian 12. Система готова к использованию: вход по HTTPS, службы запущены, фоновые задачи настроены. Не забывайте о регулярных бэкапах, обновлениях и проверках логов.

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