Skip to main content

HTTPS and access

HTTPS is what the phone camera requires, and it's the part of a home setup with the most moving pieces: a certificate, a name, and a route to the box. This page covers the failures specific to that. The setup itself, and which TLS option fits your situation, is in Install.

The phone camera is blocked​

Browsers only allow the camera (barcode scanning, photos) in a secure context, which means HTTPS or localhost. Over a plain http://192.168.x.x LAN address the camera silently doesn't open. No setting in Cobblr changes this; it's a browser rule.

  • On the box itself, http://localhost:8088 counts as secure, so scanning works there.
  • From a phone, you need HTTPS. Turn it on with one of the options in Install. Tailscale is the recommended one because it gives every device a real certificate with nothing exposed.

If you have HTTPS on and the camera still won't open, confirm the address bar shows https:// with no certificate warning. On the offline-CA option the certificate has to be trusted on the device, not only installed; on iOS that is the extra toggle under Settings, General, About, Certificate Trust Settings.

Caddy crash-loops on first run​

The HTTPS proxy (caddy) exits on a bad configuration instead of serving without TLS. docker compose logs caddy shows the reason.

  • Unknown TLS mode. A line like unknown COBBLR_TLS_MODE '...' means the value isn't one of duckdns, cloudflare, internal, or tsnet. Fix the spelling in .env. The builder sets this for you.
  • A blank ACME email on an older image. The ACME modes carry an optional contact email. When COBBLR_ACME_EMAIL was blank, an older image rendered a bare email line that Caddy rejected as a parse error, and the container crash-looped. Current images self-heal by dropping the empty line, and the builder fills the field from your email. If you're on an older image, either pull the current one (docker compose pull) or set COBBLR_ACME_EMAIL to any address you control.

Tailscale (tsnet) sits there and never comes up​

On the own-hostname option the proxy joins your tailnet as its own node, and by default it waits for you to approve it. No auth key is needed: on first start it prints a one-time sign-in link in its logs and holds until you open it. Nothing is broken; it just hasn't been authorized yet.

docker compose logs caddy | grep -iE 'to authenticate|login.tailscale'

Open the https://login.tailscale.com/... link that prints, sign in, and approve the new node. The address you set in COBBLR_SITE_ADDRESS starts answering right after, and the approval is one-time. If no such line appears, follow the logs live (docker compose logs -f caddy) while the container starts, since the link prints early.

Once the node is up, find it in the Tailscale admin console and disable key expiry on it, or it signs itself out in a few months and you get the same wait again.

If you would rather the box never wait on a link, put a reusable auth key from the admin console in TS_AUTHKEY and it joins on its own. That is the optional headless path, not a requirement.

The certificate didn't issue (DuckDNS or Cloudflare)​

These modes get a real certificate through a DNS challenge. When the challenge fails, docker compose logs caddy names it. The usual causes:

  • A wrong DUCKDNS_TOKEN or CLOUDFLARE_API_TOKEN. The Cloudflare token must be scoped Zone, DNS, Edit for your zone.
  • No outbound internet from the box, so it can't reach Let's Encrypt.

Once a certificate issues it's cached under ./data/caddy, so this is a first-run problem, not something that recurs on every restart.

A name resolves but the page won't load​

This is almost always DNS rebind protection. Many routers and Pi-hole setups refuse to answer a public name (like yourbox.duckdns.org) that points at a private LAN IP, as a security measure. The laptop on one network loads it; the phone on another doesn't.

Add an exception for the name in your router or Pi-hole, or add a local DNS entry mapping the name straight to the box's LAN IP. This only affects the internet-facing modes; Tailscale doesn't use public DNS at all and sidesteps it.

DuckDNS or Cloudflare reachable, Tailscale not (or the reverse)​

These are different routes, and a device has to be on the right one.

  • Tailscale. The device must be signed into the same tailnet, with the Tailscale app running. Confirm the box is serving: on the own-hostname (tsnet) mode the proxy joins as its own node, so it appears in the Tailscale admin console; on the serve mode, tailscale serve status on the box should list the app on 127.0.0.1:8088. To reach a serve setup from outside the tailnet you need tailscale funnel, not serve.
  • DuckDNS or Cloudflare. These reach the box over the public internet, which requires the port forward on your router (TCP 443) to actually be in place and the name to point at your current public IP. Because they put the instance on the internet, set PUBLIC_SIGNUP_ENABLED=false and rely on login (see Accounts and access).

Locked out: signup is closed and nobody can get in​

Because you own the box, this is always recoverable with one .env edit; see the recovery steps in Operating and the account model in Accounts and access.