ProjectDB — платформа для создания веб-приложений под задачи вашего бизнеса. На её основе можно построить небольшой веб-сервер, специализированный микросервис или полноценную информационную систему с сайтом, CRM, личными кабинетами и отчётностью.

Официальный сайт: projectdb.ru

This guide, including installation and first-launch instructions, is also available in English.

Возможности платформы

На ProjectDB можно создать сайт, CRM, личный кабинет или отдельный сервис. Начните с нужных вам функций и добавляйте новые по мере развития проекта.

• Общие данные сайта и внутренних систем. Сайт, CRM и личный кабинет могут работать с одной базой. Заявка с сайта сразу попадает в работу, её статус виден клиенту, а отчёты строятся по тем же данным.
• Настройка под свои процессы. Настраивайте формы, этапы работы и отчёты под задачи вашей команды. Готовые компоненты и настройки в базе данных позволяют менять приложение без пересборки его кода.
• Совместная работа в реальном времени. Изменения задач и карточек видны другим участникам: команда работает с актуальными данными.
• Гибкие права доступа. Определяйте, какие записи и поля доступны каждому пользователю, и отслеживайте действия в журнале.
• Несколько языков и доменов. Создавайте сайты и приложения для разных аудиторий, при необходимости объединяя их данные и правила доступа.
• Интеграции и автоматизация. Подключайте внешние API, базы данных, почту, файлы и очереди сообщений. Задания по расписанию помогают автоматизировать повторяющиеся операции.

ProjectDB использует подход low-code: многие функции задаются настройками, а программист добавляет бизнес-логику, SQL-запросы и нестандартные интеграции. Установка пакета подготавливает среду запуска. Чтобы запустить конкретное приложение, нужно подключить его базу данных и указать параметры запуска. Примеры использования представлены на официальном сайте.

Приложения работают в Linux и Windows. Их можно запускать в терминале, как службу Linux или через PM2. Серверный установщик подготавливает окружение и позволяет продолжить работу после прерывания. Код репозитория распространяется по лицензии MIT.

Выбор способа установки

| Ваше окружение | Способ установки | | --- | --- | | Новый сервер Debian или Ubuntu | Воспользуйтесь быстрой установкой, описанной ниже. | | Windows x64 | Скачайте готовый архив из релизов GitHub; порядок запуска описан в разделе о Windows. | | Окружение, которое вы настраиваете самостоятельно | Установите необходимые компоненты и пакет npm; см. раздел «Установка через npm». | | Устройство передачи данных | Воспользуйтесь отдельным руководством для Raspberry Pi. |

Быстрая установка на сервер

Перед началом

• Поддерживаемые системы: Debian 12, Debian 13, Ubuntu 22.04 и Ubuntu 24.04.
• Используйте чистую систему с минимальным набором пакетов и войдите под пользователем root. Установщик обновляет системные пакеты и меняет настройки сервера.
• Если планируете отключить IPv6, подключайтесь по IPv4 или используйте консоль сервера. Отключение IPv6 запрашивается перед установкой.
• SSH: уточните порт текущего подключения. Установщик разрешит его в межсетевом экране перед включением защиты.
• Веб-сервер: порты 80 (HTTP) и 443 (HTTPS) будут открыты для входящих подключений.
• PostgreSQL: доступ к порту 5780 зависит от выбранного режима: локальная сеть 192.168.0.0/16 (по умолчанию), любые IPv4-адреса 0.0.0.0/0 или только этот сервер 127.0.0.1. В последнем случае порт в межсетевом экране не открывается.

В состав серверной установки входят ProjectDB, Node.js 18, PHP 7.2 с необходимыми расширениями и вспомогательные инструменты. Установка Nginx и PostgreSQL 17 необязательна. Для загрузки пакетов требуется доступ в интернет.

Загрузка и запуск

Подключитесь к серверу, заменив your.server его IPv4-адресом. Если SSH использует другой порт, добавьте -p PORT:

