Set Up HivePaaS on Docker Swarm with Localtonet

How HivePaaS, Docker Swarm, Traefik, and Localtonet fit together

HivePaaS is a lightweight, open-source, self-hosted Platform-as-a-Service built on Docker Swarm. Its control plane manages applications, databases, functions, deployments, domains, logs, backups, and other platform operations. Applications are deployed as Docker Swarm services, while Traefik v3 provides the HTTP and HTTPS ingress layer.

In the documented architecture, the primary control-plane node hosts Traefik, the HivePaaS application, and PostgreSQL. Worker nodes can run application workloads and the HivePaaS agent. A shared overlay network allows Traefik to reach publicly exposed containers, while project and environment networks isolate internal application communication.

For this guide, the most important part is the web request path. A browser normally connects to the dashboard domain on port 443. Traefik receives that request, examines information such as the requested hostname, and routes it to the appropriate HivePaaS service. Port 80 may handle plain HTTP requests, certificate validation, or redirection to HTTPS, depending on the active configuration.

Localtonet does not replace the HivePaaS installation or its internal ingress configuration. HivePaaS must already be installed, its services must be running, and the intended Traefik route must work before a tunnel can provide useful access.

The official HivePaaS prerequisites also require ports 80 and 443 to be free and open to the internet. This guide does not reinterpret or remove that requirement. Even if a tunnel is added later, follow the project's documented installation conditions unless HivePaaS documentation explicitly provides a supported alternative for your version and deployment.

Prerequisites for installing HivePaaS

Prepare the server and domain before running the installer. Changing these foundations after deployment can affect certificate issuance, redirects, routing, and dashboard availability.

Check ports 80 and 443 before installation

A port conflict can prevent Traefik from starting or accepting traffic. On Linux systems that provide the ss utility, the following command can show listening TCP sockets associated with ports 80 and 443:

sudo ss -ltnp | grep -E ':(80|443)\s'

No output usually means that this particular check did not find a matching listener. It is not a complete firewall or internet reachability test. Some distributions may not include ss, and container publishing or host security controls may require separate inspection.

If a service is already listening, identify it before proceeding. Do not stop an existing web server blindly on a production machine. Determine whether it serves another application, whether it can be migrated, and whether HivePaaS is meant to become the host's primary ingress layer.

Prepare the dashboard domain

The installer asks for the dashboard domain. Use a hostname that you control, such as hivepaas.example.com. Configure it using the record type and values appropriate for your DNS provider and server network. The supplied HivePaaS evidence establishes that the domain should point at the server, but it does not provide one universal DNS record recipe for every IPv4, IPv6, proxy, or DNS-provider configuration.

DNS changes may require time to propagate. Before installation, check that the hostname resolves to the intended public server address from an independent network. Also make sure upstream cloud firewalls, security groups, host firewalls, and routers permit the documented web traffic.

Install HivePaaS on the Linux server

The official quick-start workflow is intentionally short. It installs HivePaaS on the server, collects the administrator credentials and dashboard domain, configures Docker Swarm, and deploys the platform. The documented quick start then opens the dashboard and explains the recovery behavior for settings that could lock out the administrator.

curl -fsSL https://get.hivepaas.com | sudo bash

A successful installer completion is not, by itself, proof that the dashboard is reachable. DNS, firewall rules, Traefik startup, certificate issuance, and hostname matching all affect the final result. Complete the verification section before configuring Localtonet.

Verify HivePaaS and the Traefik dashboard route

Verification should proceed from the documented public interface toward the local listener. This separates HivePaaS installation problems from Localtonet configuration problems.

Verify the normal HTTPS dashboard first

Open the exact dashboard domain entered during installation. The expected result is an HTTPS page that allows you to sign in with the administrator email and password. Do not use a raw server IP as a substitute for this check. Traefik may select routes according to the hostname, and an HTTPS certificate is normally issued for a domain rather than an arbitrary address.

A command-line HTTP header request can provide a second check:

curl -I https://hivepaas.example.com

Replace the example hostname with your actual dashboard domain. A successful response, or an intentional redirect followed by a successful browser page, confirms more than basic port reachability. It indicates that DNS, TCP connectivity, TLS, and at least part of the hostname route are functioning.

Interpret redirects carefully. A response redirecting HTTP to the configured HTTPS dashboard may be expected. Repeated redirects, a redirect to an unexpected hostname, a certificate warning, or a generic Traefik response requires investigation before adding a tunnel.

Confirm the local listener rather than assuming loopback access

The supplied HivePaaS documentation establishes that Traefik accepts ingress on ports 80 and 443. It does not establish a universal loopback URL or promise that every installation binds those ports to 127.0.0.1. Inspect the active listener:

sudo ss -ltnp | grep -E ':(80|443)\s'

Look at the local address associated with each listener. A wildcard IPv4 address, wildcard IPv6 address, specific interface address, and loopback-only address have different implications. The Localtonet client must be able to reach the exact local IP and port selected as the tunnel target.

If port 80 appears reachable through loopback, test the route while preserving the configured dashboard hostname:

curl -I -H 'Host: hivepaas.example.com' http://127.0.0.1

Replace the example domain. If the listener is bound to a different local address, use that verified address instead of 127.0.0.1. Do not assume that a failed loopback test means HivePaaS itself is down. It may mean only that Traefik is not listening on loopback.

For HTTPS, this form of test keeps the hostname available for both TLS certificate validation and HTTP routing while sending the connection to loopback:

curl -I --resolve hivepaas.example.com:443:127.0.0.1 https://hivepaas.example.com/

Use this only if the listener inspection confirms that port 443 is reachable at that address. Replace both instances of the example domain. If the certificate, route, or listener does not match, curl should report the problem rather than silently proving a different path.

Record the verified backend details

Before opening our dashboard, record four facts: the reachable local IP address, the working port, whether the backend request uses HTTP or HTTPS, and the hostname Traefik expects. The first three determine the basic tunnel target. The fourth determines whether a generated Localtonet hostname can work as-is or whether a compatible custom-domain configuration is needed.

Access the verified HivePaaS endpoint with Localtonet

Once the dashboard works normally and a local Traefik target has been verified, you can add a Localtonet HTTP tunnel. Our client establishes an outbound connection to a Localtonet relay server, so the tunnel does not require inbound router port forwarding, firewall changes, a VPN, or a public IP address for the tunnel connection itself.

This does not cancel HivePaaS's documented prerequisite that ports 80 and 443 be free and open to the internet. Treat Localtonet as a distinct access path added after the supported HivePaaS deployment, not as an undocumented substitute for its installer requirements.

Choose the target based on evidence

When a custom domain may be necessary

If Traefik accepts only the configured dashboard hostname, a Localtonet endpoint using that same hostname may be more compatible than a generated hostname. HTTP and File Server tunnels can use a custom domain, but the exact DNS requirements must be checked against current Localtonet documentation before changing records.

Domain changes can also affect HivePaaS certificate issuance and its normal public route. Plan the complete request path before modifying DNS. Confirm which system terminates public TLS, what hostname reaches Traefik, and whether the original HivePaaS endpoint must remain available. Do not point production DNS at a new endpoint without a tested rollback plan.

If the generated public hostname displays the correct HivePaaS dashboard and all redirects remain on an intended secure endpoint, a custom domain may be unnecessary. If it does not, stop and diagnose the host routing rather than repeatedly changing ports.

Routine operations after setup

Starting and stopping remote access

A Localtonet tunnel exists independently from the HivePaaS services. The tunnel is reachable only while the selected client device is connected and the tunnel is running. You can stop the tunnel without uninstalling HivePaaS or stopping its Docker Swarm workloads. Delete the tunnel when its configuration is no longer needed.

Conversely, a running tunnel cannot make a stopped or unhealthy HivePaaS backend work. If the dashboard fails, test the local route first. This avoids confusing an application problem with relay connectivity.

Deploying applications through HivePaaS

HivePaaS can deploy from a Docker image or a Git repository. It supports applications built from Dockerfiles, generated build definitions for supported languages and frameworks, functions, and one-click templates. It also provides health checks, resource controls, placement options, scheduled jobs, logs, metrics, backups, projects, environments, and role-based access.

Those application routes are separate from the administrative dashboard route. Exposing the dashboard through one Localtonet tunnel does not automatically prove that every deployed application domain will work through that same public hostname. Each Traefik route can have its own domain, TLS, redirect, authentication, IP, or rate-limit behavior.

Adding worker nodes

HivePaaS supports single-server and multi-node Docker Swarm deployments. The primary control-plane node manages the platform, while worker nodes can run workloads and the agent. Cluster expansion introduces additional network, firewall, and trust considerations. Use the join procedure produced by the active installation and protect Swarm join tokens as secrets.

