Skip to content
Klutch.sh Docs

Deploying WebThings Gateway

Introduction

WebThings Gateway is an open-source smart home controller that allows you to manage IoT devices from multiple manufacturers through a unified interface. Based on the Web of Things standard, it provides local control of your smart home without relying on cloud services.

Developed originally by Mozilla, WebThings Gateway supports various protocols including Zigbee, Z-Wave, and Wi-Fi devices through an extensible add-on system.

Key features of WebThings Gateway include:

  • Multi-Protocol Support: Connect Zigbee, Z-Wave, and Wi-Fi devices
  • Privacy-Focused: Local control without cloud dependencies
  • Web Interface: Manage devices from any web browser
  • Rules Engine: Create automation rules for smart devices
  • Floor Plan View: Visualize devices on a custom floor plan
  • Voice Control: Integration with voice assistants
  • Add-On System: Extend functionality with community add-ons
  • Web of Things API: Standard API for IoT interoperability
  • Remote Access: Optional secure remote access through tunneling
  • Logs and Monitoring: Track device activity and events
  • User Management: Multi-user support with permissions

This guide walks you through deploying WebThings Gateway on Klutch.sh using Docker for smart home control.

Prerequisites

Before deploying WebThings Gateway on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Compatible smart home devices (Zigbee, Z-Wave, or Wi-Fi)
  • Basic familiarity with Docker and smart home concepts

Important Considerations

WebThings Gateway is designed to run on local hardware with direct access to radio adapters (Zigbee/Z-Wave USB dongles). Cloud deployment has limitations:

  • Zigbee/Z-Wave: Requires physical USB adapters connected to the host
  • Wi-Fi Devices: Can work if devices are accessible over the network
  • Local Network Access: Some device discovery requires local network presence

For full smart home functionality, consider running WebThings Gateway on local hardware. This cloud deployment guide focuses on Wi-Fi device management and remote monitoring scenarios.

Repository Structure

Create a GitHub repository with the following structure:

webthings-deploy/
├── Dockerfile
└── .dockerignore

Dockerfile

Create a Dockerfile in your repository:

FROM webthingsio/gateway:latest


# Web interface port
EXPOSE 8080
EXPOSE 4443


# The base image handles the entrypoint

Environment Variables

VariableRequiredDefaultDescription
TZNoUTCTimezone

Deployment on Klutch.sh

  1. Push your Dockerfile to your GitHub repository.
  2. Log in to Klutch.sh and create a new project.
  3. Create a new app within your project and connect your GitHub repository containing the Dockerfile.
  4. Configure the deployment settings: - Select **HTTP** as the traffic type - Set the internal port to **8080**
  5. Add environment variables: - `TZ`: Your timezone
  6. Attach persistent volumes: - Mount path: `/home/node/.webthings` - Recommended size: 5 GB - Purpose: Configuration, add-ons, and device data
  7. Click **Deploy** and wait for the build to complete.
  8. Access your WebThings Gateway at the provided URL and complete the setup wizard.

Post-Deployment Configuration

After deployment:

  1. Complete the initial setup wizard
  2. Create your admin account
  3. Install add-ons for your device types
  4. Add and configure devices
  5. Create automation rules

Troubleshooting

Devices Not Discovered

Wi-Fi devices must be accessible from the Klutch.sh network. Devices using local discovery protocols may not be found in cloud deployments.

Add-Ons Not Installing

Check internet connectivity and verify sufficient storage space.

Additional Resources