Deploying Gladys

Introduction

Gladys Assistant is a privacy-focused, self-hosted home automation platform that puts you in control of your smart home. Built with Node.js and designed for simplicity, Gladys provides a beautiful interface for managing devices, creating scenes, and automating your home without relying on cloud services.

Originally created in France and actively developed since 2013, Gladys has grown into a mature platform with a vibrant community. Unlike cloud-dependent alternatives, Gladys runs entirely on your own infrastructure, ensuring your home automation data stays private and accessible even without internet connectivity.

Key highlights of Gladys:

Privacy-First: All data stays on your server, no cloud required
Beautiful Dashboard: Modern, responsive interface accessible from any device
Device Integrations: Support for Zigbee, Z-Wave, MQTT, Philips Hue, Sonoff, and more
Scene Automation: Create complex automations with triggers and actions
Voice Control: Integration with voice assistants
Presence Detection: Track who’s home and automate based on presence
Calendar Integration: Connect calendars for time-based automations
Music Control: Integrate with Sonos and other music systems
Telegram Bot: Control your home via Telegram messages
Multi-User Support: Create accounts for family members
100% Open Source: Licensed under Apache 2.0

This guide walks through deploying Gladys on Klutch.sh using Docker, configuring device integrations, and setting up home automations.

Why Deploy Gladys on Klutch.sh

Deploying Gladys on Klutch.sh provides several advantages for your smart home:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gladys without complex orchestration. Push to GitHub, and your home automation platform deploys automatically.

Persistent Storage: Attach persistent volumes for your device configurations, scenes, and historical data. Your automations survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your smart home dashboard from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Remote Access: Access your smart home dashboard from anywhere in the world without complex VPN or port forwarding setup.

Environment Variable Management: Securely store sensitive configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Gladys instance for a professional home automation URL.

Always-On Availability: Your home automation hub remains accessible 24/7 for remote monitoring and control.

Prerequisites

Before deploying Gladys on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Gladys configuration
Basic familiarity with Docker and containerization concepts
Smart home devices you want to integrate (optional for initial setup)
(Optional) A custom domain for your Gladys instance

Understanding Gladys Architecture

Gladys is built on a modern, modular architecture:

Node.js Backend: The core server handles device communication, automation logic, and API requests. Built with Express.js and optimized for low resource usage.

SQLite Database: User data, device configurations, scenes, and historical data are stored in an embedded SQLite database. No external database required.

Service System: Device integrations are implemented as services that can be enabled/disabled independently. Each service handles communication with specific device types.

WebSocket Communication: Real-time updates between the server and dashboard use WebSocket connections for instant device status changes.

Docker-First Design: Gladys is designed to run in Docker, making deployment consistent across different platforms.

Preparing Your Repository

To deploy Gladys on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

gladys-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM gladysassistant/gladys:v4

# Set environment variables
ENV NODE_ENV=production
ENV SERVER_PORT=80
ENV TZ=${TZ:-UTC}

# Create data directory
RUN mkdir -p /var/lib/gladysassistant

# Expose the web interface port
EXPOSE 80

# The base image includes the default entrypoint

Advanced Dockerfile with Custom Configuration

For more control over your deployment:

FROM gladysassistant/gladys:v4

# Set production environment
ENV NODE_ENV=production
ENV SERVER_PORT=80

# Timezone configuration
ENV TZ=${TZ:-UTC}

# SQLite configuration
ENV SQLITE_FILE_PATH=/var/lib/gladysassistant/gladys-production.db

# Optional: Configure external MQTT broker
ENV GLADYS_MQTT_URL=${GLADYS_MQTT_URL}
ENV GLADYS_MQTT_USERNAME=${GLADYS_MQTT_USERNAME}
ENV GLADYS_MQTT_PASSWORD=${GLADYS_MQTT_PASSWORD}

# Create data directories
RUN mkdir -p /var/lib/gladysassistant

# Set proper permissions
RUN chmod -R 755 /var/lib/gladysassistant

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/api/v1/ping || exit 1

EXPOSE 80

# The base image includes the default entrypoint

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
node_modules/

Environment Variables Reference

