Розгорнути приватний npm‑реєстр Verdaccio на Linux: HTTPS, автентифікація, кеш і автозапуск через systemd

Хочете власний приватний npm‑реєстр для внутрішніх пакетів, швидкого кешу з npmjs і повним контролем? Verdaccio — легка й надійна відповідь. Нижче я покажу, як розгорнути його на Linux із захищеним HTTPS, автентифікацією, кешуванням і автозапуском через systemd. Без зайвої магії — тільки зрозумілі кроки у терміналі Linux ⚡

Що ми розгортаємо і чому Verdaccio

Verdaccio — це легкий приватний npm‑реєстр на Node.js, який уміє проксувати публічний registry.npmjs.org з кешем, зберігати ваші приватні пакунки та працювати дуже швидко. Ідеально під проєкти на nodejs в Linux, де важливі швидкість CI, контроль доступу та повторюваність збірок.

Підготовка системи

Далі — приклад для Debian/Ubuntu. Для інших дистрибутивів команди відрізняються, але логіка та ж сама.

# Оновлення системи і встановлення корисних інструментів
sudo apt update && sudo apt -y upgrade
sudo apt -y install curl gnupg2 ca-certificates nginx software-properties-common

# Встановлюємо Node.js LTS (джерело NodeSource)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt -y install nodejs

# Перевіряємо версії
node -v
npm -v

# Системний користувач для Verdaccio
sudo useradd --system --create-home --home-dir /var/verdaccio --shell /usr/sbin/nologin verdaccio

# Каталоги для даних та конфігів
sudo mkdir -p /var/verdaccio/storage /var/verdaccio/plugins /etc/verdaccio
sudo chown -R verdaccio:verdaccio /var/verdaccio

Встановлення Verdaccio

# Встановлення Verdaccio глобально
sudo npm i -g verdaccio

# Знайти шлях до виконуваного файлу (стане в пригоді для systemd)
command -v verdaccio

Налаштування Verdaccio: порт, сховище, кеш, правила доступу

Створимо конфіг. Verdaccio слухатиме localhost:4873 (за ним буде працювати Nginx з HTTPS). Включимо кешування публічних пакетів і базову автентифікацію через htpasswd.

sudo tee /etc/verdaccio/config.yaml >/dev/null <<'YAML'
storage: /var/verdaccio/storage
plugins: /var/verdaccio/plugins

web:
  title: "Private NPM (Verdaccio)"

auth:
  htpasswd:
    file: /var/verdaccio/htpasswd
    max_users: -1  # необмежено

uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    cache: true
    maxage: 1h

packages:
  '@your-scope/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $authenticated
    publish: none
    proxy: npmjs

server:
  keepAliveTimeout: 60

logs:
  - { type: stdout, format: pretty, level: http }

listen: 127.0.0.1:4873
YAML

# Права на конфіг
sudo chmod 644 /etc/verdaccio/config.yaml

Порада: змініть @your-scope на ваш реальний scope (наприклад, @acme).

HTTPS через Nginx + Let's Encrypt

Зробимо зворотний проксі з TLS. Це класичне nginx налаштування для Verdaccio.

# Створюємо віртуальний хост Nginx (замініть registry.example.com на свій домен)
sudo tee /etc/nginx/sites-available/verdaccio >/dev/null <<'NGINX'
server {
  listen 80;
  server_name registry.example.com;

  location / {
    proxy_pass http://127.0.0.1:4873/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 300s;
    client_max_body_size 50m;  # для більших пакетів
  }
}
NGINX

sudo ln -s /etc/nginx/sites-available/verdaccio /etc/nginx/sites-enabled/verdaccio
sudo nginx -t && sudo systemctl reload nginx

# Встановлюємо сертифікат Let's Encrypt (плагін для Nginx)
sudo apt -y install certbot python3-certbot-nginx
sudo certbot --nginx -d registry.example.com --redirect --agree-tos -m admin@example.com --non-interactive

# Перевірка автопродовження сертифікатів
sudo systemctl status certbot.timer

Автентифікація користувачів (htpasswd)

Htpasswd-плагін постачається разом з Verdaccio. Створіть першого користувача через npm — файл /var/verdaccio/htpasswd створиться автоматично після успішної реєстрації.

# Тимчасово запустимо Verdaccio вручну для першого логіна (або дочекаємося systemd нижче)
verdaccio --config /etc/verdaccio/config.yaml &

# Встановлюємо реєстр у вашому клієнті npm	npm config set registry https://registry.example.com/

# Додаємо користувача
npm adduser --registry https://registry.example.com/
# Введіть логін/пароль — після цього файл /var/verdaccio/htpasswd з'явиться

Автозапуск через systemd

Налаштуємо сервіс, щоб Verdaccio стартував разом із системою (так ми покриваємо й тему "cron та systemd timers").

# Створюємо unit (перевірте шлях до verdaccio: зазвичай /usr/bin/verdaccio або /usr/local/bin/verdaccio)
which verdaccio

