mirror of
https://github.com/Xevion/HATray.git
synced 2025-12-06 01:15:11 -06:00
chore: update readme
This commit is contained in:
170
README.md
170
README.md
@@ -1,156 +1,20 @@
|
|||||||
# HASS Tray - Windows Service
|
# HATray
|
||||||
|
|
||||||
A minimal Go application that can run as a Windows service with JSON logging.
|
|
||||||
|
|
||||||
## Features
|
### Feature Targets
|
||||||
|
|
||||||
- Runs as a Windows service
|
- [ ] Easy MSI Installer/Uninstaller
|
||||||
- JSON logging with debug level
|
- [ ] Structured JSON Logging, Configurable
|
||||||
- Logs to `current.log` in the same directory as the executable
|
- [ ] One-command/click Install, Background Service
|
||||||
- Heartbeat logging every 5 seconds
|
- [ ] Tray Icon, Tray Menu
|
||||||
- Interactive mode for testing
|
- [ ] Cross-platform Support (Linux, Windows)
|
||||||
|
- [ ] Easy Development Testing
|
||||||
## Requirements
|
- [ ] Go Tests
|
||||||
|
- [ ] Conventional Commits
|
||||||
- Go 1.21 or later
|
- [ ] GitHub Actions
|
||||||
- Windows operating system
|
- [ ] MSI Packages
|
||||||
- Administrator privileges (for service installation)
|
- [ ] Testing, Linting, Formatting
|
||||||
- Task (taskfile.dev) - modern task runner
|
- [ ] Automatic Releases (GitHub Releases, Winget)
|
||||||
|
- [ ] Per-commit Artifacts
|
||||||
## Installing Task
|
- [ ] Winget Package Publishing
|
||||||
|
- [ ] README Documentation Links
|
||||||
Download and install Task from [taskfile.dev](https://taskfile.dev/installation/):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Using Chocolatey
|
|
||||||
choco install task
|
|
||||||
|
|
||||||
# Using Scoop
|
|
||||||
scoop install task
|
|
||||||
|
|
||||||
# Using winget
|
|
||||||
winget install Task.Task
|
|
||||||
|
|
||||||
# Or download directly from GitHub releases
|
|
||||||
```
|
|
||||||
|
|
||||||
## Building
|
|
||||||
|
|
||||||
```bash
|
|
||||||
task build
|
|
||||||
```
|
|
||||||
|
|
||||||
This will create `hass-tray.exe` in the current directory.
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
task install
|
|
||||||
```
|
|
||||||
|
|
||||||
This will:
|
|
||||||
1. Build the application
|
|
||||||
2. Copy the executable to `%APPDATA%\hass-tray\`
|
|
||||||
3. Display instructions for installing as a Windows service
|
|
||||||
|
|
||||||
To install as a Windows service (run as Administrator):
|
|
||||||
|
|
||||||
```cmd
|
|
||||||
task service-install
|
|
||||||
```
|
|
||||||
|
|
||||||
Or manually:
|
|
||||||
```cmd
|
|
||||||
sc create hass-tray binPath= "%APPDATA%\hass-tray\hass-tray.exe" start= auto
|
|
||||||
sc description hass-tray "Home Assistant Tray Service"
|
|
||||||
sc start hass-tray
|
|
||||||
```
|
|
||||||
|
|
||||||
## Uninstallation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
task uninstall
|
|
||||||
```
|
|
||||||
|
|
||||||
This will:
|
|
||||||
1. Stop and remove the Windows service
|
|
||||||
2. Delete the executable from the AppData directory
|
|
||||||
3. Remove the installation directory
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
To run the application in interactive mode for testing:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
task run
|
|
||||||
```
|
|
||||||
|
|
||||||
This will run the application directly and show debug output in the console.
|
|
||||||
|
|
||||||
## Logging
|
|
||||||
|
|
||||||
The application logs JSON-formatted messages to `current.log` in the same directory as the executable. Log entries include:
|
|
||||||
|
|
||||||
- Timestamp in RFC3339 format
|
|
||||||
- Log level (debug)
|
|
||||||
- Message content
|
|
||||||
- Service name
|
|
||||||
|
|
||||||
Example log entry:
|
|
||||||
```json
|
|
||||||
{"timestamp":"2024-01-15T10:30:00Z","level":"debug","message":"Service heartbeat","service":"hass-tray"}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Service Management
|
|
||||||
|
|
||||||
Once installed as a service, you can manage it using Task commands:
|
|
||||||
|
|
||||||
- Install service: `task service-install` (requires admin)
|
|
||||||
- Uninstall service: `task service-uninstall` (requires admin)
|
|
||||||
- Start service: `task service-start`
|
|
||||||
- Stop service: `task service-stop`
|
|
||||||
- Check status: `task service-status`
|
|
||||||
|
|
||||||
Or using standard Windows commands:
|
|
||||||
|
|
||||||
- Start: `sc start hass-tray`
|
|
||||||
- Stop: `sc stop hass-tray`
|
|
||||||
- Status: `sc query hass-tray`
|
|
||||||
- Delete: `sc delete hass-tray`
|
|
||||||
|
|
||||||
## Available Task Commands
|
|
||||||
|
|
||||||
- `task build` - Build the application
|
|
||||||
- `task install` - Build and copy to AppData directory
|
|
||||||
- `task uninstall` - Remove service and files
|
|
||||||
- `task clean` - Remove build artifacts
|
|
||||||
- `task run` - Build and run in interactive mode
|
|
||||||
- `task test` - Run tests
|
|
||||||
- `task fmt` - Format Go code
|
|
||||||
- `task vet` - Vet Go code
|
|
||||||
- `task deps` - Download and tidy dependencies
|
|
||||||
- `task service-install` - Install as Windows service (requires admin)
|
|
||||||
- `task service-uninstall` - Uninstall Windows service (requires admin)
|
|
||||||
- `task service-start` - Start the service
|
|
||||||
- `task service-stop` - Stop the service
|
|
||||||
- `task service-status` - Check service status
|
|
||||||
- `task dev` - Complete development workflow
|
|
||||||
- `task` - Show all available tasks
|
|
||||||
|
|
||||||
## Development
|
|
||||||
|
|
||||||
The application uses the `golang.org/x/sys/windows/svc` package for Windows service functionality. The main service logic is in the `Execute` method of the `myservice` struct.
|
|
||||||
|
|
||||||
When running in interactive mode (not as a service), the application will run the same logic but in the foreground with console output.
|
|
||||||
|
|
||||||
## Why Task instead of Make?
|
|
||||||
|
|
||||||
Task provides several advantages over Make:
|
|
||||||
|
|
||||||
- **Better Windows support** - Native Windows compatibility
|
|
||||||
- **YAML configuration** - More readable and maintainable
|
|
||||||
- **Cross-platform** - Works on Windows, macOS, and Linux
|
|
||||||
- **Dependencies** - Better task dependency management
|
|
||||||
- **Variables** - More flexible variable handling
|
|
||||||
- **Parallel execution** - Built-in support for parallel task execution
|
|
||||||
- **Silent mode** - Better control over output verbosity
|
|
||||||
Reference in New Issue
Block a user