Variable	Required	Default	Description
`NODE_ENV`	No	production	Node.js environment
`SERVER_PORT`	No	80	HTTP server port
`TZ`	No	UTC	Timezone for the server
`SQLITE_FILE_PATH`	No	/var/lib/gladysassistant/gladys-production.db	Database file location
`GLADYS_MQTT_URL`	No	-	External MQTT broker URL
`GLADYS_MQTT_USERNAME`	No	-	MQTT username
`GLADYS_MQTT_PASSWORD`	No	-	MQTT password

Deploying Gladys on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gladys:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Gladys deployment configuration"
git remote add origin https://github.com/yourusername/gladys-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. Give it a descriptive name like “gladys” or “smart-home”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gladys Dockerfile.

Configure HTTP Traffic

Gladys serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80 (Gladys default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
`TZ`	Your timezone (e.g., `America/New_York`)
`NODE_ENV`	`production`

Add MQTT credentials if using an external broker:

Variable	Value
`GLADYS_MQTT_URL`	`mqtt://your-broker:1883`
`GLADYS_MQTT_USERNAME`	Your MQTT username
`GLADYS_MQTT_PASSWORD`	Your MQTT password

Attach Persistent Volumes

Persistent storage is essential for Gladys. Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/lib/gladysassistant`	5 GB	Database and configuration storage

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the Gladys container
Provision an HTTPS certificate

Access Gladys

Once deployment completes, access your Gladys instance at https://your-app-name.klutch.sh. The setup wizard will guide you through creating your account.

Initial Setup and Configuration

First-Time Setup

When you first access your Gladys instance:

Language Selection: Choose your preferred language
Account Creation: Create your admin account with email and password
House Setup: Configure your home’s rooms and floors
Device Setup: Start adding your smart home devices

Configuring Your Home

Set up your home’s structure:

Go to Settings > Houses
Add your house name and location
Create floors within your house
Add rooms to each floor
Assign devices to rooms

Room Configuration

Room Property	Description
Name	Display name for the room
Floor	Which floor the room is on
Picture	Optional room image
Devices	Devices located in this room

Device Integrations

Available Integrations

Gladys supports many device protocols:

Integration	Device Types
Zigbee2MQTT	Zigbee sensors, lights, switches
Z-Wave JS	Z-Wave devices
MQTT	Any MQTT-compatible device
Philips Hue	Hue lights and sensors
Sonoff	Sonoff WiFi devices
Xiaomi	Mi Home devices
Tuya	Tuya/Smart Life devices
Broadlink	IR/RF controllers
TP-Link	Kasa smart devices
Tasmota	Tasmota-flashed devices

Enabling Integrations

Activate device integrations:

Go to Settings > Integrations
Find the integration you need
Click to enable and configure
Follow the setup instructions

Zigbee2MQTT Setup

Connect Zigbee devices:

Enable the Zigbee2MQTT integration
Configure your Zigbee2MQTT broker URL
Discover devices automatically
Assign devices to rooms

MQTT Integration

Connect MQTT devices:

Enable the MQTT integration
Configure broker connection details
Create device topics
Map topics to Gladys devices

Cloud Integrations

Some integrations require network access:

Integration	Requirements
Philips Hue	Local network bridge
Telegram	Internet access
Calendar	CalDAV server access
Weather	Internet access

Dashboard Configuration

Creating Dashboards

Build custom dashboards:

Go to Dashboard
Click “Edit Dashboard”
Add widgets by clicking ”+”
Arrange widgets by dragging
Save your layout

Available Widgets

Widget Type	Description
Devices	Control lights, switches, sensors
Camera	View camera feeds
Weather	Current weather and forecast
Chart	Historical sensor data
Room	Quick access to room controls
Music	Music player controls
Calendar	Upcoming events
User Presence	Who’s home indicator

Dashboard Tips

Create separate dashboards for different purposes (main view, bedroom controls, etc.)
Use the room widget for quick access to common areas
Add charts for monitoring energy usage or temperature trends

Scenes and Automations

Creating Scenes

Build automation scenes:

Go to Scenes
Click “Create Scene”
Add triggers that start the scene
Add actions to perform
Save and enable the scene

Trigger Types

Trigger	Description
Device State	When a device changes state
Time	At specific times or intervals
Sunrise/Sunset	Based on sun position
User Presence	When someone arrives/leaves
Calendar Event	When events start/end
Telegram Message	On Telegram command

Action Types

Action	Description
Control Device	Turn on/off, dim, set values
Send Notification	Push or Telegram notification
Wait	Delay before next action
Condition	If/then logic
HTTP Request	Call external APIs
Set Variable	Store values for later use

Example Automations

Morning Routine:

Trigger: Time = 7:00 AM on weekdays
Actions: Turn on lights gradually, start coffee maker

Welcome Home:

Trigger: User presence = home
Actions: Turn on entry lights, adjust thermostat

Goodnight Scene:

Trigger: Telegram message = “goodnight”
Actions: Turn off all lights, lock doors, arm security

User Management

Creating Users

Add family members:

Go to Settings > Users
Click “Create User”
Enter name, email, and password
Assign a role
Configure presence detection

User Roles

Role	Permissions
Admin	Full system access
User	Dashboard and device control
Guest	Limited dashboard access

Presence Detection

Track who’s home:

Configure presence detection method
Set up geofencing or network detection
Create presence-based automations

Telegram Integration

Setting Up Telegram Bot

Control Gladys via Telegram:

Create a bot with @BotFather on Telegram
Get your bot token
Enable Telegram integration in Gladys
Enter your bot token
Link your Telegram account

Telegram Commands

Command	Description
`/scene morning`	Run a scene
`/temperature`	Get temperature readings
`/camera kitchen`	Get camera snapshot
`/status`	System status

Calendar Integration

Connecting Calendars

Integrate with CalDAV calendars:

Enable Calendar integration
Add your CalDAV server URL
Enter credentials
Select calendars to sync

Calendar Automations

Use calendar events in scenes:

Trigger: Meeting starts
Action: Set “Do Not Disturb” mode
Trigger: Vacation starts
Action: Enable away mode

Production Best Practices

Security Recommendations

Strong Passwords: Use unique, strong passwords for all accounts
HTTPS Only: Always access via HTTPS (automatic with Klutch.sh)
Regular Updates: Keep Gladys updated for security patches
Telegram Security: Protect your Telegram bot token
API Access: Secure any external API integrations

Performance Optimization

Database Maintenance: Gladys handles this automatically
Integration Selection: Enable only needed integrations
History Retention: Configure appropriate data retention
Resource Allocation: Monitor CPU/memory usage

Backup Strategy

Protect your configuration:

Database Backups: Back up /var/lib/gladysassistant/ regularly
Scene Export: Document your scenes
Integration Notes: Keep track of device configurations
Test Restores: Verify backups work

Monitoring and Logging

Accessing Logs

View Gladys logs through:

Klutch.sh Dashboard: View runtime logs
System Logs: Check container logs for errors
Integration Logs: Review specific integration issues

System Status

Monitor your Gladys instance:

Check dashboard for device status
Monitor scene execution history
Review integration health
Track database size

Troubleshooting Common Issues

Devices Not Responding

Symptoms: Devices show offline or don’t respond to commands.

Solutions:

Check device network connectivity
Verify integration configuration
Restart the affected integration
Check device-specific logs

Scenes Not Running

Symptoms: Automations don’t trigger or complete.

Solutions:

Verify trigger conditions are met
Check scene is enabled
Review scene execution logs
Test individual actions

Dashboard Not Loading

Symptoms: Web interface is slow or unresponsive.

Solutions:

Clear browser cache
Check server resources
Verify database integrity
Review container logs

Integration Connection Issues

Symptoms: Integration shows disconnected status.

Solutions:

Verify credentials and URLs
Check network connectivity
Restart the integration
Review integration logs

Updating Gladys

To update to a newer version:

Check Release Notes: Review Gladys blog for updates
Backup Data: Ensure database is backed up
Update Dockerfile: Pull latest image
Push Changes: Commit and push to trigger redeployment
Verify: Test dashboards and automations

Additional Resources

Conclusion

Deploying Gladys on Klutch.sh gives you a powerful, self-hosted home automation platform with automatic builds, persistent storage, and secure remote access. The combination of Gladys’s privacy-focused design and Klutch.sh’s deployment simplicity means you can focus on automating your home rather than managing infrastructure.

With support for numerous device protocols, flexible scene automation, and a beautiful dashboard, Gladys on Klutch.sh provides a complete smart home solution that respects your privacy. Whether you’re controlling a few lights or building a fully automated home, Gladys delivers the functionality you need with complete control over your data.

Note: For local device integrations (Zigbee, Z-Wave, local network devices), you may need a local Gladys instance that can communicate directly with those devices. Cloud-accessible integrations and dashboard access work seamlessly with Klutch.sh deployments.