Self-Host HomelabAPI and Connect with Localtonet

What HomelabAPI does in a self-hosted notification stack

Homelab environments often accumulate independent notification configurations. Home Assistant may send one type of alert, a NAS may use another destination, and monitoring tools may each contain separate provider credentials. This works initially, but changing the final notification provider can require editing every source system.

HomelabAPI provides a central input and output hub. Compatible services submit notifications to HomelabAPI, and HomelabAPI forwards those notifications to the output or outputs selected in its configuration. If the destination changes, the central configuration can be updated instead of independently changing every compatible source.

The project currently documents inputs for ChangeDetection.io, Headphones, HealthChecks, Home Assistant, LazyLibrarian, Monit, Radarr, SmokePing, Sonarr, Synology, Tailscale, UptimeRobot, and any POST webhook that permits a request body. Documented outputs include Discord, email, Gotify, Matrix, ntfy.sh, Pushbullet, Pushover, Telegram, and generic POST webhooks.

Remote access is optional. If every sender runs on the same LAN and can reach the Docker host, a private local endpoint may be sufficient. A public endpoint becomes useful when a hosted monitoring service, remote automation platform, or other off-site system must initiate the request.

The complete request path has several independently testable layers:

Webhook sender
    |
    | HTTP POST
    v
Localtonet public HTTPS address
    |
    | Tunnel carried by the connected Localtonet client
    v
Docker host address and published host port
    |
    v
HomelabAPI /input endpoint
    |
    v
Configured notification output

Prerequisites and deployment decisions

HomelabAPI lists Docker and Docker Compose as requirements. The current Docker installation model normally uses either Docker Desktop, which includes Docker Engine and the Compose plugin, or Docker Engine with the Compose plugin installed separately.

Avoid replacing the official installation procedure with an unofficial convenience script on an important host unless you have reviewed and accepted its behavior. After installation, confirm that both Docker and Compose are available:

docker version
docker compose version

The second command verifies the current Docker Compose plugin. HomelabAPI's README uses the older standalone command:

docker-compose up

That upstream command remains relevant on systems where the legacy docker-compose executable is installed. On a current Docker installation with the Compose plugin, use the equivalent command:

docker compose up

The difference is the space instead of a hyphen. Do not install both implementations merely to make one copied command work. Use the command supported by your host and use it consistently throughout the deployment.

Acquire the HomelabAPI repository

The canonical project repository is gregdotca/homelabapi on GitHub. If Git is installed, clone it and enter the project directory:

git clone https://github.com/gregdotca/homelabapi.git
cd homelabapi

If Git is not available, open the repository, use GitHub's download option to obtain the repository as a ZIP archive, extract it, and open a terminal in the extracted directory. The directory must contain docker-compose.yml.sample, config.yaml.sample, the application files, and the helper_scripts directory.

Before installation, decide:

• Which applications will submit notifications.
• Which notification output will be configured and tested first.
• Whether the sample Docker host port is suitable or must be changed because of a local conflict.
• Whether HomelabAPI will remain LAN-only or accept requests through a Localtonet HTTP tunnel.
• Where backups of the Compose and configuration files will be stored.
• Whether you will track latest or pin a reviewed image version that is available from the project's image registry.

Install HomelabAPI with Docker Compose

The project's documented installation begins with the two sample files in the repository. Copy each sample to its active filename, edit the active copies, and retain the original samples for comparison.

On Linux, macOS, or another shell that provides cp, create the active files with:

cp docker-compose.yml.sample docker-compose.yml
cp config.yaml.sample config.yaml

In Windows PowerShell, the equivalent copies are:

Copy-Item docker-compose.yml.sample docker-compose.yml
Copy-Item config.yaml.sample config.yaml

Before editing, inspect the current files directly:

cat docker-compose.yml.sample
cat config.yaml.sample

Windows users can open the files in a text editor or use Get-Content. The checked-out sample is authoritative for its release. Do not substitute a port, mount path, output name, or provider field copied from an unrelated deployment.

Understand sample defaults and user-selected values

A Compose port publication has a host side and a container side. In short syntax it appears as HOST_PORT:CONTAINER_PORT. The container port is where HomelabAPI listens inside its container. The host port is what local clients and the Localtonet client contact.

If you change only the host side to avoid a conflict, record that change. The resulting address for a client running on the Docker host is normally structured as:

http://127.0.0.1:HOST_PORT

The current repository evidence supplied for this guide does not reproduce the full contents of docker-compose.yml.sample or config.yaml.sample. Consequently, this article does not hardcode an unverified port, mount path, output identifier, or provider schema. Read those values from the files in the repository revision you checked out. This is especially important because a sample default and a host port selected by the operator are not the same thing.

Preserve the configuration mount defined by the sample Compose file. HomelabAPI needs access to the active config.yaml; removing or redirecting its required mount without adjusting the deployment can leave the application unable to load the intended configuration.

Use the maintained image name

HomelabAPI release v0.11.1 renamed the maintained Docker image from gregdotca/homelab-api to gregdotca/homelabapi. The old image receives no further updates. A current Compose configuration that follows the renamed stream uses:

image: gregdotca/homelabapi:latest

If you are upgrading an older deployment, inspect its image: entry. The project documents the rename in the v0.11.1 release notes.

Validate Compose before startup

Docker Compose can parse and render the active definition without starting the service:

docker compose config

This catches many YAML and variable-substitution problems. The rendered output may contain resolved configuration, so do not paste it into a public issue if it includes secrets.

Start interactively the first time:

docker compose up

The upstream README expresses this as docker-compose up. Use that legacy spelling only if your host actually provides the standalone executable. Press Ctrl+C after the initial inspection if you want to restart the service in detached mode later.

Configure the API key, input, and notification output

Open config.yaml and locate the application section documented by the project. Assign a completely random string to api_key. Do not reuse an account password, Localtonet device token, hostname, or project name.

The project also documents current_outputs. Set it to one configured output while performing the first test. After individual outputs work, use comma-separated values to select several outputs or all to send to every configured output.

application:
  api_key: "REPLACE_WITH_A_RANDOM_SECRET"
  current_outputs: "REPLACE_WITH_AN_OUTPUT_NAME_FROM_CONFIG_YAML_SAMPLE"

This excerpt demonstrates placement of the two documented application settings. It deliberately does not invent provider-specific fields. Retain the complete structure from config.yaml.sample, choose an output represented there, and fill in that output's required values exactly as the sample describes.

Configure one output end to end

Use this evidence-based sequence regardless of whether the first output is Discord, email, Gotify, Matrix, ntfy.sh, Pushbullet, Pushover, Telegram, or a generic POST webhook:

1. Choose one output that appears in the current config.yaml.sample.
2. Retain that output's exact key names and YAML nesting.
3. Replace sample placeholders with credentials and destination values issued by that provider.
4. Set current_outputs to the exact output identifier used by the sample.
5. Start HomelabAPI and send a controlled local request.
6. Confirm that the test notification arrives at the selected destination before adding another output.

The private evidence available for this revision identifies the supported output names but does not include the current provider-specific sections from config.yaml.sample. Reproducing a supposed complete Discord, Telegram, ntfy, or other provider block without those fields would risk publishing a non-working configuration. The checked-out sample must therefore be used for the provider block, while the request and operational examples below can be followed directly.

Use a JSON request body when the sender supports it

HomelabAPI supports POST webhooks that allow the request body to be specified. The documented generic input fields are api_key, subject, and message. A redacted JSON request body uses this structure:

{
  "api_key": "REPLACE_WITH_YOUR_API_KEY",
  "subject": "Local test",
  "message": "HomelabAPI is working"
}

Save the JSON as test-notification.json in a protected working directory if you do not want the key directly in the command line. Restrict access to that file and delete it when the test is complete.

Certain services require a helper script to format and submit information. HomelabAPI specifically identifies Monit and SmokePing as examples and includes functional examples in the repository's helper_scripts directory. Review a helper before deploying it and test it against the local endpoint before changing it to a public address.

Use query parameters only as a compatibility fallback

If a sender cannot submit JSON, the default /input endpoint also accepts values as URL parameters on a POST request. The documented pattern is:

curl -X POST "https://your-public-host.example/input?api_key=YOUR_API_KEY&subject=Backup&message=Backup%20finished"

URL-encode the parameter values. The placeholder hostname is not a real Localtonet address.

Verify HomelabAPI on the local network

A useful verification confirms four things: the container is running, Docker published the expected host port, HomelabAPI accepted the request, and the selected output received the notification.

docker compose up -d
docker compose ps
docker compose logs --tail=100

