Skip to Content
Front pageLabsLabs, projects & CCNA notes

Install on a home server

Install MileWage 0.3.0 on a Linux host with Docker, publish it on a tailnet with HTTPS, and pair one Android phone.


Note: The upstream guide was run on a development machine with Docker 29. It has not been followed on a fresh VM, a Raspberry Pi or a real tailnet.

Prerequisites

  • A host with Docker and the Docker Compose plugin. Run docker compose version to confirm.
  • 1 GB of RAM and a few GB of free disk space.
  • A Tailscale account, with Tailscale installed on the host and on the phone.
  • An Android phone with Android 8.0 or later. Google services are not required.

Start the server

  1. Clone the repository.

    bash
    Wrap linesDownloadCopy code
    git clone https://github.com/raiz-toff/Milewage.git milewage && cd milewage
  2. Run the install script.

    bash
    Wrap linesDownloadCopy code
    infra/install.sh

    The script writes infra/docker/.env, builds two containers and checks /healthz. It does not overwrite an existing .env.

  3. Answer the LAN prompt.

    Enter n to keep the port on loopback only. Enter y to let phones on the home Wi-Fi connect over plain HTTP.

  4. Open the web app.

    Go to http://127.0.0.1:8080 on the host. The script selects the next free port if 8080 is in use.

Note: LAN access sends the access token and shift data unencrypted on the home network. Docker's published ports also bypass ufw and firewalld. Do not enable LAN access on a shared network.

Create the owner account

  1. Enter the account details.

    Set a username and a password of at least 10 characters. Select the country, the distance unit, the currency and the time zone.

  2. Record the recovery key.

    Write the key on paper or save it in a password manager. The server stores only the public half and cannot show the key again.

  3. Confirm the key.

    Type the last 6 characters of the key. Every other page returns "setup incomplete" until you do.

Publish the server on the tailnet

Note: HTTPS certificates publish the machine name and the tailnet name on a public certificate log. Choose a host name that can be public.

  1. Sign in to Tailscale on the host.

    bash
    Wrap linesDownloadCopy code
    sudo tailscale up
  2. Enable certificates.

    In the Tailscale admin console, open DNS. Turn on MagicDNS, then turn on HTTPS Certificates.

  3. Serve the port.

    bash
    Wrap linesDownloadCopy code
    tailscale serve --bg 8080
  4. Set the public address.

    Add this line to infra/docker/.env. Replace the host and tailnet names with your own.

    bash
    Wrap linesDownloadCopy code
    MILEWAGE_PUBLIC_URL=https://myhost.mytailnet.ts.net
  5. Restart the stack.

    bash
    Wrap linesDownloadCopy code
    docker compose --env-file infra/docker/.env -f infra/docker/docker-compose.yml up -d

Caddy trusts forwarded headers only from the Docker gateway of the stack's network. The default gateway is 172.29.88.1.

Pair the phone

  1. Install the app.

    Download milewage-0.3.0.apk from the latest release and install it.

  2. Create a pairing code.

    In the web app, open Devices and create a pairing QR code. Check the address shown under Your phone will connect to.

  3. Scan the code.

    In the phone app, tap I have a server and scan the QR code.

Verify the installation

Run the smoke test. It builds a temporary stack on port 18080 and checks health, the web client and loopback-only publishing.

bash
Wrap linesDownloadCopy code
infra/docker/smoke.sh

In the web app, open Backups and select Back up now. Download the file to a second machine.

Storage volumes

VolumeContents
datamilewage.db (records) and diagnostics.db (disposable)
backupsEncrypted .db.gz.age files
configsecrets.json (public key only), optional settings.json, optional milewage.apk
caddy_data, caddy_configCaddy state

Do not copy milewage.db while the API container runs. Use the Backups page.

Remove MileWage

Download a backup first if you need the records. Then delete the containers and all five volumes:

bash
Wrap linesDownloadCopy code
docker compose -f infra/docker/docker-compose.yml down -v
tailscale serve reset

tailscale serve reset clears every tailscale serve setting on the host.

Back to top