ArchMapДокументация

Установить ArchMap на сервер

Примечание

Для установки на Linux-сервер достаточно одного архива поставки. Python и Node.js на сервере не нужны, потому что в архиве уже есть переносной Python со всеми зависимостями, бэкенд и собранный интерфейс. Установщик настраивает службу systemd и сайт в nginx.

Примечание

Что понадобится:

  • сервер Linux x86_64 с systemd и glibc 2.17 или новее (подходит любой дистрибутив последних лет);
  • права root или sudo на время установки;
  • nginx из репозитория дистрибутива;
  • 1–2 ГБ памяти и около 1 ГБ на диске (установщик хранит три последних релиза);
  • pg_dump той же или более новой версии, что сервер PostgreSQL (пакет postgresql-client) для копии базы перед обновлениями;
  • отдельное DNS-имя для ArchMap и сертификат TLS для него (работа по подпути не поддерживается).

Подготовить базу PostgreSQL#

Примечание

ArchMap хранит все данные в PostgreSQL версии 15 или новее. Базу готовит администратор PostgreSQL, а таблицы ArchMap создаст сам при первом запуске. Расширения не нужны.

Чтобы подготовить базу, выполните следующие действия:

  1. Создайте пользователя и базу в кодировке UTF-8, владельцем которой будет этот пользователь:

    CREATE ROLE archmap LOGIN PASSWORD 'ПАРОЛЬ';
CREATE DATABASE archmap OWNER archmap ENCODING 'UTF8' TEMPLATE template0;

  2. В файле pg_hba.conf разрешите пользователю archmap подключаться к базе archmap с адресов, с которых работает ArchMap.

  3. Перечитайте настройки PostgreSQL:

    SELECT pg_reload_conf();

  4. Составьте адрес базы для ArchMap (например, postgresql://archmap:ПАРОЛЬ@pg.example.com:5432/archmap).

Примечание

Спецсимволы пароля в адресе базы нужно закодировать: @ → %40, : → %3A, / → %2F, % → %25, # → %23, ? → %3F. Если PostgreSQL требует TLS, допишите к адресу ?sslmode=require.

Собрать архив поставки#

Чтобы собрать архив поставки, выполните следующие действия:

  1. На машине с доступом в интернет (Linux x86_64 с git, Node.js 22 или новее и curl) скачайте исходный код ArchMap:

    git clone https://github.com/eidunyushkinhse/archmap.git
cd archmap

  2. Соберите поставку:

    deploy/build-bundle.sh

    В папке dist-bundle появятся архив archmap-<дата>-<коммит>-linux-x86_64.tar.gz (около 55 МБ) и файл с его контрольной суммой .sha256.

Установить ArchMap#

Чтобы установить ArchMap на сервер, выполните следующие действия:

  1. Перенесите архив и файл .sha256 на сервер.

  2. Проверьте целостность архива и распакуйте его:

    sha256sum -c archmap-*.tar.gz.sha256
tar -xzf archmap-*.tar.gz && cd archmap-*-linux-x86_64

  3. Запустите установщик, указав имя сервера и сертификат:

    sudo ./deploy/install.sh --server-name archmap.example.com \
  --tls-cert /etc/ssl/archmap.crt --tls-key /etc/ssl/archmap.key

    При первом запуске установщик создаст файл настроек /etc/archmap/archmap.env со случайным ключом подписи и остановится.

  4. Впишите в файл /etc/archmap/archmap.env адрес базы:

    DATABASE_URL=postgresql://archmap:ПАРОЛЬ@pg.example.com:5432/archmap

  5. Запустите ту же команду установщика ещё раз. Установщик проверит базу, применит миграции, разложит релиз в /opt/archmap, запустит службу archmap и настроит nginx.

  6. Создайте первого администратора. Команда дважды спросит пароль:

    sudo archmap-admin create-admin admin

  7. Откройте адрес ArchMap (например, https://archmap.example.com) и войдите под учётной записью администратора.

  8. Заведите учётные записи для коллег (см. Создать учётные записи и назначить роли).

Примечание

Без параметров --tls-cert и --tls-key ArchMap будет работать по HTTP без шифрования. Так можно делать только в доверенном тестовом сегменте сети, потому что пароли и токены пойдут открытым текстом.

Примечание

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

Примечание

Что где лежит после установки:

  • /opt/archmap/releases/<версия>: релизы (хранятся три последних);
  • /opt/archmap/current: ссылка на работающий релиз;
  • /etc/archmap/archmap.env: настройки (см. Справочник переменных окружения);
  • /etc/systemd/system/archmap.service: служба, работает от пользователя archmap;
  • /etc/nginx/conf.d/archmap.conf: сайт в nginx;
  • /usr/local/bin/archmap-admin: команды администрирования.

Выпустить сертификат Let’s Encrypt#

Примечание

Если сервер открыт в интернет, сертификат можно бесплатно получить в Let’s Encrypt. Для этого сначала установите ArchMap по HTTP, а затем запустите установщик ещё раз уже с сертификатом.

Чтобы установить ArchMap с сертификатом Let’s Encrypt, выполните следующие действия:

  1. Установите ArchMap без сертификата (см. Установить ArchMap):

    sudo ./deploy/install.sh --server-name archmap.example.com

  2. Выпустите сертификат с помощью certbot:

    sudo certbot certonly --nginx -d archmap.example.com --deploy-hook "systemctl reload nginx"

  3. Запустите установщик ещё раз с выпущенным сертификатом:

    sudo ./deploy/install.sh --server-name archmap.example.com \
  --tls-cert /etc/letsencrypt/live/archmap.example.com/fullchain.pem \
  --tls-key /etc/letsencrypt/live/archmap.example.com/privkey.pem

  4. В файле /etc/archmap/archmap.env исправьте в переменной CORS_ORIGINS адрес с http:// на https://.

  5. Перезапустите службу:

    sudo systemctl restart archmap

Примечание

Сертификат продлевает служба certbot.timer, а после продления nginx перечитывает его сам.

Установить без nginx#

Примечание

Если перед сервером уже стоит свой обратный прокси, nginx не нужен. Установщик с параметром --no-nginx ставит только службу ArchMap, а прокси нужно настроить самостоятельно.

Чтобы установить ArchMap без nginx, выполните следующие действия:

  1. Запустите установщик с параметром --no-nginx:

    sudo ./deploy/install.sh --no-nginx

  2. Настройте свой обратный прокси:

    • отдавать файлы интерфейса из папки /opt/archmap/current/frontend, а на неизвестные пути отвечать файлом index.html;
    • передавать на 127.0.0.1:8000 пути /api/, /mcp и /.well-known/oauth-;
    • ждать ответа на /mcp и /api/ до 300 секунд;
    • принимать запросы до 64 МБ.

Примечание

За образец возьмите конфигурацию nginx, которую пишет установщик (функция render_nginx в файле deploy/install.sh).