sudo tee /etc/systemd/system/verdaccio.service >/dev/null <<'UNIT'
[Unit]
Description=Verdaccio Private NPM Registry
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=verdaccio
Group=verdaccio
WorkingDirectory=/var/verdaccio
Environment=NODE_ENV=production
ExecStart=/usr/bin/verdaccio --config /etc/verdaccio/config.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now verdaccio
sudo systemctl status verdaccio --no-pager

Тепер відкрийте https://registry.example.com/ у браузері — побачите простий веб-інтерфейс Verdaccio 🔒

Швидка перевірка публікації

# Переконайтеся, що ви залогінені
npm whoami --registry https://registry.example.com/

# Ініціалізуємо тестовий пакет і публікуємо (у вашому scope)
mkdir -p ~/demo-pkg && cd ~/demo-pkg
npm init -y
npm set scope @your-scope
npm publish --registry https://registry.example.com/

Альтернативні способи

Docker + docker-compose

Любите контейнеризацію? Verdaccio чудово працює в контейнері на сервер Linux. Приклад:

mkdir -p ~/verdaccio && cd ~/verdaccio
sudo tee docker-compose.yml >/dev/null <<'YML'
version: '3.8'
services:
  verdaccio:
    image: verdaccio/verdaccio:latest
    container_name: verdaccio
    restart: always
    ports:
      - "127.0.0.1:4873:4873"
    volumes:
      - ./storage:/verdaccio/storage
      - ./conf:/verdaccio/conf
YML

# Далі повторіть nginx + certbot як вище (проксі на 127.0.0.1:4873)
docker compose up -d

GUI-спосіб через Portainer/Nginx Proxy Manager

Якщо вам зручніше клікати мишкою: запустіть Verdaccio контейнер у Portainer, а HTTPS заверніть через Nginx Proxy Manager (видати сертифікат Let's Encrypt і вказати upstream 127.0.0.1:4873). Це швидкий графічний шлях для невеликих команд.

FAQ

Як обмежити публікацію лише певним scope?

У секції packages додайте правила для @your-scope/* з publish: $authenticated, а для "**" виставте publish: none — як у прикладі вище.

Помилка 413 Request Entity Too Large при публікації

Збільшіть client_max_body_size у nginx до потрібного значення (наприклад, 100m) і перезавантажте Nginx.

Як очистити кеш проксі?

Зупиніть сервіс, видаліть кеш із каталогу зберігання (залежить від версії; зазвичай усередині /var/verdaccio/storage/ з префіксами кешу), потім запустіть сервіс знову. Робіть це обережно на проді.

Чи обов'язково використовувати Nginx?

Ні. Можна підняти HTTPS на самому Node.js через reverse proxy Caddy/Traefik чи вмикати TLS у Nginx Proxy Manager. Але класичне nginx налаштування — найпростіше і перевірене.

Як інтегрувати з CI?

Задайте NPM_TOKEN у секретах CI, а в .npmrc проєкту збережіть //registry.example.com/:_authToken=${NPM_TOKEN}. Потім npm publish працюватиме без інтерактивного логіна.

Systemd не знаходить бінарник verdaccio

Дізнайтеся точний шлях через which verdaccio і змініть ExecStart у unit-файлі. Далі systemctl daemon-reload і перезапуск сервісу.

Хочу резервні копії конфігів і htpasswd

Створіть простий скрипт бекапу і запускайте його через cron та systemd timers раз на добу.

# Скрипт бекапу
sudo tee /usr/local/bin/verdaccio-backup.sh >/dev/null <<'SH'
#!/usr/bin/env bash
set -euo pipefail
DST=/var/backups
DATE=$(date +%F-%H%M)
mkdir -p "$DST"
tar -czf "$DST/verdaccio-$DATE.tgz" \
  /etc/verdaccio/config.yaml /var/verdaccio/htpasswd
SH
sudo chmod +x /usr/local/bin/verdaccio-backup.sh

# systemd unit + timer
sudo tee /etc/systemd/system/verdaccio-backup.service >/dev/null <<'UNIT'
[Unit]
Description=Backup Verdaccio config and htpasswd

[Service]
Type=oneshot
ExecStart=/usr/local/bin/verdaccio-backup.sh
UNIT

sudo tee /etc/systemd/system/verdaccio-backup.timer >/dev/null <<'UNIT'
[Unit]
Description=Run Verdaccio backup daily

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now verdaccio-backup.timer

Порада від Kernelka

Тримайте продовження сертифікатів і бекапи під наглядом: додайте сповіщення у ваш моніторинг або в Slack/Telegram, щоб не прокинутися вранці з протермінованим TLS або втраченим доступом 😅

Підсумок

• Встановили Verdaccio на сервер Linux і налаштували зберігання та правила доступу.
• Увімкнули HTTPS через Nginx + Let's Encrypt і базову автентифікацію htpasswd.
• Додали кешування проксі, щоб прискорити CI і зменшити залежність від зовнішнього реєстру.
• Запустили автозапуск через systemd і налаштували бекапи за допомогою cron та systemd timers.
• Перевірили публікацію пакунка і базові сценарії експлуатації.