eduard256
16bef455ae
Features: - Multi-arch support (aarch64, amd64, armv7) - WebUI integration with Home Assistant - Ingress support for seamless integration - Automated builds via GitHub Actions - Comprehensive documentation (EN/RU) - Health check monitoring - Configurable through HA UI
275 lines
6.6 KiB
Markdown
275 lines
6.6 KiB
Markdown
# Home Assistant Add-on Installation Guide
|
|
|
|
This guide explains how to set up and publish the Strix Home Assistant Add-on.
|
|
|
|
## 📋 Overview
|
|
|
|
The add-on structure is ready and includes:
|
|
- ✅ `config.yaml` - Add-on configuration
|
|
- ✅ `Dockerfile` - Multi-arch Docker build
|
|
- ✅ `build.yaml` - Build configuration for aarch64/amd64/armv7
|
|
- ✅ `run.sh` - Startup script with HA integration
|
|
- ✅ `README.md` - User-facing documentation
|
|
- ✅ `DOCS.md` - Comprehensive usage guide
|
|
- ✅ `CHANGELOG.md` - Version history
|
|
- ✅ GitHub Actions workflow for automated builds
|
|
|
|
## 🚀 Quick Deployment
|
|
|
|
### Step 1: Enable GitHub Actions
|
|
|
|
The `.github/workflows/addon.yml` workflow will automatically:
|
|
1. Build binaries for all architectures (aarch64, amd64, armv7)
|
|
2. Create multi-arch Docker images
|
|
3. Push to GitHub Container Registry (ghcr.io)
|
|
4. Update version numbers on tags
|
|
|
|
No manual setup needed - just push to GitHub!
|
|
|
|
### Step 2: Create First Release
|
|
|
|
```bash
|
|
# Make sure all changes are committed
|
|
git add .
|
|
git commit -m "Add Home Assistant Add-on"
|
|
|
|
# Push to main branch (this will trigger a dev build)
|
|
git push origin main
|
|
|
|
# Create and push a version tag (this will trigger a release build)
|
|
git tag v1.0.0
|
|
git push origin v1.0.0
|
|
```
|
|
|
|
The GitHub Action will automatically build and publish Docker images to:
|
|
- `ghcr.io/eduard256/strix-addon-aarch64:latest`
|
|
- `ghcr.io/eduard256/strix-addon-amd64:latest`
|
|
- `ghcr.io/eduard256/strix-addon-armv7:latest`
|
|
|
|
### Step 3: Add Icons (Optional but Recommended)
|
|
|
|
Add these files to `homeassistant-addon/`:
|
|
- `icon.png` - 128x128px icon for the add-on store
|
|
- `logo.png` - 256x256px logo for the add-on page
|
|
|
|
Recommended: Simple owl or camera icon in Home Assistant style (blue/white theme).
|
|
|
|
### Step 4: Test Installation
|
|
|
|
After the GitHub Action completes:
|
|
|
|
1. In Home Assistant, go to **Supervisor** → **Add-on Store**
|
|
2. Click **⋮** (menu) → **Repositories**
|
|
3. Add: `https://github.com/eduard256/Strix`
|
|
4. Find "Strix Camera Discovery" in the store
|
|
5. Click **Install**
|
|
6. Configure and start the add-on
|
|
7. Click **Open Web UI**
|
|
|
|
## 🔄 Updating the Add-on
|
|
|
|
### For New Features/Fixes
|
|
|
|
```bash
|
|
# Make your changes to the codebase
|
|
git add .
|
|
git commit -m "feat: add new feature"
|
|
git push origin main
|
|
```
|
|
|
|
The dev build will automatically trigger, creating images tagged with `dev-<git-hash>`.
|
|
|
|
### For New Releases
|
|
|
|
```bash
|
|
# Update version in homeassistant-addon/config.yaml
|
|
sed -i 's/^version:.*/version: "1.1.0"/' homeassistant-addon/config.yaml
|
|
|
|
# Update CHANGELOG.md
|
|
# Add new version section
|
|
|
|
# Commit and tag
|
|
git add homeassistant-addon/config.yaml homeassistant-addon/CHANGELOG.md
|
|
git commit -m "release: v1.1.0"
|
|
git tag v1.1.0
|
|
git push origin main
|
|
git push origin v1.1.0
|
|
```
|
|
|
|
The release build will automatically create versioned images.
|
|
|
|
## 📦 Manual Build (Optional)
|
|
|
|
If you need to build locally for testing:
|
|
|
|
```bash
|
|
# Build for your architecture
|
|
cd homeassistant-addon
|
|
|
|
# Build the Go binary
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
|
|
-ldflags="-s -w" \
|
|
-o strix \
|
|
../cmd/strix/main.go
|
|
|
|
# Copy required files
|
|
cp -r ../data .
|
|
cp -r ../webui .
|
|
|
|
# Build Docker image
|
|
docker build \
|
|
--build-arg BUILD_FROM=ghcr.io/home-assistant/amd64-base:3.20 \
|
|
-t strix-addon:test .
|
|
|
|
# Test the image
|
|
docker run --rm -p 4567:4567 strix-addon:test
|
|
```
|
|
|
|
## 🔧 Configuration Options
|
|
|
|
Users can configure the add-on through the Home Assistant UI:
|
|
|
|
### Default Configuration
|
|
```yaml
|
|
log_level: info
|
|
port: 4567
|
|
strict_validation: true
|
|
```
|
|
|
|
### Advanced Options
|
|
|
|
Edit `homeassistant-addon/config.yaml` to add more options:
|
|
|
|
```yaml
|
|
options:
|
|
log_level: info
|
|
port: 4567
|
|
strict_validation: true
|
|
# Add new options here
|
|
|
|
schema:
|
|
log_level: list(debug|info|warn|error)
|
|
port: port
|
|
strict_validation: bool
|
|
# Add new option schemas here
|
|
```
|
|
|
|
Then update `run.sh` to use the new options:
|
|
|
|
```bash
|
|
NEW_OPTION=$(bashio::config 'new_option')
|
|
export STRIX_NEW_OPTION="${NEW_OPTION}"
|
|
```
|
|
|
|
## 🌐 Publishing to Community
|
|
|
|
### Option 1: Keep as Custom Repository (Recommended for Start)
|
|
|
|
Users add your repository manually:
|
|
```
|
|
https://github.com/eduard256/Strix
|
|
```
|
|
|
|
**Pros:**
|
|
- Full control
|
|
- Faster updates
|
|
- No approval process
|
|
|
|
**Cons:**
|
|
- Users must add repository manually
|
|
- Not in official add-on store
|
|
|
|
### Option 2: Submit to Home Assistant Community Add-ons
|
|
|
|
To get listed in the official community store:
|
|
|
|
1. Follow Home Assistant Add-on guidelines:
|
|
https://developers.home-assistant.io/docs/add-ons/
|
|
|
|
2. Submit to Community Add-ons repository:
|
|
https://github.com/home-assistant/addons
|
|
|
|
3. Wait for review and approval
|
|
|
|
**Pros:**
|
|
- Official recognition
|
|
- Easier for users to find
|
|
- Auto-update support
|
|
|
|
**Cons:**
|
|
- Strict guidelines
|
|
- Review process
|
|
- Slower updates
|
|
|
|
## 📊 Monitoring Builds
|
|
|
|
Check GitHub Actions status:
|
|
```
|
|
https://github.com/eduard256/Strix/actions
|
|
```
|
|
|
|
View published images:
|
|
```
|
|
https://github.com/eduard256/Strix/pkgs/container/strix-addon-amd64
|
|
https://github.com/eduard256/Strix/pkgs/container/strix-addon-aarch64
|
|
https://github.com/eduard256/Strix/pkgs/container/strix-addon-armv7
|
|
```
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Build Fails
|
|
|
|
Check GitHub Actions logs for errors. Common issues:
|
|
- Go build errors → Fix in main codebase
|
|
- Docker build errors → Check Dockerfile
|
|
- Permission errors → Ensure GITHUB_TOKEN has required permissions
|
|
|
|
### Add-on Won't Install
|
|
|
|
- Verify config.yaml syntax
|
|
- Check Docker images are published to ghcr.io
|
|
- Ensure repository.yaml is in root directory
|
|
- Verify architecture support matches user's system
|
|
|
|
### Add-on Won't Start
|
|
|
|
Check add-on logs in Home Assistant:
|
|
- Go to add-on page → **Log** tab
|
|
- Look for startup errors
|
|
- Common issues:
|
|
- Port already in use
|
|
- Missing data files
|
|
- Permission errors
|
|
|
|
## 📚 Resources
|
|
|
|
- [Home Assistant Add-on Documentation](https://developers.home-assistant.io/docs/add-ons/)
|
|
- [Add-on Configuration](https://developers.home-assistant.io/docs/add-ons/configuration)
|
|
- [Add-on Testing](https://developers.home-assistant.io/docs/add-ons/testing)
|
|
- [GitHub Actions](https://docs.github.com/en/actions)
|
|
|
|
## ✅ Checklist
|
|
|
|
Before first release:
|
|
- [ ] All code tested and working
|
|
- [ ] Version set in config.yaml
|
|
- [ ] CHANGELOG.md updated
|
|
- [ ] Icons added (icon.png, logo.png)
|
|
- [ ] README.md reviewed
|
|
- [ ] DOCS.md reviewed
|
|
- [ ] GitHub Actions workflow tested
|
|
- [ ] Repository URL correct in config files
|
|
- [ ] Git tag created (v1.0.0)
|
|
- [ ] Docker images published to ghcr.io
|
|
- [ ] Test installation in Home Assistant
|
|
|
|
## 🎉 You're Ready!
|
|
|
|
Once you've completed the checklist above, your Home Assistant Add-on is ready for users!
|
|
|
|
Share it with the community:
|
|
- Home Assistant Forums
|
|
- Reddit r/homeassistant
|
|
- GitHub Discussions
|
|
- Discord servers
|