ssh [email protected]

Загрузите установщик:

curl -fLO https://raw.githubusercontent.com/pavel-elblaus/projectdb/master/dist/pdb-install.sh

После успешной загрузки запустите его:

bash pdb-install.sh

Если при загрузке возникла ошибка curl: command not found: установите curl следующей командой, затем повторите загрузку и запуск:

apt-get update && apt-get install -y curl

Вопросы установщика

Перед началом выберите параметры установки. Нажмите Enter, чтобы принять значение в скобках, или введите своё. В вопросах [Y/n] и [y/N] ответ y означает согласие, а n — отказ; заглавная буква указывает значение по умолчанию. Вопросы и сообщения об ошибках выводятся на английском языке.

| Параметр | По умолчанию | Что выбрать | | --- | --- | --- | | Веб-сервер Nginx | Да | Оставьте включённым, чтобы установить и настроить Nginx на этом сервере. Откажитесь, если он не нужен. | | PostgreSQL 17 | Да | Оставьте включённым для локального сервера базы данных. Откажитесь, если будете подключаться к уже существующему серверу БД. | | Имя базы данных | projectdb | Запрашивается при выборе PostgreSQL. Будет создана база с этим именем; укажите его при настройке приложения. | | Доступ к PostgreSQL | Локальная сеть | Выберите только текущий сервер 127.0.0.1, локальную сеть 192.168.0.0/16 или любые IPv4-адреса 0.0.0.0/0. Межсетевой экран разрешит подключения к базе данных в соответствии с выбранным вариантом. Доступ с самого сервера сохраняется во всех случаях. | | Порт SSH | 22 | Укажите порт текущего подключения. Он будет добавлен в правила межсетевого экрана; порт самого SSH-сервера не изменится. | | Размер файла подкачки, % от RAM | 50 | Введите целое число от 0 до 100. Например, 50 соответствует половине объёма оперативной памяти. Значение 0 отключает управляемый установщиком /swapfile. | | Отключить IPv6 | Да | Вопрос появляется только при включённом IPv6. При отказе настройки IPv6 сохраняются. Если IPv6 работает некорректно, возможны проблемы с загрузкой зависимостей, обновлений и библиотек. |

Ход установки, логи и повторный запуск

• Наблюдение за установкой: нижняя строка показывает текущий этап, индикатор активности и время выполнения этапа. Завершённые этапы отмечаются Done, а выполненные при предыдущей попытке — Skipped.
• Лог установки: во время установки создаётся файл ~/.projectdb/log/projectdb-install.*.log. Точный путь выводится в начале. Лог доступен пользователю root и содержит сведения для разбора ошибок.
• Остановка и продолжение: нажмите Ctrl+C и дождитесь возвращения командной строки. Для продолжения запустите тот же установщик. Он восстановит ваши ответы, проверит прерванные операции с пакетами и попытается исправить их перед продолжением. Если ошибка повторяется, изучите лог и устраните указанную причину перед новой попыткой.

Одновременно может работать только один экземпляр установщика. После успешного завершения установки повторный запуск не вносит изменений в систему. Для обновления ProjectDB используйте команду из раздела об обновлениях ниже.

После установки

Сообщение 100% ProjectDB installation completed означает, что итоговые проверки установщика пройдены. В сводке указана общая продолжительность установки. Следующий шаг — настроить и запустить приложение.

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

| Параметр | Значение | | --- | --- | | Сервер базы данных | PostgreSQL 17 | | Адрес для локального подключения | 127.0.0.1 | | Адрес для удалённого подключения | IPv4-адрес вашего сервера, если разрешён внешний доступ | | Порт | 5780 | | База данных | Имя базы данных, указанное при установке | | Пользователь | postgres | | Пароль | Создаётся автоматически и выводится в итоговой сводке |

