SolarSync Power Manager

Automatically run household appliances (pool pump, EV charger, washing machine, …) when your solar panels are producing surplus energy.

Built for Raspberry Pi 4/5 (arm64), but runs on any Linux machine with Docker.

---

Features

• Live dashboard — solar production, grid draw, surplus, running appliances
• 24 h power chart — see where your energy went
• Smart scheduling — solar_only, solar_preferred, time_window, or manual per appliance
• Manual override — force any appliance on/off from the dashboard
• Multiple energy sources — KaKu P1 meter and/or SolarEdge cloud API
• Multiple plug types — KaKu ICS2000 smart plugs and Zigbee devices via Zigbee2MQTT
• Automatic updates — Watchtower polls ghcr.io and restarts containers on new releases
• HTTPS by default — Nginx with a self-signed certificate (or bring your own)
• mDNS — accessible at https://solarsync.local on your home network, no IP needed

---

Quick Install (Raspberry Pi)

curl -fsSL https://raw.githubusercontent.com/Mel-Raeven/SolarSync-Power-Manager/main/solarsync/scripts/install.sh | bash

No configuration needed. The script runs fully automatically:

1. Set the Pi's hostname to solarsync and enable mDNS (avahi-daemon)
2. Install Docker (if missing)
3. Clone this repository to ~/solarsync
4. Auto-generate all internal secrets (APP_KEY, INTERNAL_API_KEY, MQTT credentials)
5. Generate a self-signed TLS certificate (includes solarsync.local as a SAN)
6. Pull the latest images from ghcr.io and start all services

Open https://solarsync.local in your browser. The first time you log in with admin / admin, you will be prompted to set your own username and password before you can access anything. After that, follow the onboarding wizard to connect your energy source and smart plugs.

Note: solarsync.local works on any device on the same home network. macOS, iOS, Android, Linux, and Windows 10 (build 1809+) / Windows 11 all support mDNS natively — no extra software needed.

---

Manual Setup

1. Clone

git clone https://github.com/Mel-Raeven/SolarSync-Power-Manager.git ~/solarsync
cd ~/solarsync/solarsync

2. Configure

cp .env.example .env
nano .env

The .env file only contains infrastructure-level settings. There are only a few you may want to change:

Variable	Description
ALLOWED_ORIGINS	Hostname(s) you use to access the dashboard (e.g. https://solarsync.local)
POLL_INTERVAL_SECONDS	How often the solar engine runs (default: 300)

Everything else is handled automatically:

• APP_KEY — generated by the install script
• INTERNAL_API_KEY — generated by the install script
• MQTT_USERNAME / MQTT_PASSWORD — auto-generated random credentials
• Web login credentials — set by the user on first login (default: admin / admin, forced to change)
• Energy source, hub credentials, and appliances — configured through the onboarding wizard in the web interface

If running without the install script, generate secrets manually: openssl rand -base64 32 for APP_KEY, openssl rand -hex 32 for INTERNAL_API_KEY.

3. Generate TLS certificate

bash scripts/generate-certs.sh

4. Start

Development (builds images locally):

docker compose up -d

Production (pulls from ghcr.io, includes Watchtower):

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Optional: Zigbee devices (Zigbee2MQTT)

If you have a Zigbee USB adapter, start the Zigbee2MQTT service:

docker compose --profile zigbee up -d

Edit zigbee2mqtt/configuration.yaml to set your USB device path and MQTT credentials.

---

Updating

Watchtower automatically checks ghcr.io every hour and restarts containers when a new image is available. No manual action required.

To update manually:

cd ~/solarsync
git pull
docker compose -f solarsync/docker-compose.yml -f solarsync/docker-compose.prod.yml pull
docker compose -f solarsync/docker-compose.yml -f solarsync/docker-compose.prod.yml up -d

---

Architecture

Browser ──HTTPS──► Nginx (443)
                     │
          ┌──────────┴──────────┐
          │                     │
     Laravel (PHP-FPM)     FastAPI (Python)
     UI + Auth              Solar engine + REST API
          │                     │
          └──────────┬──────────┘
                     │
               SQLite (volume)

  + Mosquitto (MQTT broker)
  + Zigbee2MQTT (optional, --profile zigbee)
  + Watchtower (auto-updates from ghcr.io)

Layer	Technology
Frontend	Laravel 11 + Blade + Tailwind CSS
Backend API	Python + FastAPI
Scheduler	APScheduler (inside FastAPI)
Database	SQLite via SQLModel
Auth	Laravel Sanctum (single household credential)
API Auth	Shared secret header (X-Internal-API-Key) between Laravel and FastAPI
MQTT	Eclipse Mosquitto (password-protected, internal network only)
Container	Docker Compose (arm64)
TLS	Nginx reverse proxy + self-signed cert
Auto-update	Watchtower

---

Releasing a New Version

1. Merge changes to main
2. Create and push a version tag:

   git tag v1.2.3
   git push origin v1.2.3

3. GitHub Actions builds arm64 Docker images and pushes them to ghcr.io
4. Watchtower on your Pi picks up the new latest tag within the hour

---

Acknowledgements

• KaKu core — original ICS2000 Python library

---

License

Copyright (c) 2026. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, modification, or use of this software, in whole or in part, is strictly prohibited.