vps-tracker/README.md

VPS Tracker

VPS Tracker — это веб-приложение для учёта виртуальных серверов, хостинг-провайдеров, счетов и балансов. Всё работает в браузере: данные хранятся у вас на компьютере или сервере, можно подключить синхронизацию с BILLmanager.

Ниже описано, как запустить готовую программу в Linux с помощью Docker. Отдельно устанавливать Node.js не нужно.

---

Скриншоты

Дашборд со сводкой по VPS, балансам и графикам:

Список виртуальных серверов (IP-адреса на скриншоте замаскированы):

---

Содержание

1. Скриншоты
2. Что понадобится
3. Самый простой способ: готовый образ
4. Запуск через Docker Compose
5. Production: Traefik + Cloudflare HTTPS
6. Сборка образа у себя
7. Сохранение данных и резервная копия
8. Другой порт и доступ по сети
9. Обновление программы
10. Для разработчиков

---

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

• Компьютер или сервер с Linux (подойдут Ubuntu, Debian, Fedora и другие дистрибутивы).
• Установленные Docker и плагин Compose. Официальные инструкции: Установка Docker Engine и обзор Compose.

Проверка в терминале:

docker --version
docker compose version

---

Самый простой способ: готовый образ

Подойдёт, если у вас есть только терминал и вы хотите быстро поднять сервис.

Шаг 1. Скачать образ

docker pull ghcr.io/denozordec/vps-tracker:latest

Если запросили логин: пакет на GitHub может быть закрытым. Войдите в аккаунт GitHub и создайте Personal Access Token с правом read:packages, затем выполните:

echo ВАШ_ТОКЕН | docker login ghcr.io -u ВАШ_ЛОГИН_GITHUB --password-stdin

Либо откройте на GitHub страницу пакета vps-tracker → Package settings и сделайте пакет public — тогда docker pull без входа.

Шаг 2. Папка для данных

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

mkdir -p ~/vps-tracker-data

Можно выбрать любой каталог вместо ~/vps-tracker-data — главное, запомнить путь для команды ниже.

Шаг 3. Запуск

Вариант А — в фоне (удобно на сервере, контейнер переживёт закрытие терминала):

docker run -d \
  --name vps-tracker \
  --restart unless-stopped \
  -p 3001:3001 \
  -v ~/vps-tracker-data:/app/data \
  ghcr.io/denozordec/vps-tracker:latest

Вариант Б — в переднем плане (логи видны в терминале, остановка — Ctrl+C):

docker run --rm \
  -p 3001:3001 \
  -v ~/vps-tracker-data:/app/data \
  ghcr.io/denozordec/vps-tracker:latest

Шаг 4. Открыть в браузере

На той же машине откройте:

http://localhost:3001

Если заходите с другого компьютера в сети — подставьте IP сервера: http://192.168.1.10:3001 (ваш адрес может отличаться). На сервере может понадобиться открыть порт в брандмауэре, например для Ubuntu с UFW:

sudo ufw allow 3001/tcp
sudo ufw reload

Остановка фонового контейнера:

docker stop vps-tracker
docker rm vps-tracker

---

Запуск через Docker Compose

Имеет смысл, если вы склонировали этот репозиторий: в docker-compose.yml указан готовый образ ghcr.io/denozordec/vps-tracker — при up он подтягивается с GitHub Container Registry (локальная сборка не нужна).

git clone https://github.com/denozordec/vps-tracker.git
cd vps-tracker
docker compose up -d

То же через Docker CLI (без Compose) — эквивалент docker-compose.yml: том ./data, порт 3001, переменная PORT=3001.

mkdir -p ./data
docker pull ghcr.io/denozordec/vps-tracker:latest
docker run -d \
  --name vps-tracker \
  --restart unless-stopped \
  -p 3001:3001 \
  -e PORT=3001 \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/denozordec/vps-tracker:latest

В PowerShell из каталога проекта подставьте путь к данным так: -v "${PWD}/data:/app/data".

Данные по умолчанию сохраняются в папку data внутри каталога проекта на диске.

Остановка:

docker compose down

---

Production: Traefik + Cloudflare HTTPS (Linux)

На VPS с доменом в Cloudflare: Traefik (Let's Encrypt DNS-01) + контейнер VPS Tracker за HTTPS, без публикации порта 3001 наружу.

Пошаговая инструкция, compose и .env: docs/deploy-traefik.md
Файлы: deploy/docker-compose.traefik.yml, deploy/env.traefik.example.

Кратко:

mkdir -p /opt/vps-tracker/data && cd /opt/vps-tracker
curl -fsSL -o docker-compose.yml \
  https://raw.githubusercontent.com/denozordec/vps-tracker/main/deploy/docker-compose.traefik.yml
curl -fsSL -o .env \
  https://raw.githubusercontent.com/denozordec/vps-tracker/main/deploy/env.traefik.example
nano .env   # CF_DNS_API_TOKEN, LETSENCRYPT_EMAIL, VPS_DOMAIN
docker compose pull && docker compose up -d
curl -fsS https://ВАШ_ДОМЕН/health

---

Сборка образа у себя

Если нужен свой образ из исходников (после git clone):

cd vps-tracker
docker build -t vps-tracker:local .
mkdir -p ./data
docker run -d \
  --name vps-tracker \
  --restart unless-stopped \
  -p 3001:3001 \
  -v "$(pwd)/data:/app/data" \
  vps-tracker:local

---

Сохранение данных и резервная копия

Файл базы в примерах выше лежит на хосте:

Способ запуска	Где лежит база на диске
docker run с -v ~/vps-tracker-data:/app/data	~/vps-tracker-data/vps-tracker.db
Docker Compose из репозитория	./data/vps-tracker.db в папке проекта

Скопируйте файл vps-tracker.db в безопасное место — это и есть резервная копия. Пока приложение не запущено, можно просто скопировать файл обратно для восстановления.

---

Другой порт и доступ по сети

Внутри контейнера приложение слушает порт 3001. Сменить внешний порт (например, 8080 снаружи, 3001 внутри):

docker run -d \
  --name vps-tracker \
  --restart unless-stopped \
  -p 8080:3001 \
  -v ~/vps-tracker-data:/app/data \
  ghcr.io/denozordec/vps-tracker:latest

Тогда в браузере: http://localhost:8080

Чтобы сменить и внутренний порт (редко нужно), добавьте -e PORT=8080 и согласуйте с -p, например -p 8080:8080 и -e PORT=8080.

---

Обновление программы

Если используете образ с GitHub:

docker pull ghcr.io/denozordec/vps-tracker:latest
docker stop vps-tracker
docker rm vps-tracker

Затем снова выполните команду docker run из раздела «Самый простой способ» (том -v ...:/app/data оставьте тот же — данные сохранятся).

При Docker Compose из репозитория:

cd vps-tracker
git pull
docker compose up -d

Файл Compose настроен с pull_policy: always, поэтому при каждом up запрашивается актуальный образ с GHCR.

---

Для разработчиков

Локальный запуск без Docker: npm install и npm run dev. Подробности по коду, API и синхронизации — в AGENTS.md.