Connecting from your phone

This chapter covers how to reach your self-hosted system from a phone, and what it takes to get every feature working there. For installation see the Installation chapter; for each setting see the Configuration chapter.

Tailscale, DDNS and Traefik here are examples, a starting point in the same way as the Docker Compose examples in the Installation chapter. A reverse proxy, TLS certificates and domain setup are part of your hosting environment and aren't covered by support (see "Support scope" in the Installation chapter).

What works over http

When your phone is on the same network as the system, you can open http://<this machine's address>:8080 (for example http://192.168.1.10:8080) directly. When you run the tarball or zip directly, the system only accepts connections from the machine itself by default: set ip = "0.0.0.0" under [server] in config.toml and restart it first. When you start it with kakephooa-tray, tick "Allow phone connections" in its menu instead (see "Connecting a phone" in the Installation chapter). You can log in, record Expenses and check your budget that way, but browsers only allow the following on an HTTPS domain (or localhost), so none of them work:

Adding it to your home screen and opening it like an app.
Recording Expenses offline (see "Offline" in the Expenses chapter).
Passkeys (see the Your account chapter).

For these, the address your phone uses has to be an HTTPS domain. Pick one of these two ways:

Way	Suits you when	You need
Tailscale	Only your own devices connect, and you don't want the system on the internet	Tailscale on both your phone and this machine
DDNS and Traefik	You don't want an extra app on your phone, or want to connect directly from anywhere	A domain, a router that can forward ports, and a public IP that isn't shared

Either way, finish by changing your settings as described in "Changing config.toml" below.

Using Tailscale

Tailscale builds a private network between your devices and issues this machine an HTTPS certificate for a *.ts.net domain. The system doesn't appear on the internet, and nothing on your router needs changing.

Install Tailscale on this machine and on your phone, and log in to both with the same account.
On this machine, run:
```
sudo tailscale serve --bg 8080
```
The first time, if your tailnet hasn't enabled this yet, it prints Serve is not enabled on your tailnet. and a link. Open the link, follow the steps to enable it (this also turns on HTTPS certificates), then run the same command again.

Afterwards, tailscale serve status shows this machine's address, for example https://my-server.tail1234.ts.net.
Set public_url to that address as described in "Changing config.toml" below, then restart the system.
Turn on Tailscale on your phone and open that address in the browser.

On Linux, tailscale serve needs root. To stop needing sudo every time, run sudo tailscale set --operator=$USER once.

With --bg, the forwarding stays in place, including after a reboot. To stop it, run sudo tailscale serve reset.

While Tailscale on your phone is disconnected, the system can't be reached.

Using DDNS and Traefik

This puts the system directly on the internet, reachable by domain from anywhere:

DDNS keeps a domain pointed at your home's current public IP. Home connections usually get a public IP that changes, and a DDNS service updates the domain when it does. The example below uses the free DuckDNS.
Traefik is a reverse proxy: it gets an HTTPS certificate from Let's Encrypt, renews it automatically, and passes connections on to the system.

Check before you start

Your public IP isn't shared. Find the WAN IP on your router's admin page and compare it with the IP ifconfig.me shows on this machine. If they differ, or the WAN IP starts with anything from 100.64. to 100.127., your provider shares one public IP across several homes and nothing outside can connect in. Use Tailscale instead.
Your router can forward ports. TCP 80 and 443 need to be forwarded to this machine. Let's Encrypt uses port 80 to check you own the domain, and it also redirects http to https.
This machine's LAN IP stays the same. Reserve an IP for it on your router, or port forwarding stops working when the IP changes.

Get a DuckDNS domain

Log in to DuckDNS and add a subdomain, for example my-budget. Your domain is then my-budget.duckdns.org.
Note the token at the top of the page. The compose file below needs it.

docker-compose.yml

Put this in the directory you unpacked the Linux tarball into, replacing the existing docker-compose.yml. Replace my-budget.duckdns.org, your-duckdns-token and [email protected] with your own values. The email has to be a real address: Let's Encrypt rejects placeholder domains such as example.com.

name: kakephooa

services:
  traefik:
    image: traefik:v3
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.web.http.redirections.entrypoint.to=websecure
      - --entrypoints.web.http.redirections.entrypoint.scheme=https
      - --entrypoints.websecure.address=:443
      - [email protected]
      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
      - --certificatesresolvers.le.acme.httpchallenge.entrypoint=web
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt

  app:
    image: ghcr.io/single9/kakephooa:1.1.1
    restart: unless-stopped
    volumes:
      - ./config.toml:/app/config.toml:ro
      - data:/app/data
    labels:
      - traefik.enable=true
      - traefik.http.routers.kakephooa.rule=Host(`my-budget.duckdns.org`)
      - traefik.http.routers.kakephooa.entrypoints=websecure
      - traefik.http.routers.kakephooa.tls.certresolver=le
      - traefik.http.services.kakephooa.loadbalancer.server.port=8080

  ddns:
    image: lscr.io/linuxserver/duckdns:latest
    restart: unless-stopped
    environment:
      SUBDOMAINS: my-budget
      TOKEN: your-duckdns-token
      TZ: Asia/Taipei

volumes:
  data:
  letsencrypt:

app has no ports: only Traefik faces outward, so the system can only be reached over HTTPS.
ddns updates DuckDNS with your current public IP every 5 minutes.
name: kakephooa and the data volume match the examples in the Installation chapter, so your existing data carries over.
Podman has no /var/run/docker.sock. Enable Podman's socket first and change that line to its path. Rootless Podman can't use ports below 1024 by default, so 80 and 443 need extra setup.

Start it

Change your settings as described in "Changing config.toml" below, with public_url set to https://my-budget.duckdns.org.
Run docker compose up -d.
Give Traefik a minute to get the certificate, then open https://my-budget.duckdns.org on your phone over mobile data (not your home Wi-Fi) to confirm it's reachable from outside.

If the certificate request fails, docker compose logs traefik shows why. The most common cause is port 80 not being forwarded to this machine.

Once the system is on the internet

Anyone can open the login page. You should:

Turn on Two-Step Verification (see the Your account chapter).
Keep signup_policy at closed.
Stay on the latest version, as described in "Upgrading" in the Installation chapter.

Changing config.toml

Whichever way you choose, set [server] to the HTTPS address your phone uses and turn on secure_cookies:

[server]
public_url = "https://my-budget.duckdns.org"
secure_cookies = true

Restart the system afterwards. From then on, always use this address, at home too. Cookies are only sent over HTTPS, so opening any other address (such as http://192.168.1.10:8080) won't let you log in.

If Google login is set up, change the authorized redirect URI in Google Cloud Console to the new address followed by /auth/google/callback, for example https://my-budget.duckdns.org/auth/google/callback.

Adding it to your home screen

Once you open the system at its HTTPS address:

iPhone (Safari): tap "Share", then "Add to Home Screen".
Android (Chrome): tap the menu at the top right, then "Add to Home screen" or "Install app".

Open it from the home screen icon from then on, and you can record Expenses offline.