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 versionto 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
-
Clone the repository.
bashgit clone https://github.com/raiz-toff/Milewage.git milewage && cd milewage -
Run the install script.
bashinfra/install.shThe script writes
infra/docker/.env, builds two containers and checks/healthz. It does not overwrite an existing.env. -
Answer the LAN prompt.
Enter
nto keep the port on loopback only. Enteryto let phones on the home Wi-Fi connect over plain HTTP. -
Open the web app.
Go to
http://127.0.0.1:8080on the host. The script selects the next free port if8080is in use.
Note: LAN access sends the access token and shift data unencrypted on the home network. Docker's published ports also bypass
ufwandfirewalld. Do not enable LAN access on a shared network.
Create the owner account
-
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.
-
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.
-
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.
-
Sign in to Tailscale on the host.
bashsudo tailscale up -
Enable certificates.
In the Tailscale admin console, open DNS. Turn on MagicDNS, then turn on HTTPS Certificates.
-
Serve the port.
bashtailscale serve --bg 8080 -
Set the public address.
Add this line to
infra/docker/.env. Replace the host and tailnet names with your own.bashMILEWAGE_PUBLIC_URL=https://myhost.mytailnet.ts.net -
Restart the stack.
bashdocker 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
-
Install the app.
Download
milewage-0.3.0.apkfrom the latest release and install it. -
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.
-
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.
infra/docker/smoke.shIn the web app, open Backups and select Back up now. Download the file to a second machine.
Storage volumes
| Volume | Contents |
|---|---|
data | milewage.db (records) and diagnostics.db (disposable) |
backups | Encrypted .db.gz.age files |
config | secrets.json (public key only), optional settings.json, optional milewage.apk |
caddy_data, caddy_config | Caddy 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:
docker compose -f infra/docker/docker-compose.yml down -v
tailscale serve resettailscale serve reset clears every tailscale serve setting on the host.