Skip to content
Klutch.sh Docs

Deploying Home Assistant

Introduction

Home Assistant is a powerful open-source home automation platform that puts local control and privacy first. It integrates with over 2,000 different smart home devices and services, allowing you to control everything from lights and thermostats to security cameras and voice assistants from a single, unified interface.

Built with Python, Home Assistant runs locally on your own hardware, keeping your data private and ensuring your smart home continues to work even without an internet connection. The platform features a beautiful, customizable dashboard, powerful automation capabilities, and an active community creating integrations and add-ons.

Key highlights of Home Assistant:

  • Local Control: Your data stays on your network
  • 2000+ Integrations: Support for virtually every smart home device
  • Powerful Automations: Create complex automations with visual editor or YAML
  • Voice Control: Integrate with Alexa, Google Assistant, or local voice
  • Mobile Apps: Native iOS and Android apps with push notifications
  • Energy Management: Track and optimize energy usage
  • Presence Detection: Automate based on who is home
  • History and Statistics: Track device states over time

This guide walks through deploying Home Assistant on Klutch.sh using Docker, understanding the limitations of cloud deployment, and configuring your smart home platform.

Important Considerations

Network Limitations: Home Assistant is designed for local network access to smart devices. When deployed on Klutch.sh, it cannot directly communicate with devices on your home network. This deployment is best suited for:

  • Cloud-based integrations (weather, calendar, APIs)
  • Remote monitoring dashboards
  • Testing and development
  • Integrations that work over the internet

For full local device control, Home Assistant should be deployed on hardware within your home network.

Prerequisites

Before deploying Home Assistant on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • Understanding of Home Assistant’s local network requirements

Preparing Your Repository

Create a GitHub repository with the following structure:

homeassistant-deploy/
├── Dockerfile
├── configuration.yaml (optional)
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the LinuxServer Home Assistant image:

FROM lscr.io/linuxserver/homeassistant:latest


# Environment variables
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}


# Expose the web interface port
EXPOSE 8123


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=5 \
  CMD curl -f http://localhost:8123/ || exit 1

Alternative with Official Image

FROM ghcr.io/home-assistant/home-assistant:stable


ENV TZ=${TZ:-Etc/UTC}


# Create configuration directory
RUN mkdir -p /config


EXPOSE 8123


HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=5 \
  CMD curl -f http://localhost:8123/ || exit 1

Basic Configuration File

Create a configuration.yaml:

# Home Assistant Configuration
homeassistant:
  name: Home
  unit_system: metric
  time_zone: ${TZ}


# Enable the frontend
frontend:


# Enable configuration through UI
config:


# Enable mobile app
mobile_app:


# HTTP configuration for reverse proxy
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16


# Enable history
history:


# Enable logbook
logbook:


# Enable system health
system_health:

Environment Variables Reference

VariableRequiredDefaultDescription
PUIDNo1000User ID for file ownership
PGIDNo1000Group ID for file ownership
TZNoEtc/UTCContainer timezone

Deploying Home Assistant on Klutch.sh

    Push Your Repository to GitHub

    Terminal window
    git init
    git add Dockerfile configuration.yaml .dockerignore README.md
    git commit -m "Initial Home Assistant deployment configuration"
    git remote add origin https://github.com/yourusername/homeassistant-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “homeassistant” or “smarthome”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your Home Assistant repository.

    Configure HTTP Traffic

    • Select HTTP as the traffic type
    • Set the internal port to 8123

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    PUID1000
    PGID1000
    TZYour timezone (e.g., America/New_York)

    Attach Persistent Volumes

    Mount PathRecommended SizePurpose
    /config10 GBHome Assistant configuration and database

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Home Assistant with HTTPS enabled.

    Access Home Assistant

    Once deployment completes, access Home Assistant at https://your-app-name.klutch.sh. Complete the onboarding wizard to create your account.

Configuring Home Assistant

Onboarding

  1. Access your Home Assistant instance
  2. Create your user account
  3. Set your location (for weather, sunrise/sunset)
  4. Review detected integrations
  5. Complete setup

Adding Integrations

Cloud-compatible integrations for Klutch.sh deployment:

Weather:

  • OpenWeatherMap
  • Met.no
  • AccuWeather

Calendar:

  • Google Calendar
  • CalDAV

Media:

  • Spotify
  • Plex (cloud access)

Information:

  • Google Travel Time
  • Air Quality
  • Sun

Notifications:

  • Pushover
  • Telegram
  • Email

Setting Up Integrations

  1. Go to Settings > Devices & Services
  2. Click Add Integration
  3. Search for the service
  4. Follow configuration steps
  5. Enter API credentials if required

Creating Automations

Example automation for notifications:

automation:
  - alias: "Weather Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.temperature
        above: 35
    action:
      - service: notify.mobile_app
        data:
          message: "High temperature alert!"

Dashboard Customization

  1. Navigate to Overview
  2. Click the three dots menu
  3. Select Edit Dashboard
  4. Add cards:
    • Weather forecast
    • Calendar
    • Statistics
    • Custom buttons

Cloud Integrations

Nabu Casa

Consider Nabu Casa for:

  • Remote access to local Home Assistant
  • Voice assistant integration
  • Supporting Home Assistant development

Webhooks

Receive external events:

automation:
  - alias: "Webhook Trigger"
    trigger:
      - platform: webhook
        webhook_id: my-webhook-id
    action:
      - service: notify.mobile_app
        data:
          message: "Webhook received!"

REST API

Integrate with external services:

rest:
  - resource: https://api.example.com/data
    sensor:
      - name: "External Data"
        value_template: "{{ value_json.value }}"

Troubleshooting

Configuration Errors

  • Check YAML syntax
  • Validate configuration in Developer Tools
  • Review logs for specific errors

Integration Issues

  • Verify API credentials
  • Check network connectivity
  • Review integration documentation

Slow Performance

  • Reduce recorder history
  • Disable unused integrations
  • Check database size

Additional Resources

Conclusion

Deploying Home Assistant on Klutch.sh provides a cloud-accessible smart home dashboard for monitoring and cloud-based integrations. While local device control requires on-premises deployment, the Klutch.sh installation works well for weather dashboards, calendar integration, and remote notification systems. The persistent storage ensures your configuration and history are preserved across deployments.