Hauk: self-hosted location sharing with a PHP backend and one Android client

Hauk keeps location history on infrastructure you own

Hauk describes itself as a fully open source, self-hosted location sharing service, and the deployment model is the whole point. The split is deliberate: a backend written in PHP runs on a web server you control, and a companion app on the phone talks to it. Nothing about the arrangement requires a third-party account, a hosted backend, or a vendor holding a database of where you were. The intended users are therefore fairly narrow and quite identifiable. Families, small teams, and hobby projects that want to share live positions among themselves, and anyone whose reason for not using a commercial tracker is that the operator should not be the one in possession of the data.

The topics attached to the repository say the same two words, location-sharing and location-tracking, and the README is blunt about the arrangement: install the backend code on a PHP-compatible web server, install the companion app on your phone. That is a two-part deployment, not a single binary, and every operational decision that follows in this article comes from that fact.

Two folders, one config file, and a cache instead of a database

The repository layout explains the architecture without needing a diagram. At the top level there is a backend-php directory, a frontend directory, an android directory, a docker directory, an install.sh script, and a Dockerfile. The backend code and the web assets are separate trees that get placed next to each other inside a document root, and the phone client lives in its own directory with fastlane configuration for store releases.

State handling is unusual for a PHP application. The system requirements ask for a web server running PHP and Memcached or Redis, plus a PHP memcached, memcache or redis extension, and an ldap extension only if you use LDAP authentication. There is no database server in the list, and no SQL schema is described anywhere. The project therefore treats the cache daemon as the working store rather than as an optional accelerator.

Configuration lives in a single file, include/config.php, referenced by both the install script flow and the manual copy flow. The documentation tells you to set a secure hashed password there and to edit the site domain to match your own deployment. That file is the one place where the shared secret and the public hostname meet, and getting it wrong means either a broken client or an open door.

Two installation paths: install.sh or a manual copy of backend-php and frontend

The scripted route starts with a clone and an install command that takes the target folder as an argument.

git clone https://github.com/bilde2910/Hauk.git

After the clone, the script is run with the web root you want Hauk to live in.

sudo ./install.sh -c web_root

The script prints its own instructions while it runs, and the documentation tells you to follow them. Once it finishes, you are expected to start the web server, confirm that Memcached or Redis is running, and treat that daemon as a network service that needs proper configuration and a firewall in front of it, which the README links out for. The companion Android app goes on the phone next, and you enter your server settings there.

The manual route skips the script entirely and is a straightforward file operation. You clone the repository, copy everything from the backend-php and frontend folders into a common folder in your web root, for example /var/www/html, then open include/config.php and set the hashed password and the domain yourself. Both routes end in the same place: a PHP site that expects a cache daemon and an app that points at your hostname.

The Docker image ships its own memcached and expects a TLS terminator in front

There is an official image on Docker Hub named bilde2910/hauk, and the compose file in the repository mounts a configuration directory into the container.

version: '3.4'

services:
  hauk:
    image: bilde2910/hauk
    container_name: hauk
    volumes:
      - ./config/hauk:/etc/hauk

The documented procedure is to copy the sample config file into that ./config/hauk directory and customise it, and to leave the memcached connection details alone, because memcached is included in the image itself. The Dockerfile confirms the composition: it starts from php:apache, copies backend-php and frontend into /var/www/html, installs memcached and the ldap extension through pecl and docker-php-ext-install, exposes port 80, and mounts /etc/hauk as a volume. Tags follow a simple scheme, with latest tracking each commit, stable-1.x tracking the newest 1.x release, and version-pinned tags available; multi-arch builds cover x86_64, armv7l and aarch64 from release 1.5.2 onward, while 1.5.1 and older are x86_64 only.

One point deserves emphasis because it is a security decision, not a deployment detail. The container exposes plain port 80, and the documentation is explicit that you should place a reverse proxy in front of Hauk that terminates TLS and expose Hauk only via HTTPS. The example nginx server block begins like this.

listen 443 ssl;
ssl_protocols TLSv1.2 TLSv1.3;

