Reaching the server from the field

A phone in the field is not on the office network, so it needs an address both it and the server agree on, preferably over https. There are several ways to give a server one. The quick tunnel works today; a permanent address and an address per organisation are supported, with parts of their set-up being finalised.

A quick tunnel (no account, no domain)

From the engine's folder on a Windows server:

powershell -ExecutionPolicy Bypass -File scripts\start-public-server.ps1

It starts the database if needed, opens a Cloudflare quick tunnel (install cloudflared first: winget install --id Cloudflare.cloudflared; no Cloudflare account is needed), and runs the engine with the tunnel's https://<words>.trycloudflare.com address as its public address, which it prints. Phones open <address>/app to install Joripo Collect and scan the sign-in code.

The engine itself listens on 127.0.0.1 only: the tunnel connects from the same computer, so nothing else needs to reach it and nobody on the local network can reach the console over plain http.

The address changes every time the tunnel starts, and the server is reachable only while the computer is on and the window open. Everything that carries the address (collection links, phone sign-in codes, /app) is worked out when it is asked for, so nothing goes stale on the server. On the phones:

• Joripo Collect keeps everything: Settings › Server address, scan the new /app code, and the app checks it is the same server (by its identity, not its address) before moving its keys there;
• ODK Collect needs a new device key.

A permanent address

A permanent address needs a domain: a named tunnel on a Cloudflare account, a reverse proxy you run, or a cloud host. The server's maintainer sets it in Server administration › Device address, and every organisation sees it read-only. Nothing restarts and no file is edited; the setting survives a restart and a database rebuild.

Before using an address for links and codes, the server checks that it answers as this server. An address that does not (a placeholder, or a host that answers every name) is not used, and the console says why, instead of handing out codes that reach nothing.

When the engine sits behind a proxy, tell it which proxy to trust for the visitor's real address and for "this request was https" (FORWARDED_ALLOW_IPS, naming the proxy). Never trust every address: a guesser could then write a new address into each attempt and escape the sign-in lockout.

Plain http on the office Wi-Fi

Starting the engine with -Lan makes it listen on the computer's network address too, for phones on the same Wi-Fi (http://<computer>:8000). It warns that this is plain http: a password typed there crosses the network unencrypted, so use it only on a network you trust. ODK Collect's password sign-in refuses plain http.

An address per organisation

With a wildcard domain pointed at the server and TENANT_BASE_DOMAIN set, https://<server name>.<domain> becomes each organisation's own address: its sign-in page shows the organisation's name and admits only its people, and its root opens on that sign-in. A quick tunnel and a host's generated single address cannot give wildcard names; such servers run as one address for everyone, which is fully supported, with /login?server=<name> links and /s/<server name> for ODK Collect.

Being finalised: a wildcard address has been designed for (on a custom domain on a container host, a Cloudflare named tunnel on a zone you own, or a reverse proxy with a wildcard certificate) but not yet exercised on a production deployment.