diff --git a/templates/home-assistant/README.md b/templates/home-assistant/README.md
index d8ae63c..e0f5046 100644
--- a/templates/home-assistant/README.md
+++ b/templates/home-assistant/README.md
@@ -1,8 +1,26 @@
-# home-assistant (templates)
+# Home Assistant (Portainer template)
 
-### Description
-Description for home-assistant goes here.
+Home Assistant is an open-source home automation platform that puts local control and privacy first. It acts as a central hub for smart home devices, allowing for complex automation and integration across thousands of different brands.
 
-### Configuration
-- Path: templates/home-assistant/docker-compose.yml
-- Status: Draft
+Quick notes:
+
+- **Network Mode**: For many integrations (like discovery of smart bulbs or TVs), it is highly recommended to use `network_mode: host`.
+- **Persistence**: Ensure the `/config` directory is mapped to a persistent volume to save your configuration, dashboards, and integrations.
+- **Devices**: If you are using Zigbee or Z-Wave USB sticks, you will need to map the device path (e.g., `/dev/ttyUSB0`) into the container.
+
+Usage:
+
+1. Import the compose file into Portainer's Stacks or App Templates.
+2. Configure the volume mapping for the configuration folder.
+3. (Optional) Set the timezone environment variable (e.g., `TZ=America/New_York`).
+4. Deploy the stack via Portainer.
+5. Access the web interface at `http://<your-ip>:8123` to begin the onboarding process.
+
+Helpful links:
+
+- Official Website: https://www.home-assistant.io/
+- Documentation: https://www.home-assistant.io/docs/
+- GitHub Repository: https://github.com/home-assistant/core
+- Docker Hub: https://hub.docker.com/r/homeassistant/home-assistant
+
+**Status:** Ready for configuration
diff --git a/templates/home-assistant/docker-compose.yml b/templates/home-assistant/docker-compose.yml
index e69de29..a806c27 100644
--- a/templates/home-assistant/docker-compose.yml
+++ b/templates/home-assistant/docker-compose.yml
@@ -0,0 +1,22 @@
+services:
+  homeassistant:
+    image: homeassistant/home-assistant:stable
+    container_name: homeassistant
+    # Resource constraints to prevent host exhaustion
+    mem_limit: 2g
+    cpu_shares: 512
+    security_opt:
+      - no-new-privileges:true
+    # Healthcheck ensures the web interface is responsive
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8123/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    network_mode: host # Required for discovery features (mDNS, UPnP)
+    volumes:
+      - ./config:/config:rw
+    environment:
+      - TZ=${TIMEZONE:-UTC}
+    # Restart policy for stability
+    restart: unless-stopped
\ No newline at end of file