Skip to content

Commit e39d4ca

Browse files
committed
docs: simplify README with link to documentation site
Move detailed documentation to jvp.jimyag.com, keep README concise with quick start guide and feature overview.
1 parent e258502 commit e39d4ca

File tree

2 files changed

+45
-525
lines changed

2 files changed

+45
-525
lines changed

README.md

Lines changed: 22 additions & 262 deletions
Original file line numberDiff line numberDiff line change
@@ -6,292 +6,52 @@ English | [中文](README_CN.md)
66

77
## Introduction
88

9-
JVP is a virtualization platform based on QEMU/KVM and libvirt, providing complete virtual machine lifecycle management. It supports creating, managing, and monitoring virtual machine instances through RESTful API and a modern web management interface.
9+
JVP is a virtualization platform based on QEMU/KVM and libvirt, providing complete virtual machine lifecycle management through RESTful API and a modern web interface.
1010

11-
![Node Management](docs/static/nodes.png)
11+
📖 **Documentation**: [https://jvp.jimyag.com](https://jvp.jimyag.com)
1212

1313
![Instance List](docs/static/instance.png)
1414

15-
![Instance Details](docs/static/instance-detail.png)
15+
## Features
1616

17-
![VNC Console](docs/static/instance-vnc.png)
17+
- **Instance Management** - Create, start, stop, snapshot VMs with cloud-init support
18+
- **Multi-Node Support** - Manage multiple libvirt nodes (local and remote)
19+
- **Storage Management** - Manage storage pools and volumes
20+
- **Snapshot & Template** - Create snapshots, register and manage VM templates
21+
- **Modern Web UI** - React-based interface with VNC and Serial console
1822

19-
![Serial Console](docs/static/instance-console.png)
23+
## Quick Start
2024

21-
![Storage Pool List](docs/static/storage-pool.png)
22-
23-
![Storage Pool Details](docs/static/storage-pool-detail.png)
24-
25-
![Template Management](docs/static/template.png)
26-
27-
![Snapshot Management](docs/static/snapshot.png)
28-
29-
## Core Features
30-
31-
### Instance Management
32-
33-
- **Create Instances**: Customize CPU, memory, and disk, support bridge or NAT networking
34-
- Integrated cloud-init, supports user data and SSH public key injection
35-
- **Query Instances**: Query by node/ID, returns network interfaces, MAC, IP, multiple IPs, autostart flag, start time
36-
- **Lifecycle Management**: Start, stop, reboot, delete (optionally delete volumes)
37-
- **Modify Instance Properties**: Adjust CPU, memory, name, autostart
38-
- **Password Reset**: Asynchronous reset based on guest-agent (background execution), with virt-customize fallback
39-
- **Remote Console**: Support VNC/Serial console
40-
41-
### Nodes and Storage
42-
43-
- **Multi-Node Management**: Support managing multiple libvirt nodes (local and remote) simultaneously, building distributed virtualization clusters
44-
- **Local Node**: Automatically creates `local (qemu:///system)` node
45-
- **Remote Nodes**: Add remote nodes via libvirt URI (e.g., `qemu+ssh://user@host/system`)
46-
- **Node Types**: Support compute, storage, hybrid, and other node types
47-
- **Node Operations**: Add, delete, enable, disable nodes
48-
- **Node Summary**: View hardware information for each node (CPU/memory/NUMA/virtualization capabilities, etc.)
49-
- **Storage Pool Management**: Manage storage pools by node, list/create/start/stop/delete storage pools, view storage pool usage
50-
- **Storage Volume Management**: List volumes by node and storage pool, create volumes, view volume details (capacity, allocation, format), delete volumes
51-
52-
### Snapshot Management
53-
54-
- **Create Snapshots**: Create snapshots for virtual machines, support including memory state
55-
- **List Snapshots**: Query snapshot list by node and virtual machine
56-
- **Snapshot Details**: View detailed snapshot information (creation time, state, disk information, etc.)
57-
- **Revert Snapshots**: Restore virtual machine to specified snapshot state
58-
- **Delete Snapshots**: Delete snapshots that are no longer needed, free up storage space
59-
- **Snapshot Types**: Support internal snapshots (qcow2) and external snapshots (all formats)
60-
61-
### Template Management
62-
63-
- **Register Templates**: Download cloud images from URL or import from local files
64-
- **List Templates**: View all available virtual machine templates
65-
- **Template Details**: View template metadata (operating system, size, source, etc.)
66-
- **Delete Templates**: Delete templates that are no longer used
67-
- **Template Types**: Support cloud image templates (Ubuntu, Debian, Alpine, etc.) and custom templates exported from snapshots
68-
69-
### Key Pair Management
70-
71-
- **Create Key Pairs**: Support RSA and ED25519 algorithms
72-
- **Import Key Pairs**: Import existing public keys
73-
- **Query Key Pairs**: Support querying by ID, name, etc.
74-
- **Delete Key Pairs**: Delete key pairs that are no longer used
75-
- **Auto Injection**: Automatically inject SSH public keys when creating instances
76-
77-
### Web Management Interface
78-
79-
- **Modern UI**: Responsive web interface built with React + Vite + Tailwind CSS
80-
- **Real-time Monitoring**: View instance status, resource usage, network information, etc.
81-
- **Remote Console**: Integrated VNC and Serial console, support graphical and text interface access
82-
- **Unified Management**: Manage all resources (instances, nodes, storage, templates, snapshots, key pairs) through web interface
83-
84-
## Requirements
85-
86-
### Required Tools
87-
88-
| Tool | Purpose |
89-
| ------------------------------ | ---------------------------------------------------- |
90-
| **libvirt** | Virtualization management core (libvirtd daemon) |
91-
| **virsh** | Execute qemu-agent-command |
92-
| **qemu-img** | Disk image operations (create, resize, convert, snapshot) |
93-
| **genisoimage** or **mkisofs** | Generate cloud-init ISO |
94-
| **ssh** | Remote node connection (VNC/serial proxy, file transfer) |
95-
96-
### Optional Tools
97-
98-
| Tool | Purpose |
99-
| ------------------ | ------------------------------------------------------ |
100-
| **wget** | Download template images (preferred) |
101-
| **curl** | Download template images (fallback when wget unavailable) |
102-
| **ip** | Query ARP neighbor table for VM IP (preferred) |
103-
| **arp** | Query ARP table for VM IP (fallback when ip unavailable) |
104-
| **virt-customize** | Reset VM password (fallback method) |
105-
| **socat** | VNC/serial forwarding for remote nodes (required on remote host) |
106-
107-
### Additional Requirements for Remote Nodes
108-
109-
If using remote libvirt nodes (e.g., `qemu+ssh://user@host/system`), the remote host needs:
110-
111-
- **ssh** service
112-
- **socat** (for VNC/serial console)
113-
- **genisoimage** or **mkisofs** (for cloud-init ISO generation)
114-
- **find**, **cat**, **mkdir**, **rm** (basic shell commands)
115-
116-
### Installation Commands
117-
118-
**Debian/Ubuntu:**
119-
120-
```bash
121-
apt install libvirt-daemon-system qemu-utils genisoimage wget curl openssh-client libguestfs-tools socat
122-
```
123-
124-
**RHEL/CentOS/Fedora:**
125-
126-
```bash
127-
dnf install libvirt qemu-img genisoimage wget curl openssh-clients libguestfs-tools socat
128-
```
129-
130-
## How to Use
131-
132-
### Option 1: Docker Deployment (Recommended)
133-
134-
Docker deployment runs libvirtd inside the container, completely taking over the host's virtualization environment.
135-
136-
**1. Stop host libvirt services**
25+
### Docker (Recommended)
13726

13827
```bash
28+
# Stop host libvirt services
13929
sudo systemctl stop libvirtd libvirtd.socket virtlogd virtlogd.socket
14030
sudo systemctl disable libvirtd libvirtd.socket virtlogd virtlogd.socket
141-
```
142-
143-
**2. Create data directory**
14431

145-
```bash
32+
# Create data directory
14633
sudo mkdir -p /var/lib/jvp
147-
```
148-
149-
**3. Start the container**
15034

151-
```bash
152-
# Using docker-compose
35+
# Start container
15336
docker compose up -d
154-
155-
# Or using docker run directly
156-
docker run -d \
157-
--name jvp \
158-
--hostname jvp \
159-
--privileged \
160-
--network host \
161-
--cgroup host \
162-
--device /dev/kvm:/dev/kvm \
163-
--device /dev/net/tun:/dev/net/tun \
164-
--device /dev/vhost-net:/dev/vhost-net \
165-
-v /var/lib/libvirt:/var/lib/libvirt \
166-
-v /var/run/libvirt:/var/run/libvirt \
167-
-v /etc/libvirt:/etc/libvirt \
168-
-v /var/lib/jvp:/var/lib/jvp \
169-
-e TZ=Asia/Shanghai \
170-
-e JVP_ADDRESS=0.0.0.0:7777 \
171-
-e JVP_DATA_DIR=/var/lib/jvp \
172-
-e LIBVIRT_URI=qemu:///system \
173-
--restart unless-stopped \
174-
ghcr.io/jimyag/jvp:latest
17537
```
17638

177-
**4. Access the Web interface**
39+
Access: `http://<server-ip>:7777`
17840

179-
```
180-
http://<server-ip>:7777
181-
```
182-
183-
### Option 2: Binary Deployment
184-
185-
**1. Download the binary**
186-
187-
Download the binary for your system from [GitHub Releases](https://github.com/jimyag/jvp/releases).
188-
189-
```bash
190-
# Create directory
191-
sudo mkdir -p /opt/jvp
192-
193-
# Download and extract (example for linux amd64)
194-
wget https://github.com/jimyag/jvp/releases/latest/download/jvp_linux_amd64.tar.gz
195-
tar -xzf jvp_linux_amd64.tar.gz -C /opt/jvp
196-
```
197-
198-
**2. Create systemd service**
199-
200-
```bash
201-
sudo tee /etc/systemd/system/jvp.service > /dev/null <<EOF
202-
[Unit]
203-
Description=JVP - jimyag's virtualization platform
204-
After=network.target libvirtd.service
205-
Wants=network.target
206-
207-
[Service]
208-
User=root
209-
Group=root
210-
Restart=always
211-
ExecStart=/opt/jvp/jvp
212-
RestartSec=2
213-
214-
[Install]
215-
WantedBy=multi-user.target
216-
EOF
217-
```
41+
### Binary
21842

219-
**3. Start the service**
43+
Download from [GitHub Releases](https://github.com/jimyag/jvp/releases) and run:
22044

22145
```bash
222-
sudo systemctl daemon-reload
223-
sudo systemctl enable jvp
224-
sudo systemctl start jvp
46+
./jvp
22547
```
22648

227-
**4. Access the Web interface**
228-
229-
```
230-
http://<server-ip>:7777
231-
```
232-
233-
### Option 3: Build and Run Locally
234-
235-
**1. Build the project**
236-
237-
```bash
238-
# Build complete binary file including frontend
239-
task build
240-
```
241-
242-
**2. Run the service**
243-
244-
```bash
245-
# Run JVP service (default port 7777)
246-
./bin/jvp
247-
```
248-
249-
**3. Access the Web interface**
250-
251-
After building, the frontend is embedded in the binary file. After starting the service, access:
252-
253-
```
254-
http://localhost:7777
255-
```
256-
257-
### Local Debugging (Docker)
258-
259-
```bash
260-
# Build local debug image
261-
task debug-image
262-
263-
# Modify image in docker-compose.yml to jvp:local, then start
264-
docker compose up -d
265-
```
266-
267-
## Future Plans
268-
269-
JVP is under continuous development. The following features are planned for future releases:
270-
271-
### User Experience Enhancements
272-
- **Internationalization (i18n)**: Support for multiple languages (Chinese, English, etc.)
273-
- **Dark/Light Theme Toggle**: Theme switching with automatic system theme detection
274-
- **User Onboarding**: First-time user guide, feature tooltips, quick start wizard
275-
276-
### Network Feature Enhancements
277-
- **Multiple Network Configurations**: Bridge, NAT, virtual networks, passthrough networks, VLAN, network QoS, etc.
278-
- **Network Isolation**: Support for network isolation and multi-NIC bonding
279-
280-
### Device Passthrough Virtualization
281-
- **PCIe Device Passthrough**: GPU, network cards, NVMe, and other PCIe device passthrough
282-
- **USB Device Passthrough**: USB device passthrough and hot-plug support
283-
- **Disk Passthrough**: Physical disk, partition, and LVM logical volume passthrough
49+
## Documentation
28450

285-
### Windows Virtual Machine Support
286-
- **Windows Installation Support**: Windows ISO images, VirtIO driver integration
287-
- **Windows Optimization**: CPU mode optimization, clock synchronization, performance tuning
288-
- **Windows Tools Integration**: QEMU Guest Agent, automatic VirtIO driver installation
51+
For detailed installation guides, feature documentation, and API reference, visit:
28952

290-
For more details, please refer to the [Implementation Plan](docs/implement/implementation-plan.md).
53+
**[https://jvp.jimyag.com](https://jvp.jimyag.com)**
29154

292-
## Related Resources
55+
## License
29356

294-
- <https://www.voidking.com/dev-libvirt-create-vm/>
295-
- <https://sq.sf.163.com/blog/article/172808502565068800>
296-
- <https://shihai1991.github.io/openstack/2024/02/20/%E9%80%9A%E8%BF%87libvirt%E5%88%9B%E5%BB%BA%E8%99%9A%E6%8B%9F%E6%9C%BA/>
297-
- <https://www.baeldung.com/linux/qemu-uefi-boot> Boot qemu with UEFI
57+
[MIT](LICENSE)

0 commit comments

Comments
 (0)