security-alert-center/docs/install-ubuntu-24.04-native.md

Ubuntu 24.04 — установка SAC (native, без Docker)

Пошаговое руководство: PostgreSQL + Python venv + systemd + nginx.
Рекомендуемый путь для production.

---

0. Исходные данные

Параметр	Пример
FQDN	sac.kalinin.example
IP	10.0.0.50
Каталог	/opt/security-alert-center
Пользователь сервиса	sac
API только на localhost	127.0.0.1:8000
Снаружи	nginx → 443 → API

---

1. Базовая настройка ОС

sudo apt update
sudo apt upgrade -y
sudo timedatectl set-timezone Europe/Moscow

Firewall (ufw)

sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

---

2. Пакеты

sudo apt install -y \
  git \
  postgresql \
  postgresql-contrib \
  nginx \
  python3.12 \
  python3.12-venv \
  python3-pip \
  jq \
  certbot \
  python3-certbot-nginx

Проверка:

python3.12 --version
psql --version
nginx -v

---

3. Клонирование репозитория

sudo mkdir -p /opt
sudo git clone https://git.kalinamall.ru/PapaTramp/security-alert-center.git /opt/security-alert-center

---

4. PostgreSQL

Создать пользователя и БД (пароль сохраните для .env):

sudo -u postgres psql <<'SQL'
CREATE USER sac WITH PASSWORD 'ЗАМЕНИТЕ_НА_ДЛИННЫЙ_ПАРОЛЬ';
CREATE DATABASE sac OWNER sac;
GRANT ALL PRIVILEGES ON DATABASE sac TO sac;
SQL

PostgreSQL по умолчанию слушает 127.0.0.1 — для SAC этого достаточно.
Проверка:

psql "postgresql://sac@127.0.0.1/sac" -c 'SELECT 1'

Каталог бэкапов:

sudo mkdir -p /var/backups/sac
sudo chown postgres:postgres /var/backups/sac

---

5. Пользователь sac и Python venv

sudo useradd --system --home /opt/security-alert-center --shell /usr/sbin/nologin sac || true
sudo chown -R sac:sac /opt/security-alert-center

cd /opt/security-alert-center/backend
sudo -u sac python3.12 -m venv .venv
sudo -u sac .venv/bin/pip install --upgrade pip
sudo -u sac .venv/bin/pip install -r requirements.txt

---

6. Конфигурация /etc/security-alert-center

sudo mkdir -p /etc/security-alert-center
sudo chmod 750 /etc/security-alert-center
sudo cp /opt/security-alert-center/deploy/env.native.example /etc/security-alert-center/sac-api.env
sudo chmod 600 /etc/security-alert-center/sac-api.env
sudo nano /etc/security-alert-center/sac-api.env

Обязательно задать:

• DATABASE_URL — с паролем PostgreSQL из шага 4
• JWT_SECRET — openssl rand -hex 32
• SAC_PUBLIC_URL — https://sac.kalinin.example (как будет с nginx)
• SAC_BOOTSTRAP_API_KEY — python3.12 -c "import secrets; print('sac_'+secrets.token_urlsafe(32))"
• EVENT_SCHEMA_PATH=/opt/security-alert-center/schemas/event-schema-v1.json

---

7. Миграции БД

cd /opt/security-alert-center/backend
sudo -u sac bash -c 'set -a; source /etc/security-alert-center/sac-api.env; set +a; .venv/bin/alembic upgrade head'

---

8. systemd

sudo cp /opt/security-alert-center/deploy/systemd/sac-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable sac-api
sudo systemctl start sac-api
sudo systemctl status sac-api --no-pager

Логи:

journalctl -u sac-api -f

---

9. nginx и TLS

sudo cp /opt/security-alert-center/deploy/nginx/sac.conf.example /etc/nginx/sites-available/sac
sudo ln -sf /etc/nginx/sites-available/sac /etc/nginx/sites-enabled/sac
# убрать default при необходимости: sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

В sac.conf замените server_name на ваш FQDN.

Let's Encrypt:

sudo certbot --nginx -d sac.kalinin.example

---

10. Проверка

Локально на сервере:

curl -sS http://127.0.0.1:8000/health | jq .

Через nginx (после TLS):

curl -sS https://sac.kalinin.example/health | jq .

Тест ingest (подставьте SAC_BOOTSTRAP_API_KEY):

API_KEY="ваш_ключ_из_sac-api.env"
curl -sS -X POST http://127.0.0.1:8000/api/v1/events \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "1.0",
    "event_id": "00000000-0000-4000-8000-000000000002",
    "occurred_at": "2026-05-26T12:00:00+03:00",
    "source": {"product": "ssh-monitor", "product_version": "test"},
    "host": {"hostname": "test-host", "os_family": "linux"},
    "category": "agent",
    "type": "agent.test",
    "severity": "info",
    "title": "Test",
    "summary": "Native install check"
  }'

Ожидается HTTP 202 и "status": "accepted".

---

11. Резервное копирование

sudo tee /etc/cron.d/sac-backup <<'EOF'
0 3 * * * postgres pg_dump -Fc -U sac sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump
EOF

Для pg_dump без пароля в cron настройте ~postgres/.pgpass (см. документацию PostgreSQL).

---

12. Обновление SAC

cd /opt/security-alert-center
sudo -u sac git pull
sudo -u sac backend/.venv/bin/pip install -r backend/requirements.txt
sudo -u sac bash -c 'set -a; source /etc/security-alert-center/sac-api.env; set +a; cd backend && .venv/bin/alembic upgrade head'
sudo systemctl restart sac-api

---

13. Чеклист

• Ubuntu 24.04, timezone
• ufw: 22, 80, 443
• PostgreSQL: БД sac, пользователь sac
• venv, зависимости установлены
• /etc/security-alert-center/sac-api.env, chmod 600
• alembic upgrade head без ошибок
• sac-api active (systemd)
• nginx + TLS
• /health ok, ingest 202
• cron backup

---

14. Устранение неполадок

Симптом	Действие
database: error	journalctl -u sac-api; проверить DATABASE_URL, systemctl status postgresql
401 ingest	ключ в Authorization: Bearer; проверить SAC_BOOTSTRAP_API_KEY
502 от nginx	API не слушает: ss -lntp | grep 8000, systemctl restart sac-api
Schema errors 422	путь EVENT_SCHEMA_PATH, наличие файла schema

---

См. также

• install-ubuntu-24.04.md — указатель
• install-ubuntu-24.04-docker.md — альтернатива (не prod)
• deployment.md