Use the host port displayed by Compose. For a request originating on the Docker host, replace YOUR_PUBLISHED_PORT and submit the JSON file:

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  --data @test-notification.json \
  "http://127.0.0.1:YOUR_PUBLISHED_PORT/input"

On Windows PowerShell, curl can be an alias with different behavior on some versions. Use curl.exe when you want the command-line tool's standard options.

The project evidence supplied for this guide does not define one exact success status code or response body for every current input path. Treat an HTTP connection failure, timeout, or server-error response as a failure. For a successful functional test, also require the expected notification to arrive at the selected output. The downstream delivery check prevents a reachable API with invalid output credentials from being mistaken for a working notification pipeline.

If a body-based request is rejected by the exact project release you installed, inspect the API documentation presented by that running instance and compare its required content type and body schema. Do not silently move the key into the URL without understanding the logging consequence.

The documented query-string fallback can be tested locally with:

curl -i -X POST "http://127.0.0.1:YOUR_PUBLISHED_PORT/input?api_key=YOUR_API_KEY&subject=Local%20fallback%20test&message=Query-string%20delivery%20is%20working"

Use 127.0.0.1 only when the request originates on the Docker host and the published port accepts loopback connections. From another LAN device, use a reachable address for the Docker host. If the Localtonet client will run on another device, perform this LAN test from that device before creating the tunnel.

Connect the verified endpoint with Localtonet

Once local delivery works, our HTTP tunnel can expose HomelabAPI to an authorized external sender. The Localtonet client establishes an outbound connection to a Localtonet relay server. This removes the need for inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

The local target is the Docker host address and published host port used by the successful local test. The client can run on the Docker host or on another device that can reach that address over the LAN.

HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain as the Process Type. Each serves the same local content at a public HTTPS address. Availability and domain requirements can vary, so use the choices and instructions currently shown in the dashboard. The current workflow is also available in our HTTP tunnel documentation.

The public input URL follows this structure:

https://YOUR_ASSIGNED_PUBLIC_HOST/input

Test the JSON body against that address:

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  --data @test-notification.json \
  "https://YOUR_ASSIGNED_PUBLIC_HOST/input"

Use a distinct subject such as Remote test. Confirm that the notification reaches the selected output, then remove the test file if it contains the API key.

Migrate external senders one at a time. Incremental migration makes it easier to identify a sender using the wrong HTTP method, malformed JSON, an incorrect key, or an unsupported payload.

Security guidance for a public notification endpoint

Exposing an API changes its risk profile. A public hostname can receive unwanted requests even when it is not advertised. The HomelabAPI key must be treated as a secret, and the tunnel should target only the intended application port.

Protect config.yaml using operating-system permissions appropriate for the account that runs the deployment. The file can contain the HomelabAPI key and credentials for notification providers. Do not commit it to a public repository or place an unprotected copy in shared storage.

Keep the Localtonet device token separate from the HomelabAPI API key. The device token identifies the client device that establishes the tunnel. The application key authenticates requests to HomelabAPI. They are separate credentials and neither belongs in public examples.

Stop the tunnel when remote delivery is no longer required. Delete obsolete tunnel configurations and remove old webhook endpoints from sending services after a migration. If a sender supports additional source restrictions or credential controls, apply them according to that service's documentation.

Routine operation, backups, upgrades, and rollback

Run the following commands from the directory containing docker-compose.yml. If the host uses the legacy standalone implementation, substitute docker-compose for docker compose.

Apply configuration changes deliberately

Editing config.yaml does not prove the running process reloaded it. After making a change, validate the files, recreate or restart the service as appropriate, inspect logs, and repeat the local notification test:

docker compose config
docker compose up -d
docker compose logs --tail=100
docker compose ps

If the current container does not observe the edited mounted file, force recreation:

docker compose up -d --force-recreate

Test the selected output before changing external senders. If only the final notification provider changes while the input URL and API key remain the same, compatible source systems may not require endpoint changes.

Back up the deployment

At minimum, back up the active docker-compose.yml and config.yaml. Include any additional local files or directories referenced by the current Compose volumes. Because config.yaml can contain secrets, encrypt or otherwise protect the backup according to your environment.

Record the repository revision before an upgrade:

git rev-parse HEAD
git status

If the repository was downloaded as a ZIP rather than cloned, record the release or commit from which it was downloaded. Also retain the previous Compose file and configuration in a protected backup location.