The same example sets the certificate paths under /etc/letsencrypt, the server name, security headers, and a proxy_pass to the hauk service on port 80. If you serve Hauk over plain HTTP, anyone positioned between the clients and the server can read the location data in transit.

The client half is Android only, and LDAP is an optional extra

The phone side is where the project narrows sharply. The requirements list Android 6 or above for the companion app, and the README links to a Google Play listing and an F-Droid entry. No iOS client is named anywhere in the documentation, and no web-only fallback is described for participants who do not run Android. If a group that wants to share positions includes anyone on an iPhone, the group is stuck, and no amount of server-side work changes that.

Authentication has a similar shape. The base requirement is a password that you hash into the configuration file, and the ldap extension is listed only as conditional, needed if you use LDAP authentication. That means directory-backed accounts are possible but sit outside the default path, and the deployment instructions never spell out how to point Hauk at a directory server, so you would be working from the sample config and the wiki rather than from a documented procedure.

Distribution also differs by platform. For Arch Linux there is a hauk-server package in the AUR that installs the backend to /usr/share/webapps/hauk-server, which suits anyone who would rather not hand-roll a PHP stack and a cache daemon. For everyone else, the installer script, the manual copy, or the Docker image are the three documented routes.

Where Hauk is the wrong tool

Several ordinary situations rule Hauk out, and it is better to name them before deployment than after. If you want location sharing with no server of your own, Hauk is the wrong shape entirely, since the backend is not optional. If your group includes iOS users, there is no client for them. If your organisation already standardises on hosted crash reporting and analytics dashboards with multi-tenant accounts and role management, Hauk offers none of that machinery; it is a small self-hosted service rather than a platform.

There is a narrower operational trap too. Because the cache daemon takes the place of a database, running Hauk without a working Memcached or Redis instance does not degrade gracefully into a slower mode. The application is documented to require one of them, and the Docker image is documented to bundle memcached while the bare-metal path leaves you responsible for installing and configuring it yourself. A misconfigured cache is a broken backend, not a degraded one. The related risk is that Memcached speaks a protocol with no authentication of its own, which is why the documentation insists on configuring and firewalling it properly rather than exposing it as-is.

Semantic versioning, an uneven release history, and an Apache-2.0 licence

Hauk follows Semantic Versioning 2.0.0, and the upgrade promise is stated plainly: any update that is not a major update is guaranteed to be without breaking changes, so you can keep the same configuration file across those releases. Major updates are the ones that either require manual intervention or break backward compatibility, and the README says update instructions for major versions are listed separately. That is a workable contract for a self-hosted service, because the configuration file is the thing you would otherwise have to rewrite.

The release list is uneven. Versions 1.6.1 and 1.6.2 are dated 2020-03-24 and 2023-08-13, while version 1.6.3 is dated 2026-10-01. The repository is not archived, and the last push was on 2026-10-01. So the gap between the previous tag and the current one is long, and the release history does not support a claim of a steady cadence. What it does show is a project that resumed work and shipped a new 1.x release under the same compatibility promise.

On licensing, the licence field on the repository says Apache-2.0. That is a permissive licence with an express patent grant and a requirement to preserve notices, and it does not oblige you to open source your own deployments. Reading the LICENSE file for the exact obligations is still worth doing before you redistribute a modified backend, and this is not legal advice. The multi-arch Docker tags and the AUR package mean some operators will run prebuilt artefacts rather than the source tree, which is another reason to look at the licence text rather than assume.

Editorial conclusion

Adopt Hauk if you run your own PHP-capable server and want location sharing that never leaves your infrastructure, and expect to maintain the TLS terminator and the cache daemon yourself. Skip it if your users are on iOS or if you have no interest in operating PHP, Memcached or Redis, because the project ships only an Android companion app and assumes a backend you run. Before committing, verify that your web server has the memcached, memcache or redis extension loaded, that include/config.php carries a hashed password and your real domain, and that the whole site is reachable only over HTTPS.

Frequently asked questions

Official sources

1. bilde2910/Hauk on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases