Compile your home automation server carefully, verify it locally, then make its web interface reachable when you need it
Domoticz is a free, open-source home automation system with an HTML5 interface for desktop and mobile browsers. This guide explains how to plan a source build on Linux, complete the first-run administrator setup, identify the web listener without assuming a port, and test the service before exposing it. It also documents an important evidence limitation: the verified project material available for this draft points to the official source-build guide but does not reproduce its distribution-specific dependency and compiler commands. After the local service works, we show how to publish the configured HTTP endpoint with Localtonet without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
📋 What's in this guide
Why build Domoticz from source on Linux?
Domoticz is designed to run as a local home automation service. It can monitor and control lights, switches, environmental sensors, energy meters, water and gas meters, and other connected devices. The project documents support for more than 150 hardware types, including Z-Wave, Zigbee, MQTT, RFXCOM, P1 smart meters, 1-Wire devices, Philips Hue, and other integrations. It also supports automation through dzVents, Lua, Python plugins, and Blockly.
Its user interface is a scalable HTML5 frontend that adapts to desktop and mobile browsers. That architecture makes the web frontend the natural endpoint to verify after installation and, when remote access is required, the appropriate endpoint to place behind a Localtonet HTTP tunnel.
Building from source is different from using the project's one-command installer or a prebuilt package. A source build can be useful when you want to inspect the code being compiled, work from a specific release, test a development change, apply a local patch, or understand the software's build process. It also places more responsibility on the operator. You must install the correct development dependencies, use a supported toolchain, select the intended source revision, retain build output for troubleshooting, and plan how future upgrades will be performed.
Domoticz identifies Linux, Windows, macOS, FreeBSD, Raspberry Pi, and other ARM boards among its supported environments. This article concentrates on Linux. The exact dependency names and package-manager commands are distribution-specific, so instructions for one Linux family should not be copied blindly to another.
What this draft can verify, and what must be checked
A dependable build guide should provide exact package names, compiler requirements, source checkout commands, build-directory commands, CMake options, binary paths, service definitions, and startup flags. Those values should come directly from the current Domoticz source-build documentation for the selected release and Linux distribution.
The verified project material available for this article confirms that Domoticz maintains an official build-from-source path and links to its build wiki. The repository also contains files named CMakeLists.txt, build.sh, INSTALL.md, and service-related files. However, the supplied material does not include the contents of those files or the current build-wiki procedure. A filename alone does not establish how it should be invoked, which arguments it accepts, what dependencies it installs, or where it puts the resulting executable.
We do not reproduce unverified dependency lists, compiler commands, build flags, installation paths, service-unit locations, ports, or startup options in this draft. Before building, compare your selected Domoticz release with the current
official Domoticz source-build guide
and the INSTALL.md file shipped in that exact source revision. This is an intentional limitation rather than an invitation to guess.
The same caution applies to the web interface. The available evidence confirms that Domoticz provides an HTML5 web frontend and presents an administrator setup wizard on first run. It does not establish one universal URL, bind address, port, or HTTP versus HTTPS mode for every source-built deployment. This guide therefore refers to the address and port shown by your actual configuration and startup output.
An alternative installation route is publicly documented on the Domoticz website:
curl -sSL install.domoticz.com | sudo bashThat command is an installer path, not a build-from-source procedure. It is included only to distinguish the available installation models. If your objective is specifically to compile Domoticz yourself, do not substitute the installer and then describe the result as a source build. As with any command that downloads and executes a remote script, review the current script and decide whether that trust model is acceptable before running it with elevated privileges.
Prerequisites and decisions to make before compiling
Source compilation is easier to troubleshoot when the operating system, source revision, toolchain, and runtime plan are decided before the first command is run. Record these details in your deployment notes so that a later upgrade can be reproduced.
Choose the Linux host
Select a Linux device that will remain available whenever you expect automations and the web interface to work. Domoticz can run on conventional Linux computers and ARM devices such as Raspberry Pi boards, but a project's general platform support does not mean that every historical board, Linux release, compiler version, or integration behaves identically.
Confirm the architecture, distribution name, distribution release, available memory, available storage, and whether the system uses a service manager. Also account for connected hardware. A USB Zigbee coordinator, Z-Wave adapter, RFXCOM transceiver, or other directly attached controller must remain visible to the Domoticz process after reboots. Device permissions and stable device naming are operating-system concerns that should be resolved separately from web tunneling.
Select a source revision deliberately
Do not compile an unidentified moving branch for a production home automation server. Prefer a deliberate release or commit and record its identifier. The reviewed evidence identifies Stable Release 2026.3 and commit f734fde, but that does not automatically make it the correct release for every deployment. A newer stable release may exist when this draft is reviewed or published.
If you need a specific hardware fix, plugin behavior, or development feature, verify that it exists in the revision you select. Keep the original source revision separate from any local patches, and document each patch so that it can be reviewed again during upgrades.
Obtain the exact dependency list
A C++ source build commonly involves a compiler, build tooling, development headers, and libraries, but generic expectations are not a safe substitute for Domoticz's current requirements. Package names differ across Debian-derived, Fedora-derived, Arch-derived, and other Linux distributions. Even when two distributions provide the same library, the development package name can be different.
Use the dependency list associated with the exact release and operating system you selected. Avoid copying an old package list from an unrelated forum post merely because it completes without an immediate error. Missing optional development libraries can sometimes produce a successful build with functionality omitted, so read the configuration summary and warnings rather than looking only for a final success message.
Decide how the service will run
Plan a dedicated runtime identity, a persistent data location, log handling, startup after reboot, and access to required serial or network devices. The verified excerpt does not establish the correct user name, group names, executable path, database path, or service-unit contents for a source installation. These values must be taken from the current project instructions and your chosen deployment layout.
Avoid running the service permanently as the root user merely to work around device permissions. A better approach is to grant the dedicated service identity only the filesystem and hardware access it needs. The exact group or device rule depends on the Linux distribution and attached hardware, so inspect the device permissions on the host rather than assuming a universal group name.
Prepare an access and recovery plan
Before adding real devices, decide how configuration and automation data will be backed up. Test whether you can restore the service locally before relying on remote access. A Localtonet tunnel transports traffic to the configured local listener. It does not replace application backups, operating-system maintenance, hardware permissions, or Domoticz authentication.
| Decision | Record before building | Why it matters |
|---|---|---|
| Linux environment | Distribution, release, CPU architecture, and service manager | Dependency names and runtime integration can differ between systems. |
| Domoticz revision | Stable tag or exact commit identifier | A pinned revision makes the build and later troubleshooting reproducible. |
| Build instructions | Documentation version and required packages | The requirements must match the selected source rather than an unrelated tutorial. |
| Runtime identity | Service user and required device or directory permissions | Least-privilege operation reduces unnecessary host access. |
| Web listener | Actual scheme, bind address, and configured port | Local verification and the Localtonet target must match the real listener. |
| Recovery | Backup scope, location, and restore test | A recoverable local installation should exist before remote publication. |
Build Domoticz from the selected source revision
The safe source-build workflow consists of selecting the revision, following its documented prerequisites, configuring the build, compiling it, and starting the resulting program according to the instructions shipped with that revision. The exact shell commands cannot be supplied from the verified excerpt available to this draft, so the checkpoints below explain what each documented command must accomplish and what you should verify before moving forward.
Acquire source from the official project repository
Obtain the selected Domoticz source revision from the official repository. Verify that the working tree identifies the intended release or commit before compiling. If you are using a release archive, preserve its original filename and checksum information when available. If you are using a version-control checkout, record the resolved commit rather than relying only on a branch name.
Review the top-level installation instructions from that source tree. The repository contains INSTALL.md, and the project points readers to its source-build wiki. If those two instructions conflict, pause and confirm which one applies to the selected release. A current wiki can describe the newest branch while an older tagged source tree may require different dependencies or options.
Install only the documented build dependencies
Use the package manager appropriate to your distribution and install the packages named by the official procedure. Keep a record of what was added. If the instructions distinguish required dependencies from optional integration libraries, decide which integrations you need and verify the build summary reflects that decision.
Do not resolve a missing header by downloading an arbitrary file into a system include directory. That approach can conceal package-version problems and makes the build difficult to reproduce. Prefer distribution packages or the dependency mechanism explicitly documented by the Domoticz project.
Configure and compile in the documented location
Follow the project's documented build-directory layout and configuration options. Do not infer a CMake command merely from the presence of CMakeLists.txt, and do not assume that build.sh accepts a particular option without reading it. Capture the complete configure and compiler output.
Treat warnings about missing libraries, disabled features, incompatible versions, and architecture mismatches as actionable information. A generated executable is not, by itself, proof that all desired hardware integrations or scripting capabilities were included.
Identify the resulting executable and runtime files
Use the output locations stated by the official instructions for the selected revision. Do not copy binaries to guessed system directories. Determine which supporting files, web assets, certificates, scripts, and data directories must remain beside the executable or be installed elsewhere. The repository includes a www directory, but the available evidence does not establish the correct deployment operation for that directory.
Start Domoticz in the manner documented for the source build and observe its complete startup output. Record any generated configuration, warnings, listener information, and database initialization messages. If the project provides a foreground mode for initial troubleshooting, use it only according to the documented startup syntax. No startup flag is assumed here.
A useful installation test must also confirm that Domoticz starts, retains its configuration, serves the expected web interface, can be reached from the intended network scope, and restarts correctly after a controlled reboot. Complete those checks before creating a public tunnel.
Complete the first-run Domoticz configuration
On first run, Domoticz presents a setup wizard for creating the administrator account. Complete this wizard from a trusted local device before enabling remote access. Use a unique administrator password that is not reused for another service. Store it in an appropriate password manager rather than placing it in a shell history, public configuration example, or Localtonet tunnel description.
The project also documents DOMOTICZ_ADMIN_PASSWORD and the optional DOMOTICZ_ADMIN_USERNAME for automatically provisioning an administrator in Docker deployments. Those variables are explicitly described for Docker. This article does not assume that they are the correct provisioning method for a native source build.
Once authenticated, add only the hardware and integrations you are ready to test. Device setup varies substantially. A network-based MQTT integration has different requirements from a USB radio, and a smart meter has different permissions and data flow from a Philips Hue bridge. Make one controlled change at a time, then confirm that Domoticz receives or sends the expected data.
Determine the real web endpoint
Find the scheme, bind address, and port in the actual Domoticz configuration or startup output. The endpoint may use HTTP or HTTPS depending on how you configured the service. Do not copy a port from an old tutorial. Also determine whether the service listens only on loopback, on a specific LAN address, or on all interfaces.
A loopback listener can be a sensible choice when the Localtonet client runs on the same Linux host. In that arrangement, the tunnel can target the local service without making Domoticz directly reachable from every LAN device. If the Localtonet client runs on another device, the Domoticz listener must be reachable from that client over the local network, and host firewall policy must permit that local connection.
Test persistence and startup behavior
Stop Domoticz cleanly, start it again using the intended operational method, and confirm that the administrator account and configuration remain present. Then perform a planned host reboot. Verify that attached controllers retain stable device access and that the web listener returns on the expected address.
This test separates application correctness from tunnel availability. If Domoticz does not restart reliably without Localtonet, adding a tunnel will not make the underlying service reliable.
Verify Domoticz locally before remote access
Start with a browser on the Domoticz host or another trusted LAN computer, depending on the listener scope you configured. Enter the exact scheme, address, and port reported by Domoticz. Confirm that the interface loads completely, not merely that the browser receives a response.
A complete local check should include the login flow, navigation between pages, loading of static interface assets, retrieval of current device states, and at least one low-risk operation. For example, inspect a sensor reading or operate a test device where doing so is safe. Avoid using a safety-critical appliance as the first remote-control test.
You can perform a basic HTTP header check from a Linux shell after substituting the actual configured endpoint:
curl -I "http://127.0.0.1:YOUR_CONFIGURED_PORT/"
Use https:// instead if your local Domoticz listener is configured for HTTPS. The placeholder is intentional. Replace it with the port shown by your installation. A successful response confirms basic connectivity, but it does not validate authentication, scripts, live updates, attached devices, or every frontend request.
If local testing fails, inspect whether the process is running, whether the listener matches the URL, and whether the service is bound to the expected network address. On systems that provide the ss utility, this general Linux command can help display listening TCP sockets:
ss -lntpTool availability and the amount of process information visible depend on the Linux distribution and the privileges of the user running the command. Match the result to your Domoticz startup output rather than selecting an unexplained open port.
If the frontend cannot be reached directly from the device that will run the Localtonet client, it will not become healthy merely because a public URL exists. Resolve process, bind-address, protocol, port, certificate, and local firewall problems first.
Provide remote Domoticz access with Localtonet
After Domoticz works locally, you can publish its web endpoint through an HTTP tunnel with Localtonet. Our client runs on a device that can reach Domoticz and establishes an outbound connection to a Localtonet relay server. This avoids inbound router port forwarding, a public IP requirement, firewall changes for unsolicited internet traffic, and a separate VPN setup.
An HTTP tunnel points to a local IP address and port. For a same-host deployment, that target may be the loopback address and the configured Domoticz port. For a split-host deployment, use the private address through which the Localtonet client can actually reach Domoticz. Never assume that localhost refers to the Domoticz computer when the client runs somewhere else. It always refers to the machine on which the client itself is running.
HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain as the Process Type. All three serve the configured content at a public HTTPS address. Availability and exact custom-domain DNS requirements can vary, so consult the current dashboard and documentation rather than inventing DNS records.
Install and run the Localtonet client
Install the Localtonet client on the Linux host running Domoticz or on another device that can reach the verified Domoticz web listener. Keep the client running for as long as remote access is required.
Authenticate and select the client device
Use the device-specific authentication token through the supported client workflow, then select that connected device in the dashboard. Do not place the token in this article, screenshots, logs, or shared configuration. Tokens must not be guessed or disclosed.
Select an available relay server
Choose a current server or region offered by the dashboard. Available server codes can change and may vary by plan or deployment, so this guide does not hardcode one.
Create the HTTP tunnel configuration
Select the desired HTTP Process Type and enter the exact local IP address and port you verified for Domoticz. The target must be reachable from the selected Localtonet client device. Match the tunnel configuration to the actual local service rather than assuming a default port.
Start the tunnel and test the assigned address
Creating a tunnel does not start it. Press Start, then open the assigned public HTTPS address from a network outside your LAN. Confirm that the Domoticz login page appears and that authentication succeeds before testing any device action.
Stop or delete access when it is no longer needed
Stop the tunnel to end public availability while retaining the configuration, or delete it when it is no longer required. The public endpoint is available only while the selected client is connected and the tunnel is running.
For the current dashboard sequence and field descriptions, compare this workflow with our HTTP tunnel documentation. The current dashboard is authoritative for available relay servers, Process Type availability, and any plan-specific options.
| Deployment pattern | Local target | Important check |
|---|---|---|
| Domoticz and Localtonet on the same host | The verified loopback or local listener and configured port | Confirm Domoticz accepts requests from the Localtonet client process on that host. |
| Localtonet client on another LAN device | The reachable private address of the Domoticz host and configured port | Test the same address directly from the client device before creating the tunnel. |
| Domoticz local listener uses HTTP | The verified HTTP listener | Select the matching local target behavior and test the full application through the public HTTPS address. |
| Domoticz local listener uses HTTPS | The verified HTTPS listener | Confirm the current Localtonet configuration required for that local service rather than treating HTTP and HTTPS as interchangeable. |
Secure and operate the combined deployment
Remote reachability changes the threat model. A service that was previously available only on a trusted host or LAN can now receive requests through a public address. The tunnel removes the need for inbound port forwarding, but it does not replace Domoticz authentication or secure application configuration.
Require application authentication
Finish the Domoticz first-run administrator wizard before starting the tunnel. Use a unique password, review any additional security settings supported by the selected release, and avoid sharing administrator credentials among household members or automation clients. If the application supports more limited access appropriate to your deployment, prefer least privilege over using one administrator account everywhere.
Expose only the intended listener
Configure the HTTP tunnel for the exact Domoticz address and port. Do not select a broad raw-port forwarding configuration for unrelated services merely because it appears to work. Do not expose database files, debugging listeners, development servers, or Linux administration ports as part of this workflow.
Protect the Localtonet device token
A Localtonet authentication token identifies the client device. Keep it out of source repositories, shell examples, screenshots, tickets, and public logs. If you believe a token has been exposed, use the current account controls to replace or revoke it rather than continuing to rely on a known secret.
Separate service availability from tunnel availability
A working Domoticz process, a connected Localtonet client, and a running tunnel are separate lifecycle states. If Domoticz stops, the tunnel cannot make its interface functional. If the Localtonet client disconnects, the local interface may continue working while the public endpoint becomes unavailable. If the tunnel is stopped, both local services can remain healthy while remote access is intentionally disabled.
Use controlled updates
For a source-built deployment, upgrades should be repeatable. Record the old revision, back up relevant data, review release notes and build requirements, compile the intended new revision, and test it locally before restoring public access. Keep a rollback plan appropriate to your installation. Do not overwrite your only known-working executable and data copy without a recovery path.
Monitor without confusing webhook types
Our platform-wide Token and Tunnel webhooks can report Connected and Disconnected state changes for tokens or tunnels in a selected Token Group. Their JSON payload identifies the relevant tunnel ID or authentication token, action date, type, and connection status. These webhooks report connectivity lifecycle events. They do not report Domoticz device events, sensor updates, failed logins, or application health.
If you need the Domoticz interface only occasionally, start the tunnel for the required session and stop it afterward. For continuous access, regularly verify the Domoticz account configuration, Linux updates, selected source revision, Localtonet client status, and tunnel target.
Troubleshooting the build, web interface, and tunnel
The source configuration step reports missing dependencies
Return to the instructions associated with the exact Domoticz revision and Linux distribution. Confirm that development packages, not only runtime libraries, are installed. Review the full configuration output for the first missing component. Do not add random header files or copy libraries from a different distribution release. If the package names in the project instructions no longer exist, verify that your Linux release is supported and check the project's user support channels for the current equivalent.
The compiler fails partway through
Save the first meaningful compiler error and the commands that preceded it. Later errors are often consequences of the first failure. Confirm the source tree is complete, the selected revision is correct, and any required source dependencies were obtained according to the official process. Also verify available storage and memory, especially on smaller ARM devices.
Domoticz starts but the browser cannot connect
Compare the browser URL with the scheme, address, and port shown by the actual configuration or startup output. Determine whether Domoticz listens only on loopback. A loopback listener works from the same host but cannot be reached from a separate Localtonet client device. If the listener is on a LAN address, verify local firewall policy and test from the client device itself.
The page opens but assets or live data fail
Confirm that the source installation includes the required runtime files and web assets in their documented locations. Check the Domoticz log while reloading the page. If local access is also incomplete, the issue belongs to the Domoticz installation rather than the tunnel. If only the public address fails, compare browser developer-network errors with the local behavior and review whether the configured local scheme matches the actual listener.
The Localtonet public address is unavailable
Check the three independent conditions: the selected Localtonet client must be connected, the tunnel must have been started, and Domoticz must be listening at the configured local target. Remember that creating the tunnel is not the same as starting it. Also verify that the selected client is the device from which the Domoticz target is reachable.
The public page appears, but login fails
First confirm the same credentials work locally. Verify that the first-run administrator wizard was completed and that you are reaching the expected Domoticz instance rather than an old or test installation. Do not disable authentication to work around a login problem. Resolve the account issue locally, then test remotely again.
Remote access stopped after a reboot
Determine which component failed to return: Domoticz, the Localtonet client, or the tunnel. Test the Domoticz URL locally, inspect the client connection state, and then inspect the tunnel state. A tunnel is available only while its selected client is connected and the tunnel is running. Configure startup behavior only through current, documented procedures for each component.
A USB controller works manually but not as a service
Compare the interactive user's device permissions with those of the dedicated Domoticz runtime identity. Check whether the device path changed after reboot or reconnection. Solve the Linux permission and stable-device problem directly rather than running the entire home automation service with unnecessary root privileges.
Frequently asked questions
What port does Domoticz use after a source build?
This article does not assume a port. The verified project excerpt does not establish one universal port, bind address, or HTTP versus HTTPS mode for every source-built deployment. Read the actual startup output or configuration, test that endpoint locally, and use the same verified address and port as the Localtonet target.
Is the one-line Domoticz installer the same as building from source?
No. The documented curl -sSL install.domoticz.com | sudo bash command is an installer route. A source build involves intentionally obtaining a source revision, installing its build dependencies, compiling it, and deploying the resulting runtime files according to the instructions for that revision.
Can I use the Docker administrator environment variables for this native source build?
The available project evidence documents DOMOTICZ_ADMIN_PASSWORD and the optional DOMOTICZ_ADMIN_USERNAME for Docker deployments. It does not establish them as the provisioning method for a native source build. For the workflow in this guide, complete the first-run administrator wizard unless the current source-build documentation explicitly states otherwise.
Must the Localtonet client run on the Domoticz computer?
No. It can run on the same host or on another device that can reach the Domoticz web listener. If it runs elsewhere, configure the tunnel with the Domoticz host's reachable private address rather than localhost, and test that address directly from the client device first.
Does creating a Localtonet tunnel make it immediately available?
No. Creating and starting are separate lifecycle actions. After creating the HTTP configuration, press Start. The public endpoint remains available only while the selected client is connected and the tunnel is running.
Does Localtonet replace the Domoticz administrator login?
No. The HTTP tunnel provides network reachability to the configured local service. Domoticz remains responsible for its application accounts, permissions, and login behavior. Complete and verify the administrator setup before making the interface remotely reachable.
Do I need router port forwarding or a public IP address?
Not for this Localtonet workflow. Our client establishes an outbound connection to a relay server, so the tunnel can provide a public URL without inbound router port forwarding, a public IP address, firewall changes for unsolicited inbound traffic, or a separate VPN setup.
Should I expose Domoticz before adding smart home devices?
First establish a stable local installation, create the administrator account, verify the frontend, and test controlled device operations. Add remote access only after local startup, authentication, listener configuration, and recovery behavior are understood.
Connect your verified Domoticz interface with Localtonet
Once your source-built Domoticz service starts reliably and its web endpoint works locally, create an HTTP tunnel to that exact address and port. Keep application authentication enabled, protect the device token, and stop the tunnel whenever remote access is no longer required.
Get Started Free →