Upgrade the container image

Review the project's current release notes and compare the latest sample files with your active configuration before pulling a newer image. Then use:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100

Repeat both the local and public notification tests. Pulling an image is not, by itself, proof that the running container was recreated or that the application still accepts the configured payload.

Consider version pinning

The current sample may use gregdotca/homelabapi:latest, which follows the maintained image stream but can change when a new image is published. A production-minded deployment may instead pin a reviewed image tag if that exact tag is available in the project's container registry. Confirm registry availability rather than assuming every GitHub release has a matching container tag.

Record the previously working image reference before any upgrade. Version pinning makes rollback more predictable because the old image can be named explicitly rather than relying on whatever latest points to at that moment.

Roll back after a failed upgrade

1. Stop new external traffic by stopping the Localtonet tunnel if necessary.
2. Restore the backed-up Compose and config.yaml files.
3. Restore the previously recorded image reference or reviewed version tag.
4. Run docker compose up -d to recreate the deployment.
5. Inspect status and logs.
6. Repeat the local test before restarting the public tunnel.

A rollback plan is only reliable if the previous image remains available and the backup includes every required local file. Do not remove the known-good image until the upgraded deployment has passed both local and remote tests.

Understand restart behavior

docker compose up -d leaves the container in the background, but behavior after a Docker daemon or host restart depends on the restart policy in the active Compose file. Inspect the rendered configuration rather than assuming automatic startup:

docker compose config
docker compose ps

The Localtonet client must also reconnect, and the tunnel must be running, for the public route to recover. Test the complete path after a planned reboot.

Troubleshooting installation and remote delivery

Docker Compose is not recognized

Run docker compose version. If it works, use the plugin form with a space. If only docker-compose --version works, the host has the legacy standalone implementation. If neither works, install Docker Compose using the official Docker path for the operating system.

Compose fails before HomelabAPI starts

Confirm that docker-compose.yml and config.yaml exist in the deployment directory. Run docker compose config and correct YAML indentation, quoting, missing variables, or invalid Compose syntax. Also confirm that the image uses gregdotca/homelabapi instead of the retired gregdotca/homelab-api name.

The container starts and then exits

Use docker compose ps -a and docker compose logs --tail=200. Compare the active configuration with config.yaml.sample. Look for a missing API key, damaged YAML nesting, an incomplete output block, or a configuration mount that no longer points to the intended file.

The local connection is refused

Check service state and published ports with docker compose ps. Confirm that the request uses the host-side port, not merely the internal container port. If another process occupies the selected host port, choose an unused host port in the Compose mapping, recreate the service, and update the Localtonet target.

JSON is rejected

Confirm that the request uses POST, includes Content-Type: application/json, and contains the documented api_key, subject, and message fields. Validate the JSON syntax. If the installed release exposes interactive API documentation, compare the request with that running version's schema.

The request reaches HomelabAPI but no notification arrives

Recheck the API key, current_outputs, and the provider-specific configuration. Test one output at a time. A successful TCP connection or HTTP response does not prove that the downstream provider accepted the forwarded message.

A dedicated input integration fails

Confirm that the sender produces the format expected by HomelabAPI. For Monit and SmokePing, inspect the examples in helper_scripts. Test the helper against the local endpoint before switching it to the public URL.

Local requests work but the public URL fails

Confirm that the selected Localtonet client is connected and that the tunnel was explicitly started. Verify that the local target exactly matches the address and port used by the successful test. If the client runs on another machine, 127.0.0.1 refers to that client machine, not the Docker host. Use the Docker host's reachable LAN address instead.

The public hostname responds but /input fails

Confirm that the external service sends POST requests, preserves the /input path, uses the supported body format, and provides the correct API key. A browser navigation normally issues GET and is not equivalent to the required POST test.

Notifications stop after a reboot

Check each layer in order: Docker daemon availability, Compose service state, local endpoint reachability, Localtonet client connectivity, and tunnel running state. Inspect the Compose restart policy instead of assuming the application automatically started.

The API key appeared in a URL or log

Treat it as disclosed. Generate a new random key, update config.yaml, apply the configuration, and update every authorized sender. Restrict or remove affected logs according to your retention policy, while recognizing that deleting one visible copy may not eliminate every stored copy.

Frequently asked questions