Network and firewall requirements

What your network and security team needs to allow so AO works well: hosts, ports and settings for AO in the cloud, self-hosted AO and AO OnBoard. AO users don't need to do anything here; pass this article to the team that manages your firewall, proxy and allowlists. For just the rules, see Firewall and allowlist quick reference.

At a glance

You use	What to allow	Read
AO in the cloud (`ao.terradepth.com`) or AO for government (`gov.terradepth.com`)	Outbound HTTPS (`443/TCP`) from users' browsers to the AO host, without TLS inspection	AO in the cloud, below
Self-hosted AO	The same for your AO server's address, plus inbound access to the server	Self-hosted AO, below
AO OnBoard	Everything for self-hosted AO, plus remote desktop to the processing workstation	AO OnBoard, below
A network with no internet access	Nothing outside your network: ask for an air-gapped build	Air-gapped networks, below

Remote support by Terradepth is optional, and needs rules only if your agreement includes it. See Remote support, below.

AO is a web application. Users' browsers reach it over HTTPS, or over HTTP on port 8888 on your own AO server, and it uses no WebSockets.

AO in the cloud

Required

Host	Port	Purpose	If blocked
`ao.terradepth.com`, or `gov.terradepth.com` for AO for government	`443/TCP`	The AO application and all its services	AO doesn't load

Exempt the AO host from TLS inspection. Allowing the host isn't enough on its own. Proxies that inspect or decrypt TLS, or isolate the browser, slow AO's many requests and hold back its live updates. Users then see intermittent slowness, progress that stops updating, and services reported as unavailable. Depending on your tools, this control is called an SSL-inspection bypass, decryption exemption, "direct access" or browser-isolation bypass. Only the AO host needs it.

If the allow and the exemption are approved separately, the allow alone gets users started.

Single sign-on

If your organization signs in to AO with Microsoft or Google, users' browsers must also reach your identity provider:

Host	Provider
`login.microsoftonline.com`	Microsoft
`accounts.google.com`	Google

Optional: online map layers and services

AO works without these hosts, with the feature listed unavailable. They need only a normal allow, not a TLS-inspection exemption.

Host	Used for	Without it
`api.cesium.com`, `assets.ion.cesium.com`	Global terrain and imagery	Global terrain and satellite basemaps don't load
`*.virtualearth.net`	The Aerial, Aerial+Labels and Roads+Labels basemaps	Those basemaps don't load
`www.google.com` (only `www.google.com/generate_204`)	Checking whether AO has internet access	AO behaves as if it's offline. A proxy that answers with its own block page counts as online. See Troubleshooting, below
`help.terradepth.com`	The Help Center link in AO	No in-app help

Built-in map layers

These layers are off until a user turns them on. Allow the ones your users need.

Host	Layer
`gis.charttools.noaa.gov`	NOAA Charts
`nowcoast.noaa.gov`	Weather Radar - NOAA nowCOAST Regions
`gibs.earthdata.nasa.gov`	NASA Terra Truecolor
`tile.openstreetmap.org`	OpenStreetMap Standard
`mapproxy.osm.ch`	Waymarked Trails Hiking Overlay

External layers that your organization adds come from their own hosts: allow those as they're added.

Email

AO emails invitations and password reset links. Make sure your mail gateway accepts AO's mail; to get the sending address for your AO, contact support@terradepth.com. Invitation and reset links expire after 24 hours, so a message held in quarantine can look like a broken link. If that happens, ask your AO Admin to send a new one.

Live updates

The progress of unzipping a file in AO streams over a long-lived HTTPS response from the AO host (Server-Sent Events). Proxies and firewalls must not buffer these responses or cut long-lived connections. AO sends a heartbeat at least every 10 seconds, so the connection is never idle. Otherwise progress stops updating while the rest of AO works.

Self-hosted AO

Everything above applies to users' browsers, with your AO server's address in place of the AO host. Your AO server also needs:

Inbound to the AO server

Port	Purpose	Needed
`8888/TCP`	AO in a browser over plain HTTP, or from your own proxy that terminates TLS in front of AO	Unless everyone uses HTTPS on port 443. HTTP stays on alongside HTTPS, with no redirect. With your own proxy, allow it only from the proxy
`443/TCP`	AO in a browser over HTTPS	Once HTTPS is set up on the AO server
`80/TCP`	Let's Encrypt reaching the server's public name	Only with Let's Encrypt certificates: from the internet, when a certificate is issued and at each renewal

AO's internal services also listen on the server, on every network interface. Docker publishes their ports itself, so ufw or firewalld rules on the server don't block them. From other computers, allow only the ports in this article, plus your own administration access such as SSH. Block all other inbound ports on a firewall in front of the server or, with Docker, in Docker's DOCKER-USER chain, then check with a port scan from another computer.

HTTPS: AO serves plain HTTP on port 8888. Your IT administrator turns on HTTPS on port 443 with ./ao-mgr.sh tls setup (see HTTPS in Administering AO), or puts AO behind your own TLS proxy that forwards to port 8888. People's computers must trust AO's certificate and use the name on it: AO doesn't change DNS or install trust. If your release has no tls command, use your own TLS proxy or ask support@terradepth.com to set up HTTPS.

Outbound from the AO server

AO itself needs none of these. Each is needed only for the feature listed.

Destination and port	Needed when
Your mail server, port `465/TCP` or `587/TCP`	Email is turned on. Use port 465 or 587
`443/TCP` to your storage	Cloud mounts to S3, Google Cloud Storage, Azure or Google Drive
`22/TCP`	SFTP cloud mounts
`445/TCP`	SMB cloud mounts to a file server
`21/TCP`, plus the server's passive ports	FTP cloud mounts
The other AO's address, such as `443/TCP` for AO in the cloud	Remote Sync, or a cloud mount to another AO. Remote Sync waits on a long-lived response from the other AO: a proxy in the way must not buffer or cut it
The layer's host	Someone adds an external layer, or an animated layer is on: AO checks the layer from the server
`443/TCP` to `login.microsoftonline.com` and `graph.microsoft.com`, `oauth2.googleapis.com` and `openidconnect.googleapis.com`, or your own identity provider	Microsoft, Google or another single sign-on provider is turned on
`443/TCP` to Let's Encrypt (`acme-v02.api.letsencrypt.org`), or Tailscale's connections (see Remote support, below)	HTTPS certificates from Let's Encrypt or Tailscale, when issued and at each renewal

Cloud mount ports can be changed to match your storage. The server's operating system handles time sync and DNS. Upgrades arrive as a complete release folder, so AO needs no access to a container registry.

AO OnBoard

Everything in Self-hosted AO, above, applies. AO OnBoard also uses:

Port	Direction	Purpose	Needed when
`3389/TCP`	Inbound	Remote desktop to the processing workstation	People use the processing software from other computers on the network

To reach a server on another network, such as a file server, AO OnBoard needs an address on that network as well as open ports. Terradepth sets this up with you.

Remote support (only if your agreement includes it)

Some AO OnBoard and self-hosted systems are set up so Terradepth support can reach them for support and maintenance. This is arranged for each system, as your agreement describes. AO works without it, and air-gapped systems don't use it. If your agreement doesn't include remote support, you need none of these rules.

Method	Rule	Used for
SSH	Inbound `22/TCP`, plus `2222/TCP` on AO OnBoard	Command-line access to the server
Tailscale	Outbound `41641/UDP`, and `443/TCP` as a fallback	Remote desktop and SSH
Cloudflare Tunnel	Outbound `7844/TCP` and `7844/UDP`	HTTPS access to AO

Tailscale and Cloudflare Tunnel connect out from your system, so they need no inbound rules. The ports listed are the ones each service documents. To ask what's set up on your system, contact support@terradepth.com.

Air-gapped networks

With an air-gapped build, AO needs no connection outside your network: imagery, terrain and basemaps come from your AO server, and AO never checks for internet access. Block all traffic to and from outside your network at your firewall. This is set when your AO system is built, so tell Terradepth before delivery.

For HTTPS on such a network, use the Appliance CA or your organization's own certificate: Let's Encrypt and Tailscale need internet access.

Troubleshooting

Symptom	Likely cause
Intermittent slowness, or services shown as unavailable while AO still works	TLS inspection or browser isolation on the AO host
Unzip progress stops updating while the rest of AO works	A proxy is buffering streamed responses or cutting long-lived connections
No global terrain, or satellite basemaps missing	`api.cesium.com`, `assets.ion.cesium.com` or `*.virtualearth.net` is blocked
A built-in or external layer doesn't load	That layer's host is blocked
AO acts offline while the network works: Help Center is missing from the menu under your initial, and the basemaps show offline imagery	`www.google.com/generate_204` is blocked. Allow it, or ask Terradepth for a build that doesn't check
The browser warns about AO's certificate	The computer doesn't trust the certificate yet (install the Appliance CA's root certificate, or your organization's), or the address isn't the name on the certificate
An invitation or reset link says it's expired the first time it's used	The email was held at your mail gateway

Questions? Contact support@terradepth.com.