Пароль для локального подключения через командные инструменты PostgreSQL сохраняется в стандартном файле ~/.pgpass пользователя root. Доступ к файлу имеет только root. При настройке ProjectDB введите пароль базы данных в соответствующем вопросе.

Установка в Windows

Готовая сборка для Windows x64 доступна в релизах GitHub. Например, в релизе 17.8.0 опубликован архив ProjectDB 3.4.0 для Windows x64.

1. Скачайте ZIP-архив и распакуйте его целиком в удобный каталог, например C:\ProjectDB.
2. Запустите projectdb.exe. Программа запросит адрес сервера конфигурации, имя приложения и пароль доступа.
3. Введите данные вашего приложения, чтобы подключиться и начать работу.

Имя приложения можно передать при запуске из PowerShell, открытого в каталоге программы:

.\projectdb.exe PDB-SERVER

Среда Node.js включена в архив. При запуске из консоли можно передать только имя приложения. Этот параметр необязателен: если его не указать, программа запросит имя приложения. Если приложению требуется локальное подключение к базе, создайте файл db.PDB-SERVER.json или db.json самостоятельно по примеру подключения: в этой сборке нет опроса для их создания. PHP и LAME устанавливаются отдельно, если они нужны приложению.

Установка на Raspberry Pi

Для устройства LIMS-USB предусмотрен отдельный установщик. Устройство подключается к лабораторному прибору как USB-накопитель и принимает файлы с результатами измерений. Приложение на базе ProjectDB обрабатывает эти файлы и передаёт результаты в ЛИМС. Порядок подготовки устройства описан в руководстве LIMS-USB.

Установка через npm

Установка через npm подходит для Linux и Windows, если вы самостоятельно настраиваете программное окружение. Подготовьте:

• Node.js 18.x или новее, включая npm.
• PHP 7.2 с расширениями mbstring, dom, gd и zip.
• Данные для подключения к базе данных PostgreSQL.

Установите ProjectDB:

npm install projectdb -g

После установки станет доступна команда projectdb. Настройте сервер базы данных, веб-сервер и межсетевой экран в соответствии с задачами вашего приложения.

Преобразование аудио — опциональная возможность

Если приложение преобразует аудиофайлы, отдельно установите LAME. Этот компонент необязателен и не входит в серверную установку. Требования и инструкции для разных ОС доступны в репозитории node-lame.

В Debian или Ubuntu выполните под пользователем root:

apt-get install -y lame

Если приложение не использует преобразование аудио, пропустите этот шаг.

Первый запуск

Укажите рабочий каталог и имя приложения. В примерах используется /opt/pdb, но вы можете выбрать другой путь. ProjectDB создаст каталог, если его ещё нет.

projectdb start PDB-SERVER -w /opt/pdb

Замените PDB-SERVER именем приложения. Используйте латинские буквы, цифры, точки, подчёркивания и дефисы; первый символ должен быть буквой или цифрой. Для управления приложением используйте одно и то же имя приложения, учётную запись операционной системы и рабочий каталог.

Если конфигурация ещё не сохранена, ProjectDB предложит создать файл подключения к базе и запросит параметры. Писать JSON вручную не требуется. Проверьте ответы и подтвердите их, чтобы сохранить настройки и продолжить запуск.

Настройка подключения к базе данных

Подготовьте имя базы и параметры подключения. Если вы воспользовались быстрой установкой, возьмите пароль PostgreSQL из итоговой сводки установщика.

| Параметр | По умолчанию | Назначение | | --- | --- | --- | | Пользователь базы данных | postgres | Учётная запись для подключения к базе. | | Пароль | Пустое значение | Введите пароль этой учётной записи. Оставляйте пустым только для подключения, которое не требует пароля. | | Адрес сервера БД | 127.0.0.1 | Оставьте для базы на том же сервере или укажите адрес удалённого сервера. | | Порт БД | 5780 | Соответствует быстрой установке. Для существующего сервера укажите его настроенный порт. | | Имя базы данных | Обязательно | Имя базы, которую будет использовать приложение. | | Схема БД | api_pdb | Схема, используемая приложением. | | Минимум подключений на рабочий процесс | 1 | Минимальное число подключений к БД для каждого рабочего процесса. | | Максимум подключений на рабочий процесс | 10 | Максимальное число подключений к БД для каждого рабочего процесса. Не должно быть меньше минимума. | | Активные рабочие процессы | 1 | Количество рабочих процессов приложения. | | Использовать SSL | Нет | Включите, если подключение к базе требует SSL. |

Сначала ProjectDB предложит сохранить настройки в db.PDB-SERVER.json — отдельном файле этого приложения. При отказе будет предложен db.json, общий для приложений в том же рабочем каталоге. Сохранённые настройки используются при следующих запусках.

После подтверждения настроек приложение запустится в текущем терминале. Для остановки нажмите Ctrl+C. Если приложение должно работать после закрытия терминала, запустите его как службу или через PM2 — эти способы описаны ниже.

Работа приложения в фоновом режиме

| Режим | Для чего подходит | Поведение | | --- | --- | --- | | Текущий терминал | Первый запуск и диагностика | Работает до остановки или закрытия терминала. | | Служба systemd в Linux | Постоянная работа на сервере Linux | Работает в фоне и автоматически запускается после перезагрузки. | | PM2 | Управление приложениями через PM2 и, как опция, мониторинг PM2+ | Работает в фоне; в Linux ProjectDB настраивает автоматический запуск. |

Служба Linux

Выполняйте команды управления службой под пользователем root. Перейдите в рабочий каталог приложения или укажите его через --work-path. В примере используется /opt/pdb:

projectdb service-start PDB-SERVER --work-path /opt/pdb

Команда создаёт и запускает службу. Если служба уже существует, её настройки обновляются, после чего она перезапускается. При первом интерактивном запуске доступны те же вопросы о подключении к базе данных.

Перезапустить существующую службу:

projectdb service-restart PDB-SERVER

Остановить приложение, удалить его службу и отключить автоматический запуск:

projectdb service-stop PDB-SERVER

Настройки подключения к базе данных сохраняются.

Менеджер процессов PM2

Запускайте приложение из его рабочего каталога. В Linux используйте root, чтобы ProjectDB мог настроить автоматический запуск:

projectdb pm2-start PDB-SERVER

Повторное выполнение команды перезапускает то же приложение и обновляет настройки его запуска. В Windows автоматический запуск при необходимости нужно организовать отдельно.

Перезапустить приложение:

projectdb pm2-restart PDB-SERVER

Остановить и удалить это приложение из PM2:

projectdb pm2-stop PDB-SERVER

Другие приложения той же учётной записи PM2 продолжат работу. При удалении последнего приложения ProjectDB также останавливает PM2 и удаляет его автоматический запуск.

Чтобы остановить все приложения PM2 текущей учётной записи, не указывайте имя приложения:

projectdb pm2-stop

Переключение режимов запуска

Запуск приложения в другом режиме останавливает существующую службу или приложение PM2 с тем же именем приложения. Используйте ту же учётную запись операционной системы, имя приложения и рабочий каталог, чтобы команды обращались к одному приложению.

Временный запуск в терминале останавливает существующую службу, но сохраняет её автоматический запуск. Чтобы удалить его, используйте service-stop.

Мониторинг PM2+ как опция

Для подключения PM2 к панели мониторинга укажите её секретный и публичный ключи:

projectdb pm2-start PDB-SERVER --link SECRET_KEY,PUBLIC_KEY

Если подключение с такими ключами уже существует, оно используется повторно. При удалении последнего приложения из работающего PM2 подключение PM2+ отключается, а сохранённые ключи удаляются. Для повторного подключения снова передайте --link. Если PM2 к этому моменту уже остановлен, сохранённые параметры подключения не меняются.

Справка по настройкам

Рабочий каталог и локальные файлы

Служебные данные хранятся в папке .projectdb в домашней директории пользователя (~/.projectdb):

• log — логи;
• tmp — временные файлы;
• lib — кэш библиотек;
• install — состояние установки;
• backup — исходные конфигурации, сохранённые перед изменениями, включая Nginx и его каталог conf.d.

По умолчанию рабочим становится каталог, из которого выполнена команда. Чтобы выбрать другой, используйте --work-path с start, service-start или pm2-start. При следующих запусках указывайте тот же каталог.

Параметры подключения выбираются в следующем порядке:

1. db.<servername>.json — для приложения с указанным именем.
2. db.json — общий файл рабочего каталога.
3. Сохранённая удалённая конфигурация, если она есть.

Оба локальных файла подключения имеют одинаковый формат:

{
  "user": "postgres",
  "pass": "",
  "host": "127.0.0.1",
  "port": 5780,
  "db": "projectdb",
  "schema": "api_pdb",
  "min_connect": 1,
  "max_connect": 10,
  "channel": 1,
  "ssl": false
}

Замените projectdb и параметры подключения своими значениями. Если вы запускаете ProjectDB из скрипта без ввода ответов, заранее сохраните параметры подключения в одном из этих файлов.

Удалённая конфигурация

Через сервер конфигурации можно загрузить код конструктора ProjectDB в базу данных и при необходимости развернуть административную панель на собственном домене. Панель предоставляет веб-интерфейс для работы с конструктором: разработки, настройки и администрирования приложений.

Если у вас есть пароль доступа к серверу конфигурации ProjectDB, можно использовать его вместо создания локального файла подключения к базе:

projectdb start PDB-SERVER --host node.projectdb.pro --password PASSWORD

Здесь --password — пароль удалённой конфигурации, а не PostgreSQL. Параметр --host задаёт сервер конфигурации; по умолчанию используется node.projectdb.pro. Эти параметры также доступны для service-start и pm2-start.

Подключение к серверу конфигурации сохраняется для следующих запусков. Существующие локальные файлы настройки базы имеют приоритет над этими параметрами.

Обновление ProjectDB и библиотеки релиза

Обновление пакета ProjectDB

Установите последнюю опубликованную версию:

npm install projectdb@latest -g

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

Обновление сборки Windows

Скачайте нужную сборку Windows из релизов GitHub. Перед заменой файлов программы остановите приложение и сохраните резервную копию его настроек и данных. Распакуйте новый архив целиком, сохраните настройки и данные приложения, затем запустите его снова. Команда обновления npm предназначена только для установки через npm.

Загрузка и выбор библиотеки релиза

Для проверки целостности загруженной библиотеки app.so ProjectDB сравнивает её контрольную сумму со значением, опубликованным в репозитории. При несовпадении библиотека не используется. Проверенная библиотека сохраняется в ~/.projectdb/lib для следующих запусков.

Скачайте нужную библиотеку из релизов проекта на GitHub и поместите файл app.so в /opt/pdb/lib/app.so (или в подкаталог lib своего рабочего каталога). Этот файл имеет приоритет над автоматической загрузкой. Удалите его, чтобы вернуться к автоматическому выбору.

Помощь

Посмотреть доступные команды:

projectdb --help

Посмотреть параметры отдельной команды:

projectdb pm2-start --help

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

Лицензия

Код репозитория распространяется по лицензии MIT. Его можно бесплатно использовать в личных и коммерческих целях, изменять, распространять и продавать, в том числе в изменённом виде. В копиях программы или её существенных частей необходимо сохранять уведомление об авторских правах и текст лицензии. Программное обеспечение предоставляется без гарантий.

Зависимости и отдельно распространяемые компоненты сохраняют собственные лицензии; эти условия не заменяют их лицензии.