Install xsrv and Add Remote HTTP Access

What xsrv installs and how the workflow fits together

xsrv is not itself a single web application with one standard listening port. It is a maintained Ansible collection for installing, configuring, and managing many different network services and applications on one or more servers. Its project also includes an optional command-line tool for common configuration, deployment, maintenance, and server-management operations, plus a starter template intended for a single-server environment.

That distinction matters for remote access. You do not point an HTTP tunnel at “xsrv” as a generic endpoint. You first use an xsrv role to deploy an application, identify the HTTP address and port created by that role, verify the application from the local network, and only then configure Localtonet to reach that specific endpoint.

The available roles cover substantially more than HTTP applications. Examples include Apache, backup tooling, dnsmasq, Gitea and its Actions runner, Jellyfin, Jitsi, Kiwix, libvirt, llama.cpp, Dovecot, Matrix, Grafana and other monitoring components, Mumble, Nextcloud, nmap automation, OpenLDAP, Owncast, Podman, PostgreSQL, Samba, SearXNG, Shaarli, Transmission, Tiny Tiny RSS, and WireGuard. Several of these are supporting infrastructure or use non-HTTP protocols, so an HTTP tunnel is not automatically appropriate for every role.

Prerequisites and decisions to make first

A reliable installation begins by separating confirmed requirements from role-specific choices. The xsrv project explicitly targets Debian-based servers and documents server preparation, controller preparation, and first-project creation as separate installation areas. The supplied evidence does not provide a supported Debian release matrix, controller operating-system list, Ansible version constraint, Python requirement, package installation command, privilege model, or network connection procedure.

Because those details can affect whether a deployment succeeds, use the installation documentation matching the xsrv release you actually select. The project’s documentation currently identifies version 2.2.0, while its release notes include version-specific upgrade actions. Do not combine commands or variables from a different release without checking compatibility.

Choose the application before configuring the server

Decide what the server should provide. A broad goal such as “host my own services” is not enough to determine ports, storage, authentication, or resource needs. A Gitea deployment, a Jellyfin media server, a Nextcloud collaboration environment, and a Grafana monitoring interface have different operational requirements even when they are all managed through xsrv.

For the HTTP-access portion of this guide, choose a role that produces an HTTP-facing application. Record the role name and consult its complete variable documentation. xsrv provides a list of configuration variables and a list of tags, but the supplied evidence does not include their full definitions. We cannot safely prescribe values without knowing the selected role and deployment design.

Identify the controller and managed server

Plan which machine will act as the controller and which Debian-based server will run the service. They may have different responsibilities and prerequisites. Do not assume that installing a command-line utility alone prepares the server or creates an application.

Before deployment, establish that the controller can perform the connection and privilege operations required by the version-matched xsrv documentation. Confirm the server’s identity carefully. Configuration-management mistakes can affect every host selected by a project, so a test server or limited initial target is safer than beginning with a production system.

Plan persistent data and recovery

Application data, configuration, credentials, media, repositories, and databases may need persistent storage. The exact locations are role-specific and are not established by the supplied project overview. Determine those locations from the selected role before relying on the deployment.

xsrv includes a backup role based on rsnapshot, but the existence of that role does not mean every newly deployed application is automatically backed up. Verify what is included, where backups are stored, how retention is configured, and how restoration works. A backup is not proven until a restoration procedure has been tested.

Prepare the values needed later by Localtonet

• The IP address or hostname reachable from the machine running our client.
• The application’s real HTTP listening port.
• Whether the application listens only on loopback or on another interface.
• Whether a reverse proxy sits in front of the application.
• Whether the application requires a particular hostname or base URL.
• The authentication and authorization controls users will encounter.

None of these values should be guessed. Obtain them from the deployed configuration, role documentation, service status, or verified local request.

Follow the documented xsrv installation workflow

The official xsrv documentation organizes initial setup around server preparation, controller preparation, and creation of a first project. That is the reliable sequence available in the supplied evidence. Exact shell commands, package names, repositories, directory paths, and prompts are not present in the evidence supplied for this article, so reproducing any would risk giving you an incorrect installation.

The official xsrv documentation is available at xsrv.readthedocs.io. In this case, consulting the matching installation pages is necessary because the supplied evidence confirms the phases but not the commands needed to execute them. That limitation is preferable to providing a plausible-looking command that installs the wrong release or omits required preparation.

What a successful installation means

Installation is not complete merely because a repository was downloaded or an optional command-line tool responds. At the end of preparation, you should have a controller that can work with the project, a correctly prepared Debian-based target, and a first project that identifies the intended deployment. No public tunnel is needed for this phase.

Keep xsrv management access private. Localtonet should later target the application’s HTTP service, not an administrative shell, controller workspace, private project directory, or secret-bearing configuration endpoint.

