Кастомизация Homarr: персональный cockpit для homelab
Пошаговое руководство по настройке и кастомизации Homarr — превращаем дашборд в персональный cockpit для управления сервисами вашего homelab.
Установка Homarr
Подготовка окружения и запуск Homarr через Docker
# Проверка установки Docker
docker --version
docker-compose --version
# Создание директорий для Homarr
mkdir homarr
cd homarr
mkdir data
# Создание docker-compose.yml
cat > docker-compose.yml << EOF
version: "3"
services:
homarr:
image: ghcr.io/ajnart/homarr:latest
container_name: homarr
restart: always
volumes:
- ./data:/app/data
ports:
- 7575:7575
environment:
- TZ=Europe/Moscow
EOF
# Запуск Homarr
docker-compose up -dБазовая конфигурация
Настройка основных параметров Homarr после первого запуска
# Создание пользователя и настройка параметров
# 1. При первом доступе создать аккаунт администратора
# 2. Настроить имя пользователя и пароль
# 3. Выбрать тему оформления
# 4. Настроить общие параметры панели в разделе Настройки > Общие параметрыДобавление сервисов
Добавление и настройка сервисов в Homarr
# Пример конфигурации для Portainer
{
"name": "Portainer",
"url": "http://portainer:9000",
"icon": "mdi:docker",
"type": "docker",
"docker": {
"container": "portainer",
"image": "portainer/portainer-ce"
}
}
# Пример конфигурации для системных метрик
{
"name": "Системные метрики",
"url": "",
"icon": "mdi:gauge-full",
"type": "system",
"system": {
"cpu": true,
"memory": true,
"disk": true,
"network": true
}
}Кастомизация интерфейса
Изменение темы и создание кастомных виджетов
# Пример кастомного виджета на React/TypeScript
import React, { useEffect, useState } from 'react';
import { Widget } from '@homarr/widget';
interface MyCustomWidgetProps {
title: string;
data?: any;
}
export const MyCustomWidget: React.FC<MyCustomWidgetProps> = ({ title, data }) => {
const [widgetData, setWidgetData] = useState<any>(null);
useEffect(() => {
const fetchData = async () => {
try {
const response = await fetch('https://api.example.com/data');
const result = await response.json();
setWidgetData(result);
} catch (error) {
console.error('Error fetching widget data:', error);
}
};
fetchData();
}, []);
return (
<Widget title={title}>
<div>
{widgetData ? (
<div>
<p>Значение: {widgetData.value}</p>
<p>Статус: {widgetData.status}</p>
</div>
) : (
<p>Загрузка данных...</p>
)}
</div>
</Widget>
);
};Расширенные настройки
Настройка SSL/TLS, ограничение доступа по IP и резервное копирование
# Настройка SSL через Nginx
server {
listen 443 ssl http2;
server_name homarr.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:7575;
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;
}
}
# Ограничение доступа по IP
allow 192.168.1.0/24;
allow 10.0.0.1;
deny all;
# Резервное копирование
tar -czf homarr-backup.tar.gz ./dataИнтеграции и плагины
Интеграция с Docker, API сервисов и создание собственных интеграций
# Конфигурация интеграции Docker
{
"docker": {
"enabled": true,
"refreshInterval": 5000,
"showAllContainers": false,
"onlyRunning": true
}
}
# Пример кастомной интеграции
class MyIntegration extends Integration {
async fetchData(): Promise<MyIntegrationData> {
const client = new HttpClient(this.config.baseUrl, {
headers: {
'Authorization': `Bearer ${this.config.apiKey}`
}
});
try {
const response = await client.get('/status');
const data = await response.json();
return {
status: 'online',
value: data.value,
lastUpdated: new Date()
};
} catch (error) {
return {
status: 'offline',
value: 0,
lastUpdated: new Date()
};
}
}
}Оптимизация производительности
Настройка ресурсов Docker, кэширование и оптимизация базы данных
# Ограничение ресурсов Docker
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.5'
memory: 512M
# Настройка PostgreSQL для больших развертываний
services:
postgres:
image: postgres:14
environment:
POSTGRES_USER: homarr
POSTGRES_PASSWORD: yourpassword
POSTGRES_DB: homarr
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
homarr:
image: ghcr.io/ajnart/homarr:latest
environment:
- DATABASE_URL=postgresql://homarr:yourpassword@postgres:5432/homarr
depends_on:
- postgres
volumes:
postgres_data:Кастомизация Homarr: создание персонального cockpit для вашего homelab
Мета-описание: Узнайте, как установить, настроить и глубоко кастомизировать Homarr — современную панель управления для вашего homelab. Пошаговое руководство с примерами кода для создания персонального dashboard.
Оглавление
- Введение
- Требования
- Установка Homarr
- Базовая конфигурация
- Добавление сервисов и приложений
- Кастомизация интерфейса
- Расширенные настройки
- Интеграции и плагины
- Оптимизация производительности
- Заключение
Введение
Homarr — это современная панель управления для вашего homelab, созданная на основе Next.js и TypeScript. Она позволяет агрегировать все ваши сервисы и приложения в одном удобном месте, предоставляя визуально привлекательный и функциональный интерфейс для мониторинга и управления вашим окружением. В этом руководстве мы рассмотрим процесс установки, базовой настройки и глубокой кастомизации Homarr под ваши нужды.
Homarr предлагает гибкую архитектуру, которая позволяет не только отображать информацию, но и создавать собственные виджеты и интеграции для уникальных задач. Благодаря открытому исходному коду и активному сообществу, проект постоянно развивается, добавляя новые функции и улучшая пользовательский опыт.
Официальный репозиторий Homarr на GitHub содержит последнюю версию проекта и документацию.
Требования
Прежде чем начать, убедитесь, что у вас есть:
- Сервер или контейнер с Docker и Docker Compose
- Базовые знания работы с командной строкой
- Доступ к порту 7575 (по умолчанию для Homarr)
- Опционально: Nginx или другой обратный прокси для доступа к панели
Для некоторых функций, таких как кастомные виджеты и интеграции, могут потребоваться дополнительные знания:
- Основы React и TypeScript для создания виджетов
- Опыт работы с API для создания интеграций
- Понимание принципов работы Docker для развертывания
Установка Homarr
1. Подготовка окружения
Убедитесь, что Docker и Docker Compose установлены на вашем сервере:
# Проверка установки Docker
docker --version
docker-compose --version
Если Docker не установлен, следуйте официальной документации для установки:
# Для Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Установка Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Подробные инструкции по установке Docker можно найти в официальной документации Docker.
2. Создание директорий для Homarr
Создайте директорию для проекта Homarr и перейдите в нее:
mkdir homarr
cd homarr
mkdir data
Эта структура директорий понадобится для хранения данных Homarr, включая конфигурации, пользовательские настройки и интеграции.
3. Создание docker-compose.yml
Создайте файл docker-compose.yml со следующим содержанием:
version: "3"
services:
homarr:
image: ghcr.io/ajnart/homarr:latest
container_name: homarr
restart: always
volumes:
- ./data:/app/data
ports:
- 7575:7575
environment:
- TZ=Europe/Moscow # Укажите ваш часовой пояс
Этот файл конфигурации определяет контейнер Homarr с монтированием тома для сохранения данных. Вы можете изменить порт, если 7575 уже занят.
4. Запуск Homarr
Запустите контейнер Homarr:
docker-compose up -d
Подождите несколько минут, пока контейнер будет скачан и запущен. После этого Homarr будет доступен по адресу http://ваш-ip:7575.
Для проверки статуса контейнера используйте команду:
docker-compose ps
Базовая конфигурация
1. Первоначальная настройка
При первом доступе к Homarr вам будет предложено создать аккаунт администратора и настроить основные параметры:
- Заполните форму регистрации
- Настройте имя пользователя и пароль
- Выберите тему оформления
- Настройте основные параметры панели
На этом этапе вы также сможете выбрать способ аутентификации: стандартный вход или интеграция с внешними сервисами, такими как OAuth.
2. Общие настройки
Для доступа к общим настройкам нажмите на иконку шестеренки в правом верхнем углу и выберите "Настройки". Здесь вы можете настроить:
- Общие параметры (название сайта, часовой пояс, язык)
- Параметры безопасности
- Настройки интеграций
- Параметры бэкграундов и тем
В разделе "Общие параметры" вы можете задать имя вашего dashboard, которое будет отображаться в заголовке страницы. Также здесь можно настроить язык интерфейса и часовой пояс для корректного отображения времени.
3. Настройка боковой панели
В настройках боковой панели вы можете:
- Добавить или удалить разделы
- Изменить порядок разделов
- Настроить отображение иконок
- Добавить кастомные ссылки
Боковая панель Homarr является основным навигационным элементом. Вы можете создать несколько разделов для категоризации сервисов, например: "Медиа", "Сетевые сервисы", "Инструменты", "Мониторинг".
Добавление сервисов и приложений
1. Добавление нового сервиса
Homarr поддерживает множество сервисов. Для добавления нового сервиса:
- Нажмите на "+" в основном интерфейсе
- Выберите "Добавить сервис" или "Импорт из конфигурации"
- Заполните форму с параметрами сервиса
При добавлении сервиса можно выбрать тип из предопределенного списка или создать кастомный тип, указав URL и необходимые параметры.
2. Настройка сервисов
Для каждого сервиса вы можете настроить:
- Название и иконку
- URL-адрес
- Статус (онлайн/офлайн)
- Параметры мониторинга
- Кастомные виджеты
- Интеграцию с API
Homarr автоматически проверяет доступность сервисов через заданный интервал. Вы можете настроить параметры проверки: частоту, таймаут и ожидаемый код ответа.
3. Примеры популярных сервисов
Примеры конфигурации для популярных сервисов:
Docker:
{
"name": "Portainer",
"url": "http://portainer:9000",
"icon": "mdi:docker",
"type": "docker",
"docker": {
"container": "portainer",
"image": "portainer/portainer-ce"
}
}
Системные метрики:
{
"name": "Системные метрики",
"url": "",
"icon": "mdi:gauge-full",
"type": "system",
"system": {
"cpu": true,
"memory": true,
"disk": true,
"network": true
}
}
Home Assistant:
{
"name": "Home Assistant",
"url": "http://homeassistant:8123",
"icon": "mdi:home-assistant",
"type": "homeassistant",
"homeassistant": {
"token": "ваш-токен-api",
"entity": "sensor.cpu_usage"
}
}
Кастомизация интерфейса
1. Изменение темы
Homarr поддерживает несколько тем оформления:
- Перейдите в "Настройки" > "Внешний вид"
- Выберите предпочитаемую тему
- Настройте цветовую схему
- Сохраните изменения
Доступные темы включают светую, темную и автоматическую (в зависимости от настроек системы). Вы также можете настроить акцентные цвета и параметры контрастности.
2. Кастомные виджеты
Для добавления кастомных виджетов:
- Нажмите "Настроить" на панели
- Выберите виджеты из доступных
- Настройте параметры каждого виджета
- Перетащите виджеты для изменения их расположения
Homarr предоставляет богатый набор предустановленных виджетов: от простых текстовых блоков до сложных графиков и информационных панелей. Вы можете настраивать размеры, положение и обновление каждого виджета.
3. Кастомные фоны
Homarr позволяет использовать кастомные фоны:
- Перейдите в "Настройки" > "Фон"
- Выберите тип фона (цвет, градиент, изображение)
- При необходимости загрузите изображение
- Настройте параметры прозрачности и размытия
Для фоновых изображений поддерживаются форматы JPG, PNG и GIF. Вы можете установить прозрачность или эффект размытия для улучшения читаемости текста поверх фона.
4. Создание своих виджетов
Для создания собственных виджетов вам понадобится базовые знания React и TypeScript. Процесс включает:
- Создание новой директории для виджета
- Разработка компонента виджета
- Сборка и добавление в Homarr
- Регистрация нового виджета в конфигурации
Подробная инструкция по созданию кастомных виджетов:
Шаг 1: Настройка окружения для разработки
# Клонируйте репозиторий Homarr
git clone https://github.com/ajnart/homarr.git
cd homarr
# Установите зависимости
npm install
Шаг 2: Создание структуры виджета
# Создайте директорию для вашего виджета
mkdir -p packages/widgets/src/my-custom-widget
# Создайте файл компонента виджета
touch packages/widgets/src/my-custom-widget/MyCustomWidget.tsx
Шаг 3: Разработка компонента виджета
// packages/widgets/src/my-custom-widget/MyCustomWidget.tsx
import React, { useEffect, useState } from 'react';
import { Widget } from '@homarr/widget';
import { useTheme } from '@mui/material/styles';
interface MyCustomWidgetProps {
title: string;
data?: any;
}
export const MyCustomWidget: React.FC<MyCustomWidgetProps> = ({ title, data }) => {
const theme = useTheme();
const [widgetData, setWidgetData] = useState<any>(null);
useEffect(() => {
// Здесь можно реализовать логику получения данных
// Например, из API или локального хранилища
const fetchData = async () => {
try {
// Пример получения данных (замените на ваш API)
const response = await fetch('https://api.example.com/data');
const result = await response.json();
setWidgetData(result);
} catch (error) {
console.error('Error fetching widget data:', error);
}
};
fetchData();
}, []);
return (
<Widget title={title}>
<div style={{ padding: theme.spacing(2) }}>
{widgetData ? (
<div>
{/* Отображение данных */}
<p>Значение: {widgetData.value}</p>
<p>Статус: {widgetData.status}</p>
</div>
) : (
<p>Загрузка данных...</p>
)}
</div>
</Widget>
);
};
Шаг 4: Регистрация виджета
// packages/widgets/src/index.ts
import { MyCustomWidget } from './my-custom-widget/MyCustomWidget';
// Добавьте ваш виджет в список доступных виджетов
export const widgets = {
// ... существующие виджеты
'my-custom-widget': MyCustomWidget,
};
Шаг 5: Сборка и установка
# Соберите проект
npm run build
# Скопируйте собранные файлы в директорию данных Homarr
cp -r packages/widgets/dist /путь/к/директории/homarr/data/widgets
Шаг 6: Использование виджета в Homarr
- Откройте интерфейс Homarr
- Нажмите "Настроить" в режиме редактирования
- В списке виджетов найдите "Мой кастомный виджет"
- Добавьте его на панель и настройте параметры
Для более сложных виджетов вы можете добавить:
- Параметры конфигурации через форму
- Поддержку темной/светлой темы
- Анимации и переходы
- Взаимодействие с другими виджетами
Расширенные настройки
1. Использование переменных окружения
Для передачи переменных окружения в Homarr:
- Откройте файл
docker-compose.yml - Добавьте секцию
environmentдля сервиса homarr - Добавьте необходимые переменные
Пример:
services:
homarr:
environment:
- API_KEY=ваш-ключ-api
- NODE_ENV=production
- TZ=Europe/Moscow
- LOG_LEVEL=debug
Полный список переменных окружения доступен в документации Homarr.
2. Настройка SSL/TLS
Для настройки HTTPS через обратный прокси (пример для Nginx):
server {
listen 443 ssl http2;
server_name homarr.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:7575;
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;
}
}
Для автоматической настройки SSL можно использовать Let's Encrypt с Certbot:
# Установка Certbot
sudo apt install certbot python3-certbot-nginx
# Получение сертификата
sudo certbot --nginx -d homarr.yourdomain.com
3. Настройка доступа по IP
Для ограничения доступа по IP:
- В Docker Compose добавьте сеть:
networks:
app-network:
driver: bridge
services:
homarr:
networks:
- app-network
# ...
- Настройте брандмауэр или reverse proxy для ограничения доступа
Для Nginx:
# Ограничение доступа по IP
server {
listen 443 ssl http2;
server_name homarr.yourdomain.com;
# Разрешить только определенные IP
allow 192.168.1.0/24;
allow 10.0.0.1;
deny all;
# ... остальная конфигурация
}
Для iptables:
# Разрешить доступ только с определенных IP
sudo iptables -A INPUT -p tcp --dport 7575 -s 192.168.1.0/24 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 7575 -s 10.0.0.1 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 7575 -j DROP
4. Резервное копирование
Для резервного копирования Homarr:
# Создайте архив данных
tar -czf homarr-backup.tar.gz ./data
# Восстановление
tar -xzf homarr-backup.tar.gz -C /path/to/restore
Для автоматического резервного копирования можно настроить cron-задачу:
# Откройте crontab
crontab -e
# Добавьте ежедневное резервное копирование в 2:00 ночи
0 2 * * * tar -czf /backups/homarr-$(date +\%Y\%m\%d).tar.gz -C /путь/к/homarr data
Интеграции и плагины
1. Интеграция с Docker
Homarr может отслеживать контейнеры Docker:
- В настройках Homarr перейдите в "Интеграции"
- Включите интеграцию с Docker
- Настройте параметры мониторинга
- Перезапустите Homarr
Для использования интеграции Docker убедитесь, что:
- Docker доступен из контейнера Homarr
- На хост-машине настроены необходимые разрешения
- Контейнеры имеют метки для правильной идентификации
Пример конфигурации:
{
"docker": {
"enabled": true,
"refreshInterval": 5000,
"showAllContainers": false,
"onlyRunning": true
}
}
2. Интеграция с API сервисов
Homarr поддерживает интеграцию с множеством API:
- В настройках выберите "Интеграции" > "Добавить интеграцию"
- Выберите нужный сервис
- Настройте параметры подключения
- Протестируйте соединение
Примеры поддерживаемых сервисов:
- Plex
- Sonarr
- Radarr
- Transmission
- Home Assistant
- И многие другие
Для создания интеграции с кастомным API:
- В настройках Homarr выберите "Интеграции" > "Добавить интеграцию"
- Выберите "Кастомная интеграция"
- Заполните форму:
- Имя: "Мой сервис"
- URL API: "https://api.myservice.com"
- Метод: GET или POST
- Заголовки: {"Authorization": "Bearer your-token"}
- Интервал обновления: 30000 (мс)
- Сохраните и протестируйте
3. Использование плагинов
Для добавления плагинов:
- Перейдите в "Настройки" > "Плагины"
- Нажмите "Добавить плагин"
- Выберите нужный плагин из репозитория
- Настройте параметры плагина
Homarr поддерживает плагины для расширения функциональности. Некоторые популярные плагины:
- Плагин для уведомлений (Pushover, Telegram)
- Плагин для отображения погоды
- Плагин для управления умным домом
- Плагин для мониторинга сетевых устройств
4. Создание своих интеграций
Для создания собственной интеграции:
- Создайте новую директорию для интеграции
- Разработайте модуль интеграции на TypeScript
- Реализуйте необходимые методы API
- Добавьте интеграцию в конфигурацию Homarr
Пример базовой интеграции:
// packages/integrations/src/my-integration/MyIntegration.ts
import { Integration } from '@homarr/integration';
import { HttpClient } from '@homarr/http-client';
interface MyIntegrationConfig {
apiKey: string;
baseUrl: string;
}
interface MyIntegrationData {
status: 'online' | 'offline';
value: number;
lastUpdated: Date;
}
export class MyIntegration extends Integration<MyIntegrationConfig, MyIntegrationData> {
constructor(config: MyIntegrationConfig) {
super('my-integration', {
name: 'Моя интеграция',
description: 'Описание моей интеграции',
author: 'Ваше имя',
version: '1.0.0',
config: config
});
}
async fetchData(): Promise<MyIntegrationData> {
const client = new HttpClient(this.config.baseUrl, {
headers: {
'Authorization': `Bearer ${this.config.apiKey}`
}
});
try {
const response = await client.get('/status');
const data = await response.json();
return {
status: 'online',
value: data.value,
lastUpdated: new Date()
};
} catch (error) {
return {
status: 'offline',
value: 0,
lastUpdated: new Date()
};
}
}
async render(data: MyIntegrationData): React.ReactNode {
return (
<div>
<p>Статус: {data.status}</p>
<p>Значение: {data.value}</p>
<p>Последнее обновление: {data.lastUpdated.toLocaleString()}</p>
</div>
);
}
}
Регистрация интеграции:
// packages/integrations/src/index.ts
import { MyIntegration } from './my-integration/MyIntegration';
// Добавьте вашу интеграцию в список доступных
export const integrations = {
// ... существующие интеграции
'my-integration': MyIntegration,
};
Для более сложных интеграций вы можете добавить:
- Аутентификацию OAuth
- Поддержку вебхуков
- Кэширование данных
- Обработку ошибок
- Конфигурацию через интерфейс Homarr
Оптимизация производительности
1. Настройка ресурсов Docker
Для оптимизации производительности Homarr:
- Откройте
docker-compose.yml - Добавьте ограничения ресурсов:
services:
homarr:
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.5'
memory: 512M
Эти настройки ограничивают использование ресурсов контейнером, что предотвращает его влияние на другие сервисы на хосте.
2. Кэширование
Для включения кэширования:
- В настройках Homarr перейдите в "Производительность"
- Включите кэширование для статических ресурсов
- Настройте время жизни кэша
- Перезапустите сервис
Homarr использует встроенное кэширование, но для крупных развертываний можно настроить внешнее кэширование:
services:
redis:
image: redis:7-alpine
restart: always
ports:
- "6379:6379"
volumes:
- redis_data:/data
homarr:
image: ghcr.io/ajnart/homarr:latest
environment:
- REDIS_URL=redis://redis:6379
depends_on:
- redis
volumes:
redis_data:
3. Оптимизация базы данных
Homarr использует SQLite по умолчанию. Для больших развертываний рекомендуется перейти на PostgreSQL:
services:
postgres:
image: postgres:14
environment:
POSTGRES_USER: homarr
POSTGRES_PASSWORD: yourpassword
POSTGRES_DB: homarr
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
homarr:
image: ghcr.io/ajnart/homarr:latest
environment:
- DATABASE_URL=postgresql://homarr:yourpassword@postgres:5432/homarr
depends_on:
- postgres
volumes:
postgres_data:
PostgreSQL обеспечит лучшую производительность при большом количестве данных и одновременном подключении множества пользователей.
4. Мониторинг производительности
Для мониторинга производительности Homarr:
- Добавьте виджет системных метрик
- Настройте уведомления о высокой загрузке
- Периодически проверяйте логи сервиса:
docker logs homarr
Для более детального мониторинга можно использовать специализированные инструменты:
- Prometheus + Grafana для сбора и визуализации метрик
- Datadog для комплексного мониторинга
- ELK Stack (Elasticsearch, Logstash, Kibana) для анализа логов
Пример конфигурации для Prometheus:
# prometheus.yml
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'homarr'
static_configs:
- targets: ['homarr:7575']
metrics_path: '/metrics'
Заключение
Homarr предоставляет мощные возможности для создания персональной панели управления вашим homelab. В этом руководстве мы рассмотрели установку, базовую настройку, кастомизацию интерфейса, работу с сервисами и интеграциями, а также оптимизацию производительности. Используя эти знания, вы можете создать удобную и функциональную панель, которая будет соответствовать вашим требованиям и предпочтениям.
Помните, что Homarr активно развивается, поэтому следите за обновлениями и новыми возможностями, которые появляются в новых версиях. Удачи в настройке вашего персонального cockpit!
Дополнительные ресурсы: