mirror of https://github.com/jetkvm/kvm.git
Compare commits
3 Commits
b09c715548
...
b0ec367761
| Author | SHA1 | Date |
|---|---|---|
Marc Brooks
|
b0ec367761 | |
Silke pilon
|
55fbd6c359 | |
|
Marc Brooks
|
00ef587eeb |
|
|
@ -0,0 +1,355 @@
|
|||
<div align="center">
|
||||
<img alt="JetKVM logo" src="https://jetkvm.com/logo-blue.png" height="28">
|
||||
|
||||
### Development Guide
|
||||
|
||||
[Discord](https://jetkvm.com/discord) | [Website](https://jetkvm.com) | [Issues](https://github.com/jetkvm/cloud-api/issues) | [Docs](https://jetkvm.com/docs)
|
||||
|
||||
[](https://twitter.com/jetkvm)
|
||||
|
||||
[](https://goreportcard.com/report/github.com/jetkvm/kvm)
|
||||
|
||||
</div>
|
||||
|
||||
# JetKVM Development Guide
|
||||
|
||||
Welcome to JetKVM development! This guide will help you get started quickly, whether you're fixing bugs, adding features, or just exploring the codebase.
|
||||
|
||||
## Get Started
|
||||
|
||||
### Prerequisites
|
||||
- **A JetKVM device** (for full development)
|
||||
- **[Go 1.24.4+](https://go.dev/doc/install)** and **[Node.js 22.15.0](https://nodejs.org/en/download/)**
|
||||
- **[Git](https://git-scm.com/downloads)** for version control
|
||||
- **[SSH access](https://jetkvm.com/docs/advanced-usage/developing#developer-mode)** to your JetKVM device
|
||||
|
||||
### Development Environment
|
||||
|
||||
**Recommended:** Development is best done on **Linux** or **macOS**.
|
||||
|
||||
If you're using Windows, we strongly recommend using **WSL (Windows Subsystem for Linux)** for the best development experience:
|
||||
- [Install WSL on Windows](https://docs.microsoft.com/en-us/windows/wsl/install)
|
||||
- [WSL Setup Guide](https://docs.microsoft.com/en-us/windows/wsl/setup/environment)
|
||||
|
||||
This ensures compatibility with shell scripts and build tools used in the project.
|
||||
|
||||
### Project Setup
|
||||
|
||||
1. **Clone the repository:**
|
||||
```bash
|
||||
git clone https://github.com/jetkvm/kvm.git
|
||||
cd kvm
|
||||
```
|
||||
|
||||
2. **Check your tools:**
|
||||
```bash
|
||||
go version && node --version
|
||||
```
|
||||
|
||||
3. **Find your JetKVM IP address** (check your router or device screen)
|
||||
|
||||
4. **Deploy and test:**
|
||||
```bash
|
||||
./dev_deploy.sh -r 192.168.1.100 # Replace with your device IP
|
||||
```
|
||||
|
||||
5. **Open in browser:** `http://192.168.1.100`
|
||||
|
||||
That's it! You're now running your own development version of JetKVM.
|
||||
|
||||
---
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Modify the UI
|
||||
|
||||
```bash
|
||||
cd ui
|
||||
npm install
|
||||
./dev_device.sh 192.168.1.100 # Replace with your device IP
|
||||
```
|
||||
|
||||
Now edit files in `ui/src/` and see changes live in your browser!
|
||||
|
||||
### Modify the backend
|
||||
|
||||
```bash
|
||||
# Edit Go files (config.go, web.go, etc.)
|
||||
./dev_deploy.sh -r 192.168.1.100 --skip-ui-build
|
||||
```
|
||||
|
||||
### Run tests
|
||||
|
||||
```bash
|
||||
./dev_deploy.sh -r 192.168.1.100 --run-go-tests
|
||||
```
|
||||
|
||||
### View logs
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.100
|
||||
tail -f /var/log/jetkvm.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Layout
|
||||
|
||||
```
|
||||
/kvm/
|
||||
├── main.go # App entry point
|
||||
├── config.go # Settings & configuration
|
||||
├── web.go # API endpoints
|
||||
├── ui/ # React frontend
|
||||
│ ├── src/routes/ # Pages (login, settings, etc.)
|
||||
│ └── src/components/ # UI components
|
||||
└── internal/ # Internal Go packages
|
||||
```
|
||||
|
||||
**Key files for beginners:**
|
||||
|
||||
- `web.go` - Add new API endpoints here
|
||||
- `config.go` - Add new settings here
|
||||
- `ui/src/routes/` - Add new pages here
|
||||
- `ui/src/components/` - Add new UI components here
|
||||
|
||||
---
|
||||
|
||||
## Development Modes
|
||||
|
||||
### Full Development (Recommended)
|
||||
|
||||
*Best for: Complete feature development*
|
||||
|
||||
```bash
|
||||
# Deploy everything to your JetKVM device
|
||||
./dev_deploy.sh -r <YOUR_DEVICE_IP>
|
||||
```
|
||||
|
||||
### Frontend Only
|
||||
|
||||
*Best for: UI changes without device*
|
||||
|
||||
```bash
|
||||
cd ui
|
||||
npm install
|
||||
./dev_device.sh <YOUR_DEVICE_IP>
|
||||
```
|
||||
|
||||
### Quick Backend Changes
|
||||
|
||||
*Best for: API or backend logic changes*
|
||||
|
||||
```bash
|
||||
# Skip frontend build for faster deployment
|
||||
./dev_deploy.sh -r <YOUR_DEVICE_IP> --skip-ui-build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Made Easy
|
||||
|
||||
### Check if everything is working
|
||||
|
||||
```bash
|
||||
# Test connection to device
|
||||
ping 192.168.1.100
|
||||
|
||||
# Check if JetKVM is running
|
||||
ssh root@192.168.1.100 ps aux | grep jetkvm
|
||||
```
|
||||
|
||||
### View live logs
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.100
|
||||
tail -f /var/log/jetkvm.log
|
||||
```
|
||||
|
||||
### Reset everything (if stuck)
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.100
|
||||
rm /userdata/kvm_config.json
|
||||
systemctl restart jetkvm
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Your Changes
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. Deploy your changes: `./dev_deploy.sh -r <IP>`
|
||||
2. Open browser: `http://<IP>`
|
||||
3. Test your feature
|
||||
4. Check logs: `ssh root@<IP> tail -f /var/log/jetkvm.log`
|
||||
|
||||
### Automated Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
./dev_deploy.sh -r <IP> --run-go-tests
|
||||
|
||||
# Frontend linting
|
||||
cd ui && npm run lint
|
||||
```
|
||||
|
||||
### API Testing
|
||||
|
||||
```bash
|
||||
# Test login endpoint
|
||||
curl -X POST http://<IP>/auth/password-local \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"password": "test123"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### "Build failed" or "Permission denied"
|
||||
|
||||
```bash
|
||||
# Fix permissions
|
||||
ssh root@<IP> chmod +x /userdata/jetkvm/bin/jetkvm_app_debug
|
||||
|
||||
# Clean and rebuild
|
||||
go clean -modcache
|
||||
go mod tidy
|
||||
make build_dev
|
||||
```
|
||||
|
||||
### "Can't connect to device"
|
||||
|
||||
```bash
|
||||
# Check network
|
||||
ping <IP>
|
||||
|
||||
# Check SSH
|
||||
ssh root@<IP> echo "Connection OK"
|
||||
```
|
||||
|
||||
### "Frontend not updating"
|
||||
|
||||
```bash
|
||||
# Clear cache and rebuild
|
||||
cd ui
|
||||
npm cache clean --force
|
||||
rm -rf node_modules
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Adding a New Feature
|
||||
|
||||
1. **Backend:** Add API endpoint in `web.go`
|
||||
2. **Config:** Add settings in `config.go`
|
||||
3. **Frontend:** Add UI in `ui/src/routes/`
|
||||
4. **Test:** Deploy and test with `./dev_deploy.sh`
|
||||
|
||||
### Code Style
|
||||
|
||||
- **Go:** Follow standard Go conventions
|
||||
- **TypeScript:** Use TypeScript for type safety
|
||||
- **React:** Keep components small and reusable
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
export LOG_TRACE_SCOPES="jetkvm,cloud,websocket,native,jsonrpc"
|
||||
|
||||
# Frontend development
|
||||
export JETKVM_PROXY_URL="ws://<IP>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
1. **Check logs first:** `ssh root@<IP> tail -f /var/log/jetkvm.log`
|
||||
2. **Search issues:** [GitHub Issues](https://github.com/jetkvm/kvm/issues)
|
||||
3. **Ask on Discord:** [JetKVM Discord](https://jetkvm.com/discord)
|
||||
4. **Read docs:** [JetKVM Documentation](https://jetkvm.com/docs)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
### Ready to contribute?
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Test thoroughly
|
||||
5. Submit a pull request
|
||||
|
||||
### Before submitting:
|
||||
|
||||
- [ ] Code works on device
|
||||
- [ ] Tests pass
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Documentation updated (if needed)
|
||||
|
||||
---
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Performance Profiling
|
||||
|
||||
```bash
|
||||
# Enable profiling
|
||||
go build -o bin/jetkvm_app -ldflags="-X main.enableProfiling=true" cmd/main.go
|
||||
|
||||
# Access profiling
|
||||
curl http://<IP>:6060/debug/pprof/
|
||||
```
|
||||
### Advanced Environment Variables
|
||||
|
||||
```bash
|
||||
# Enable trace logging (useful for debugging)
|
||||
export LOG_TRACE_SCOPES="jetkvm,cloud,websocket,native,jsonrpc"
|
||||
|
||||
# For frontend development
|
||||
export JETKVM_PROXY_URL="ws://<JETKVM_IP>"
|
||||
|
||||
# Enable SSL in development
|
||||
export USE_SSL=true
|
||||
```
|
||||
|
||||
### Configuration Management
|
||||
|
||||
The application uses a JSON configuration file stored at `/userdata/kvm_config.json`.
|
||||
|
||||
#### Adding New Configuration Options
|
||||
|
||||
1. **Update the Config struct in `config.go`:**
|
||||
|
||||
```go
|
||||
type Config struct {
|
||||
// ... existing fields
|
||||
NewFeatureEnabled bool `json:"new_feature_enabled"`
|
||||
}
|
||||
```
|
||||
|
||||
2. **Update the default configuration:**
|
||||
|
||||
```go
|
||||
var defaultConfig = &Config{
|
||||
// ... existing defaults
|
||||
NewFeatureEnabled: false,
|
||||
}
|
||||
```
|
||||
|
||||
3. **Add migration logic if needed for existing installations**
|
||||
|
||||
|
||||
---
|
||||
|
||||
**Happy coding!**
|
||||
|
||||
For more information, visit the [JetKVM Documentation](https://jetkvm.com/docs) or join our [Discord Server](https://jetkvm.com/discord).
|
||||
|
|
@ -37,7 +37,9 @@ JetKVM is written in Go & TypeScript. with some bits and pieces written in C. An
|
|||
|
||||
The project contains two main parts, the backend software that runs on the KVM device and the frontend software that is served by the KVM device, and also the cloud.
|
||||
|
||||
For most of local device development, all you need is to use the `./dev_deploy.sh` script. It will build the frontend and backend and deploy them to the local KVM device. Run `./dev_deploy.sh --help` for more information.
|
||||
For comprehensive development information, including setup, testing, debugging, and contribution guidelines, see **[DEVELOPMENT.md](DEVELOPMENT.md)**.
|
||||
|
||||
For quick device development, use the `./dev_deploy.sh` script. It will build the frontend and backend and deploy them to the local KVM device. Run `./dev_deploy.sh --help` for more information.
|
||||
|
||||
## Backend
|
||||
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ type NetworkInterfaceOptions struct {
|
|||
DefaultHostname string
|
||||
OnStateChange func(state *NetworkInterfaceState)
|
||||
OnInitialCheck func(state *NetworkInterfaceState)
|
||||
OnDhcpLeaseChange func(lease *udhcpc.Lease)
|
||||
OnDhcpLeaseChange func(lease *udhcpc.Lease, state *NetworkInterfaceState)
|
||||
OnConfigChange func(config *NetworkConfig)
|
||||
NetworkConfig *NetworkConfig
|
||||
}
|
||||
|
|
@ -94,7 +94,7 @@ func NewNetworkInterfaceState(opts *NetworkInterfaceOptions) (*NetworkInterfaceS
|
|||
_ = s.updateNtpServersFromLease(lease)
|
||||
_ = s.setHostnameIfNotSame()
|
||||
|
||||
opts.OnDhcpLeaseChange(lease)
|
||||
opts.OnDhcpLeaseChange(lease, s)
|
||||
},
|
||||
})
|
||||
|
||||
|
|
|
|||
|
|
@ -9,17 +9,32 @@ import (
|
|||
"github.com/beevik/ntp"
|
||||
)
|
||||
|
||||
var defaultNTPServers = []string{
|
||||
var defaultNTPServerIPs = []string{
|
||||
// These servers are known by static IP and as such don't need DNS lookups
|
||||
// These are from Google and Cloudflare since if they're down, the internet
|
||||
// is broken anyway
|
||||
"162.159.200.1", // time.cloudflare.com IPv4
|
||||
"162.159.200.123", // time.cloudflare.com IPv4
|
||||
"2606:4700:f1::1", // time.cloudflare.com IPv6
|
||||
"2606:4700:f1::123", // time.cloudflare.com IPv6
|
||||
"216.239.35.0", // time.google.com IPv4
|
||||
"216.239.35.4", // time.google.com IPv4
|
||||
"216.239.35.8", // time.google.com IPv4
|
||||
"216.239.35.12", // time.google.com IPv4
|
||||
"2001:4860:4806::", // time.google.com IPv6
|
||||
"2001:4860:4806:4::", // time.google.com IPv6
|
||||
"2001:4860:4806:8::", // time.google.com IPv6
|
||||
"2001:4860:4806:c::", // time.google.com IPv6
|
||||
}
|
||||
|
||||
var defaultNTPServerHostnames = []string{
|
||||
// should use something from https://github.com/jauderho/public-ntp-servers
|
||||
"time.apple.com",
|
||||
"time.aws.com",
|
||||
"time.windows.com",
|
||||
"time.google.com",
|
||||
"162.159.200.123", // time.cloudflare.com IPv4
|
||||
"2606:4700:f1::123", // time.cloudflare.com IPv6
|
||||
"0.pool.ntp.org",
|
||||
"1.pool.ntp.org",
|
||||
"2.pool.ntp.org",
|
||||
"3.pool.ntp.org",
|
||||
"time.cloudflare.com",
|
||||
"pool.ntp.org",
|
||||
}
|
||||
|
||||
func (t *TimeSync) queryNetworkTime(ntpServers []string) (now *time.Time, offset *time.Duration) {
|
||||
|
|
|
|||
|
|
@ -188,7 +188,7 @@ Orders:
|
|||
case "ntp":
|
||||
if syncMode.Ntp && syncMode.NtpUseFallback {
|
||||
t.l.Info().Msg("using NTP fallback")
|
||||
now, offset = t.queryNetworkTime(defaultNTPServers)
|
||||
now, offset = t.queryNetworkTime(defaultNTPServerIPs)
|
||||
if now != nil {
|
||||
t.l.Info().Str("source", "NTP fallback").Time("now", *now).Msg("time obtained")
|
||||
break Orders
|
||||
|
|
|
|||
9
main.go
9
main.go
|
|
@ -96,16 +96,25 @@ func Main() {
|
|||
if !config.AutoUpdateEnabled {
|
||||
return
|
||||
}
|
||||
|
||||
if isTimeSyncNeeded() || !timeSync.IsSyncSuccess() {
|
||||
logger.Debug().Msg("system time is not synced, will retry in 30 seconds")
|
||||
time.Sleep(30 * time.Second)
|
||||
continue
|
||||
}
|
||||
|
||||
if currentSession != nil {
|
||||
logger.Debug().Msg("skipping update since a session is active")
|
||||
time.Sleep(1 * time.Minute)
|
||||
continue
|
||||
}
|
||||
|
||||
includePreRelease := config.IncludePreRelease
|
||||
err = TryUpdate(context.Background(), GetDeviceID(), includePreRelease)
|
||||
if err != nil {
|
||||
logger.Warn().Err(err).Msg("failed to auto update")
|
||||
}
|
||||
|
||||
time.Sleep(1 * time.Hour)
|
||||
}
|
||||
}()
|
||||
|
|
|
|||
27
network.go
27
network.go
|
|
@ -15,7 +15,7 @@ var (
|
|||
networkState *network.NetworkInterfaceState
|
||||
)
|
||||
|
||||
func networkStateChanged() {
|
||||
func networkStateChanged(isOnline bool) {
|
||||
// do not block the main thread
|
||||
go waitCtrlAndRequestDisplayUpdate(true)
|
||||
|
||||
|
|
@ -37,6 +37,13 @@ func networkStateChanged() {
|
|||
networkState.GetFQDN(),
|
||||
}, true)
|
||||
}
|
||||
|
||||
// if the network is now online, trigger an NTP sync if still needed
|
||||
if isOnline && timeSync != nil && (isTimeSyncNeeded() || !timeSync.IsSyncSuccess()) {
|
||||
if err := timeSync.Sync(); err != nil {
|
||||
logger.Warn().Str("error", err.Error()).Msg("unable to sync time on network state change")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func initNetwork() error {
|
||||
|
|
@ -48,13 +55,13 @@ func initNetwork() error {
|
|||
NetworkConfig: config.NetworkConfig,
|
||||
Logger: networkLogger,
|
||||
OnStateChange: func(state *network.NetworkInterfaceState) {
|
||||
networkStateChanged()
|
||||
networkStateChanged(state.IsOnline())
|
||||
},
|
||||
OnInitialCheck: func(state *network.NetworkInterfaceState) {
|
||||
networkStateChanged()
|
||||
networkStateChanged(state.IsOnline())
|
||||
},
|
||||
OnDhcpLeaseChange: func(lease *udhcpc.Lease) {
|
||||
networkStateChanged()
|
||||
OnDhcpLeaseChange: func(lease *udhcpc.Lease, state *network.NetworkInterfaceState) {
|
||||
networkStateChanged(state.IsOnline())
|
||||
|
||||
if currentSession == nil {
|
||||
return
|
||||
|
|
@ -64,7 +71,15 @@ func initNetwork() error {
|
|||
},
|
||||
OnConfigChange: func(networkConfig *network.NetworkConfig) {
|
||||
config.NetworkConfig = networkConfig
|
||||
networkStateChanged()
|
||||
networkStateChanged(false)
|
||||
|
||||
if mDNS != nil {
|
||||
_ = mDNS.SetListenOptions(networkConfig.GetMDNSMode())
|
||||
_ = mDNS.SetLocalNames([]string{
|
||||
networkState.GetHostname(),
|
||||
networkState.GetFQDN(),
|
||||
}, true)
|
||||
}
|
||||
},
|
||||
})
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue