https://github.com/brezuicabogdan/homeassistant-docker-compose-control
**Home Assistant Docker Compose Control (DCC)** is a custom integration for Home Assistant that allows you to **monitor and manage Docker Compose deployments** directly from the Home Assistant UI.
https://github.com/brezuicabogdan/homeassistant-docker-compose-control
docker docker-compose home-assistant homeassistant-integration
Last synced: 2 months ago
JSON representation
**Home Assistant Docker Compose Control (DCC)** is a custom integration for Home Assistant that allows you to **monitor and manage Docker Compose deployments** directly from the Home Assistant UI.
- Host: GitHub
- URL: https://github.com/brezuicabogdan/homeassistant-docker-compose-control
- Owner: brezuicabogdan
- License: mit
- Created: 2025-03-01T17:04:43.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-01T18:15:22.000Z (over 1 year ago)
- Last Synced: 2025-03-01T18:32:55.678Z (over 1 year ago)
- Topics: docker, docker-compose, home-assistant, homeassistant-integration
- Language: Python
- Homepage: https://github.com/brezuicabogdan/homeassistant-docker-compose-control
- Size: 10.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Home Assistant Docker Compose Control (DCC)
## 📌 About
**Home Assistant Docker Compose Control (DCC)** is a custom integration for **Home Assistant** that allows you to **monitor and manage Docker Compose deployments** directly from the Home Assistant UI.
### 🔹 Features
- 🏠 **Device & Entity Creation**: Each Docker Compose project is registered as a device, with each service appearing as an entity.
- 📊 **Real-time Monitoring**: Track the status of each service (running, stopped, exited, etc.).
- 🩺 **Health Status & Attributes**: View additional container details like **health status, restart count, image version, and uptime**.
- 🔄 **Service Restarting**: Restart individual services directly from Home Assistant.
- 🛠 **Seamless Integration**: Works with Home Assistant's UI and automation engine.
---
## ❓ Why?
### **Bridging the Gap for Docker & Docker Compose Users**
Home Assistant users running **HassOS** benefit from a built-in **Supervisor** and **Add-ons**, allowing them to easily manage services like **ESPHome, Mosquitto, Zigbee2MQTT, and more** from within Home Assistant.
However, users running Home Assistant in **Docker** or **Docker Compose** **do not have access** to these built-in management tools. This results in:
- **Manual intervention** required to restart or update services.
- **No centralized way** to monitor running services.
- **Lack of Home Assistant integration**, making automation difficult.
This integration was created to **bring similar functionality to Docker Compose users**, allowing them to **monitor and manage their services** **directly from the Home Assistant UI**, just like HassOS users do with Add-ons and the Supervisor.
---
## 🚀 Installation
### **1️⃣ Install via HACS (Recommended)**
1. Open **HACS** in Home Assistant.
2. Go to **Integrations**.
3. Click the **+ (Add Integration)** button.
4. Search for **Docker Compose Control (DCC)** and install it.
5. Restart Home Assistant.
6. Go to **Settings → Devices & Services → Add Integration** and search for **Docker Compose Control**.
7. Provide the **Docker socket path** and the **Docker Compose file path** to set up the integration.
### **2️⃣ Manual Installation**
1. Download the latest release from the [**GitHub Releases**](https://github.com/brezuicabogdan/homeassistant-docker-compose-control) page.
2. Extract and place the `custom_components/dcc` folder inside your Home Assistant `config/custom_components/` directory.
```bash
mkdir -p /config/custom_components/dcc
cp -r dcc /config/custom_components/
```
3. Restart Home Assistant.
4. Add the integration via **Settings → Devices & Services**.
---
## ⚙️ Configuration
### 🛠️ Prerequisites
Before configuring this integration, ensure that:
- The **Docker socket** (`/var/run/docker.sock`) and the **Docker Compose file** (e.g., `/opt/home-automation/docker-compose.yml`) are correctly mapped into your Home Assistant container.
- Home Assistant has the necessary permissions to access the Docker socket.
#### 🔹 Example: Home Assistant in Docker Compose with Required Mappings
If you are running Home Assistant inside a **Docker container**, ensure your `docker-compose.yml` includes these volume mappings:
```yaml
docker-compose:
homeassistant:
image: "ghcr.io/home-assistant/home-assistant:latest"
container_name: homeassistant
restart: unless-stopped
volumes:
- /path/to/your/config:/config
- /var/run/docker.sock:/var/run/docker.sock # Map Docker socket
- /opt/home-automation/docker-compose.yml:/containers/docker-compose.yml # Map Compose file
network_mode: host
environment:
- TZ=Europe/Bucharest
```
Make sure to replace `/path/to/your/config`, `/var/run/docker.sock`, and `/opt/home-automation/docker-compose.yml` with your actual paths. Once installed, configure the integration by providing:
- **Docker Socket Path** (e.g., `/var/run/docker.sock`)
- **Docker Compose File Path** (e.g., `/opt/home-automation/docker-compose.yml`)
Each Docker Compose project will be registered as a **device**, with each service appearing as an **entity** under that device.
---
## 🔧 Usage
### **Entities & Attributes**
Each Docker service entity provides:
- **State**: `running`, `stopped`, `exited`, etc.
- **Health Status**: `healthy`, `unhealthy`, `starting`, or `unknown`.
- **Restart Count**: How many times the service has restarted.
- **Image**: The current Docker image version.
- **Uptime**: Start time of the container.
### **Service Control**
- Restart a service via Home Assistant **Developer Tools → Services**:
```json
{
"entity_id": "sensor.docker_homeassistant"
}
```
---
## 🛣️ Project Roadmap
This project aims to provide full integration of Docker Compose into Home Assistant, making it easy to monitor and manage services. The following features are planned:
1️⃣ **Home Assistant Integration of Docker Compose Deployments** ✅ (Done)
- Each Docker Compose project appears as a device in HA.
- Each service is registered as an entity.
2️⃣ **Service Status Monitoring** ✅ (Done)
- Track container states (`running`, `stopped`, `exited`, etc.).
- Monitor container health (`healthy`, `unhealthy`, `starting`).
3️⃣ **Restart Services from Home Assistant** ✅ (Done)
- Restart services directly from the HA UI or via automation.
4️⃣ **Container Update Notifications** 🛠️ (Planned)
- Detect if an updated image is available for a service.
- Send HA notifications when updates are detected.
5️⃣ **Update Containers from Home Assistant** 🛠️ (Planned)
- Allow updating containers directly from HA.
- Trigger `docker-compose pull` and `docker-compose up -d` commands.
---
## ⚠️ Disclaimer
**This integration is provided "as is" without any guarantees.**
- **Use at your own risk.** We are not responsible for any misconfigurations that may cause issues.
- Ensure that **your Home Assistant instance has the correct permissions** to access Docker.
- Running Docker as `root` may pose security risks; consider using user-level access where possible.
---
## 🤝 Contributions
Want to improve this project? Contributions are welcome! 🛠️
### **How to Contribute**
1. Fork the repository.
2. Create a new feature branch.
3. Make your changes and commit.
4. Open a pull request.
### **Support & Discussion**
- Open an **issue** on [GitHub Issues](https://github.com/brezuicabogdan/homeassistant-docker-compose-control/issues) if you encounter problems.
- Join the **Home Assistant Community** forums for discussion.
---
## 📜 License
This project is open-source and available under the **MIT License**.
🚀 **Enjoy managing Docker Compose services within Home Assistant!** 🎉