🚧 Beta Notice

This application is currently in beta testing. It may contain bugs and its features are subject to change. All feedback and suggestions are welcome!

---

Hikvision Manager is a Spring Boot application designed to manage Hikvision Cameras, execute backup jobs, store backup history, and provide a UI for browsing and downloading recordings. It integrates with Hikvision ISAPI endpoints, schedules recording backups, stores metadata in PostgreSQL, and exposes a management dashboard. Also provides HTTP Live Streaming by HLS and FFmpeg.

📚 Documentation

• API Reference
• Screenshots
• Notifications

✨ Features

🎥 Live Preview

• Real-time RTSP stream viewing via HLS (HTTP Live Streaming)
• Channel switching (Main stream 101, Sub stream 102)
• Automatic session cleanup
• No transcoding (camera must provide H.264/H.265)

📼 Recordings Management

• Browse and search camera recordings
• Batch download multiple recordings
• Real-time download progress tracking with speed and ETA
• Download status monitoring (queued, downloading, completed, failed)
• Automatic file management and cleanup

💾 Backup System

• Automated scheduled backups
• Manual on-demand backups
• Live backup progress tracking
• Detailed logs for every backup
• Retention and cleanup policies
• Backup history with statistics

🔔 Notifications

Hikvision Manager supports multiple notification providers for backup alerts:

• NTFY - Self-hosted or public push notifications
• Discord - Embedded messages in Discord channels
• Generic Webhook - Integration with Zapier, n8n, Make.com, or custom APIs

🛠️ Camera Management

• Camera restart functionality
• System information display (model, firmware, serial number)
• Real-time status monitoring (uptime, temperature, CPU, memory)
• Storage information (HDD capacity, free space, usage percentage)
• Time and network settings access

🏗️ Architecture

Technology Stack

• Backend: Spring Boot 3.5.7, Java 24
• Cache: Caffeine
• Database: PostgreSQL 16
• Frontend: Thymeleaf, Bootstrap 5.3, JavaScript
• Streaming: FFmpeg, HLS.js
• Build Tool: Maven

Key Components

• ISAPI Integration: Direct communication with Hikvision camera API
• HLS Streaming: FFmpeg-based RTSP to HLS conversion
• Scheduled Tasks: Automated backups and cleanup
• Flyway automatic database migrations

🚀 Quick Start

You can run the application either locally without Docker or via Docker Compose (recommended).

⚙️ Local Development (without Docker)

Prerequisites

• JDK 24
• Maven
• PostgreSQL 16 installed locally
• FFmpeg installed locally

Installation

1. Clone the repository

git clone https://github.com/kCn3333/hikvision-manager.git
cd hikvision-manager

2. Make sure, you have a PostgreSQL installed

# Ubuntu/Debian
sudo apt install postgresql-16

3. Create Database

CREATE DATABASE camera_db;
CREATE USER postgres WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE camera_db TO postgres;

4. Make sure, you have a FFmpeg installed

# Ubuntu/Debian
sudo apt install ffmpeg

5. Configure environment variables

cp .env.example .env
# Edit .env with your camera credentials and settings

6. Start with Maven

mvn clean spring-boot:run

7. Access the application

http://localhost:8081

🐳 Docker Deployment (recommended)

1. Clone the repository

git clone https://github.com/kCn3333/hikvision-manager.git
cd hikvision-manager

2. Configure environment variables

cp .env.example .env
# Edit .env with your camera credentials and settings

3. Start services

docker compose --env-file .env up -d

4. Access the application

http://localhost:8081

logs:

docker logs -f hikvision-manager

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# --- Credentials ---
ADMIN_USERNAME=admin
ADMIN_PASSWORD={noop}your-secure-password

# --- Database ---
DB_PASSWORD=changeme

# --- Camera ---
CAMERA_IP=192.168.X.X
CAMERA_PORT=80
CAMERA_USERNAME=admin
CAMERA_PASSWORD=password
CAMERA_RTSP_PORT=554
TIMEZONE=UTC

🐳 Docker Image Available on Docker Hub

A prebuilt Docker image is available here: https://hub.docker.com/r/kcn333/hikvision-manager

Pull the image directly without cloning the repository:

docker pull kcn333/hikvision-manager:latest
docker run \
-p 8081:8081 \
--env-file .env \
kcn333/hikvision-manager:latest

🔒 HTTPS Configuration

By default, the application runs in HTTP mode. To enable HTTPS:

Use Nginx/Traefik for SSL termination:

1. Set HTTPS_ONLY=true in .env
2. Configure your reverse proxy (see nginx-reverse-proxy.conf.example)
3. Proxy requests to http://localhost:8081

The application will automatically:

• Set secure cookies
• Enforce HTTPS for all requests
• Set proper CORS headers

🎥 Camera Setup

Ensure your Hikvision camera has:

• ISAPI enabled (usually enabled by default)
• HTTP authentication set to Digest
• RTSP enabled on port 554

Supported Camera Models

Tested with:

• DS-2CD2xxx series
• DS-2DE series

📁 Project Structure

hikvision-manager/
├── src/main/
│   ├── java/com/kcn/hikvision-manager/
│   │   ├── client/               # HTTP client for Hikvision ISAPI
│   │   ├── config/               # Spring configuration classes
│   │   ├── controller/           # REST and MVC controllers
│   │   ├── domain/               # Domain models 
│   │   ├── dto/                  # API request/response DTOs
│   │   ├── entity/               # JPA entities mapped to PostgreSQL
│   │   ├── events/               # Domain events
│   │   ├── exception/            # Custom exceptions + global handler
│   │   ├── mapper/               # Mappers
│   │   ├── repository/           # Repositories for DB and Cache access
│   │   ├── service/              # Business logic and device operations
│   │   ├── scheduler/            # Scheduled backup jobs
│   │   └── util/                 # Utility classes
│   └── resources/
│       ├── db/migration/         # Flyway scripts
│       ├── static/
│       │   ├── css/              # CSS style
│       │   └── js/               # Java Script
│       ├── templates/            # Thymeleaf HTML templates
│       └── application.properties
├── Dockerfile
├── docker-compose.yml
└── README.md                     # this file

🔐 Security Considerations

• Always change default PostgreSQL and camera passwords
• Consider running behind reverse proxy (nginx, caddy)
• Enable HTTPS for production deployment
• Use VPN for remote access
• Restrict camera access to local network only
• Consider using VLANs to isolate camera network

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.