Do not copy a sample Swarm token or manager address from a website into a real deployment. Tokens and addresses are specific to the cluster. A Localtonet HTTP tunnel to the dashboard is also not a replacement for the internal Docker Swarm networking required between cluster nodes.

Backups and observability

HivePaaS supports encrypted, deduplicated backups through Kopia to S3-compatible storage or a volume. Logging and metrics components are optional and can be enabled when required. Before relying on the platform for important workloads, define backup destinations, retention expectations, restore testing, disk monitoring, and administrative access procedures.

A dashboard that loads successfully does not prove that backups can be restored or that worker storage is healthy. Treat access testing, service health, and data protection as separate operational checks.

Troubleshooting HivePaaS and Localtonet access

The installer cannot bind ports 80 or 443

Check for an existing web server, proxy, development server, or container publishing either port. Identify the owner of the listener before stopping it. HivePaaS documents both ports as free and open prerequisites, so placing it on a server where another ingress already owns those ports requires architectural planning beyond the quick-start workflow.

The dashboard domain does not resolve

Verify the hostname spelling and inspect its current DNS result from more than one network. Confirm that it resolves to the intended server, not an old host or private address that remote users cannot reach. DNS caching may cause different clients to see different results temporarily.

Port 80 works but redirects somewhere unexpected

Inspect the Location response header. A redirect to the configured HTTPS dashboard may be correct. A redirect to a stale hostname indicates that the active HivePaaS or Traefik configuration still references that name. Correct the underlying domain configuration rather than trying to conceal the redirect in Localtonet.

The public Localtonet URL shows a Traefik error or 404

First repeat the local request with the dashboard Host header. If that succeeds while the generated Localtonet hostname fails, the network path is probably reaching Traefik but not matching the dashboard route. Review the hostname strategy and current custom-domain requirements. Changing the local port is unlikely to solve a host-rule mismatch.

The tunnel reports running but the page times out

Confirm that the selected Localtonet device is the device on which the client is actually running. Then verify that this device can reach the configured local IP and port. A target such as 127.0.0.1 refers to the Localtonet client device itself. It does not refer to a different server on the network.

Recheck the listener after restarts or configuration changes. If Traefik moved from one interface to another, a previously valid local target may no longer be reachable.

The browser reports a certificate error

Identify which hostname the browser is opening and which endpoint terminates TLS. Do not proceed through certificate warnings on an administrative dashboard. A certificate issued for the HivePaaS domain does not automatically validate for a generated Localtonet hostname, and the public Localtonet HTTPS endpoint does not automatically prove that an HTTPS backend certificate matches.

The browser enters a redirect loop

Compare the requested scheme and hostname with every redirect response. A loop can occur when one layer considers the request HTTP while another forces HTTPS, or when two different canonical hostnames redirect to each other. Preserve the intended scheme and host information and avoid stacking unverified redirect rules.

A configuration change made the dashboard unreachable

HivePaaS applies certain Traefik startup, routing, and proxy changes on trial and rolls them back unless they are confirmed. Allow the documented recovery behavior to complete. If automatic recovery cannot run, use the recovery procedure matching your installed version. Do not delete platform data, Docker volumes, or Swarm services as an initial troubleshooting step.

Local checks succeed but remote checks fail

Separate the two public paths. The normal HivePaaS domain depends on its DNS and inbound port path. The Localtonet endpoint depends on the Localtonet client, selected device, relay connection, running tunnel, and verified local target. Test each path independently so a cloud firewall problem is not mistaken for a tunnel problem, or vice versa.

Security guidance for an administrative PaaS dashboard

The HivePaaS dashboard controls application deployments, infrastructure settings, logs, terminals, credentials, backups, domains, and other high-impact resources. Treat it as an administrative control plane, not as an ordinary public website.

Protect the Localtonet device token as a credential. It identifies the client device used to run the tunnel and must not be embedded in articles, public repositories, deployment screenshots, or troubleshooting output. Select relay values from the current dashboard rather than hardcoding old server codes.

Review who can reach the public endpoint and who can authenticate to HivePaaS. A hard-to-guess URL is not an authorization control. Use the access restrictions available in the applicable configuration, maintain strong application authentication, and review platform audit information as part of normal operations.

Frequently asked questions