Configure an xsrv project for an HTTP-facing service

Once the controller, server, and project are ready, select the role that implements the service you want. The project publishes a role catalog, configuration-variable documentation, and deployment tags. Use the variable definitions for the exact role and version rather than transferring settings from another application.

Configure only documented variables

Review every required variable for the role. Pay particular attention to storage, database integration, administrator initialization, hostname behavior, reverse-proxy behavior, and application-level security. These concerns are common to self-hosted web applications, but their exact xsrv variable names and defaults are not present in the supplied evidence. This guide therefore does not invent a sample configuration file.

If you use version control for the project, separate secrets from ordinary configuration using the mechanism documented for your setup. Do not commit passwords, API keys, private keys, Localtonet device tokens, or downloaded client configurations. The xsrv 2.2.0 upgrade notes specifically warn WireGuard users to ignore downloaded files under data/wireguard/* to avoid accidentally committing configurations or private keys. That warning is role-specific, but the broader principle applies throughout the project.

Start with a narrow deployment

A first deployment is easier to diagnose when it contains one intended application and the minimum supporting roles required by its documentation. Adding databases, monitoring, backup, directory services, media applications, and network infrastructure in one initial run creates many possible failure points.

After the first role works, additional roles can be introduced deliberately. Use xsrv’s documented tags only when you understand which tasks they select. A tag is not a substitute for complete role configuration, and a partial run may not perform all work needed by a new installation.

Deploy, inspect, and verify the application locally

Configuration review should happen before applying changes. The xsrv 2.2.0 release notes identify xsrv check as an optional way to simulate changes and xsrv deploy as the operation that applies them. These commands are evidenced in the 2.2.0 upgrade procedure. Use them only after completing the documented installation and project setup for your release.

xsrv check

Review the proposed changes. Check that the intended host and role are selected and that the run will not overwrite an existing service unexpectedly. A simulation can improve confidence, but it cannot prove that every external dependency will behave identically during the real deployment.

xsrv deploy

Apply the project only when the review is satisfactory. Monitor the output and treat failed or skipped tasks as information that needs investigation. Do not create a tunnel merely to see whether an incomplete deployment happens to answer on a port.

Verify the service in layers

1. Deployment result: confirm that the deployment completed as intended and that no relevant task failed.
2. Service state: use the role’s documented validation procedure to confirm that the application and required supporting components are running.
3. Listening endpoint: identify the actual IP address and HTTP port from the deployed configuration or operating-system inspection.
4. Local request: open the application from the server or an authorized machine on the same network path.
5. Application workflow: sign in, complete setup, and test a harmless normal operation rather than accepting a status page alone as proof.
6. Client reachability: from the machine that will run Localtonet, verify that the same local IP and port can be reached.

Record the working local URL privately. It could use loopback, a LAN address, a hostname, or a reverse-proxy address depending on your deployment. Since no role-specific binding or port is established in the supplied evidence, this article intentionally provides no example port that could be mistaken for a default.

Add remote HTTP access with Localtonet

After the application works locally, Localtonet can expose it without inbound router port forwarding, firewall changes, a public IP address, or VPN setup. Our client on the device establishes an outbound connection to a Localtonet relay server. An HTTP tunnel points to the local IP address and port that you already verified and provides a public HTTPS address.

The device running our client must be able to reach the application target. The simplest topology is often to run the client on the same server, but another device can be used when it has a valid network path to the service. Availability depends on both sides: the application must be running, and the selected Localtonet client must remain connected with the tunnel started.

For the current dashboard sequence and supported options, consult our HTTP tunnel documentation. Do not substitute a TCP tunnel simply because the application uses a port. HTTP applications normally benefit from the URL-based HTTP tunnel workflow, while raw TCP is intended for services that need direct TCP forwarding.

Test from outside the server’s local network

A local browser test and a public test answer different questions. Use a device or connection outside the application’s local network to open the assigned HTTPS address. Confirm that the page is the intended application rather than a default server page, setup wizard, directory listing, or unrelated virtual host.

Exercise the real workflow that remote users need. For example, authenticate with a non-administrator test account, open an expected page, and sign out. If the application uses streaming, uploads, redirects, callbacks, or WebSocket-based features, verify those specific operations rather than assuming that loading the home page proves full compatibility.

Secure the application before sharing its public URL

Remote connectivity changes the application’s audience. A service that was reachable only from a trusted machine can receive internet traffic once its public address is shared or discovered. Treat application security as a prerequisite, not as an optional improvement after exposure.

Review the public page for information leakage. Dashboards can reveal private hostnames, internal IP addresses, software versions, repository names, storage paths, email addresses, monitoring labels, or links to services that are not meant to be public. A homepage role is especially likely to aggregate links, so inspect every widget and destination.

Public HTTPS transport does not correct unsafe application authorization. It also does not make an abandoned or unpatched application safe. Keep the xsrv-managed service and its dependencies updated according to their documented maintenance procedures, but review release notes before applying changes.

Operate, update, and retire the deployment

Use a repeatable change cycle

Treat the project configuration as the desired state of the server. Before changing variables or role versions, review the role documentation and release notes. Where supported by your installed release, simulate the proposed changes with xsrv check, inspect the target and task selection, and then use xsrv deploy to apply the approved state.

After every meaningful deployment, repeat local verification before testing through the public address. This separates application problems from tunnel problems. If a service is already broken locally, changing the Localtonet configuration will not repair it.

Handle xsrv upgrades as versioned migrations

The xsrv 2.2.0 release notes demonstrate why release review matters. Its documented upgrade procedure tells existing users to upgrade to 2.1.0 first if necessary, rename a VictoriaMetrics-related variable, move continued Stirling PDF use to an archived role, protect downloaded WireGuard configuration from version control, and address an OpenLDAP fact before updating roles. It then identifies xsrv upgrade, followed optionally by xsrv check and then xsrv deploy.

Those instructions apply to that particular upgrade path. They are not a generic first-install procedure and should not be applied blindly to another release. Newer releases may add, rename, or remove variables and roles. Always read every intermediate migration requirement relevant to your installed version.

Monitor both service and tunnel state

Remote availability has several dependencies: the server must be online, the deployed application must be healthy, the local target must remain reachable, our client must be connected, and the tunnel must be running. A failure at any layer can produce an unreachable or erroneous public endpoint.

If you need automated connectivity notifications, Localtonet has platform-wide Token/Tunnel webhooks for Connected and Disconnected state changes in a selected Token Group. These are lifecycle notifications. They do not report application health, HTTP status, or xsrv deployment success, so use service-level monitoring separately.

Stop access cleanly

Press Stop when temporary remote access is finished. Delete the tunnel if it is obsolete. Stopping the public endpoint does not uninstall the xsrv role or remove the local application, and deleting a tunnel does not delete application data.

If decommissioning the service itself, follow the selected role’s documented procedure. Back up any data that must be retained, verify the backup, remove secrets that are no longer needed, and confirm that no reverse-proxy route or monitoring target remains behind.

Troubleshooting xsrv deployment and HTTP access

The deployment fails before the application starts

Read the first relevant failed task rather than concentrating only on the final summary. Confirm that the server and controller were prepared for the same xsrv release, the intended host is selected, required role variables are present, and the server has not been left in a partially migrated state.

If this followed an upgrade, review every migration instruction between the old and new release. Renamed variables, removed roles, changed facts, and altered defaults can prevent a previously valid project from deploying correctly.

The deployment succeeds, but there is no HTTP page

A successful automation run does not prove that you are testing the correct address. Identify the actual listener created by the role, verify supporting services, and test the application from the server. Check whether a reverse proxy is the intended entry point. Do not assume a port based on the application’s upstream defaults because an xsrv role or local configuration may place it behind another endpoint.

The application works on the server but not from the client device

Compare the address used on the server with the address configured for Localtonet. A loopback address works only from the same network namespace. If our client runs on another device, it needs an address that is reachable from that device. Check routing and local firewall policy without opening an inbound internet-facing router port.

The public URL opens the wrong site

This often indicates that the selected local target reaches a default virtual host or another application. Verify the target IP and port again. If the deployment relies on hostname-based routing, inspect the role and reverse-proxy documentation for the correct host configuration. Do not guess custom-domain DNS records or application hostname settings.

The public URL exists but does not respond

Confirm each layer in order: application health, local request from the Localtonet device, client connection, selected device token, relay selection, tunnel configuration, and tunnel running state. Remember that creating the tunnel is not the same as starting it.

The login page works, but redirects or assets fail

The application may be generating URLs for a different hostname, scheme, port, or base path. Review its documented external-URL and reverse-proxy settings. Because those variable names differ among xsrv roles and are not included in the supplied evidence, do not add generic environment variables or configuration keys without role-specific confirmation.

The application is public but should not be

Stop the tunnel immediately. Review whether the public URL or credentials were shared, rotate any potentially disclosed application secret, and replace the Localtonet device token if it was exposed. Correct the application’s authentication and authorization before starting the tunnel again.

An update changes the endpoint

Re-run local verification and identify the current listening address. Update the Localtonet tunnel target only after confirming that the new endpoint is intentional. If the application moved behind Apache or another reverse proxy, target the verified public-facing local listener rather than an undocumented internal port.

Frequently asked questions