# Basemap Tile Server Proxy and LAN Access

Date: 2026-06-13

This document records the local tile-server integration used by the InSAR Management System v2 Windows launcher.

## Goals

- Start and stop `D:\Code\tile-server` from the main `start_system.bat` / `stop_system.bat` workflow.
- Serve basemap tiles through the main Nginx entry instead of exposing tile-server directly to browsers.
- Keep tile access token configuration in local `.env`; do not commit real tokens.
- Allow optional LAN client IP whitelisting.
- Show a clear restricted-access page for non-whitelisted clients.

## Runtime Topology

```text
LAN browser
  -> http://<server-ip>/
  -> main nginx :80
     -> frontend dist
     -> /api/     -> FastAPI backend on 127.0.0.1:<PORT>
     -> /tiles/   -> tile-server on 127.0.0.1:8910
     -> /geojson/ -> tile-server on 127.0.0.1:8910
```

The tile-server can stay bound to `127.0.0.1:8910`. LAN clients should not call `8910` directly.

## `.env` Settings

Tile-server frontend URL should normally be empty, which means same-origin routing through Nginx:

```env
VITE_TILE_SERVER_URL=
VITE_TILE_SERVER_TOKEN=change_me
TILE_SERVER_AUTO_START=true
TILE_SERVER_AUTO_STOP=true
TILE_SERVER_ROOT=D:\Code\tile-server
TILE_SERVER_START_SCRIPT=start-all.bat
TILE_SERVER_STOP_SCRIPT=stop-all.bat
```

The real `VITE_TILE_SERVER_TOKEN` belongs only in local `.env`.

## LAN IP Whitelist

Use `NGINX_ALLOWED_CLIENT_IPS` to restrict clients:

```env
NGINX_ALLOWED_CLIENT_IPS=192.168.1.10;192.168.1.23
```

Accepted separators are semicolon, comma, or whitespace. CIDR values are also accepted:

```env
NGINX_ALLOWED_CLIENT_IPS=192.168.1.0/28
```

Empty value means no client IP restriction:

```env
NGINX_ALLOWED_CLIENT_IPS=
```

When the whitelist is enabled, the launcher generates `nginx/client_allow.conf` with `allow` rules plus `deny all`.

## Downstream Router Cases

When client devices are behind another router, write the IP that the InSAR server actually sees.

### NAT router mode

If a downstream router has an upstream LAN address such as `192.168.1.63`, and its clients are hidden behind NAT, Nginx will see every downstream client as:

```text
192.168.1.63
```

Whitelist the router IP:

```env
NGINX_ALLOWED_CLIENT_IPS=192.168.1.63
```

This allows all clients behind that NAT router because the server cannot distinguish them by their private downstream IPs.

### AP or bridge mode

If the downstream device works as an AP/bridge, clients usually receive addresses from the main LAN, for example:

```text
192.168.1.80
192.168.1.81
```

Whitelist the actual device IPs:

```env
NGINX_ALLOWED_CLIENT_IPS=192.168.1.80;192.168.1.81
```

### Routed subnet without NAT

If the downstream router forwards another subnet without NAT, the server may see the real downstream subnet addresses, for example:

```text
192.168.63.10
192.168.63.11
```

Whitelist exact client IPs:

```env
NGINX_ALLOWED_CLIENT_IPS=192.168.63.10;192.168.63.11
```

Or whitelist the whole downstream subnet when that is acceptable:

```env
NGINX_ALLOWED_CLIENT_IPS=192.168.63.0/24
```

### How to decide

Open the system from the downstream device before whitelisting it. The restricted-access page displays the detected client IP. Put that displayed IP, or its trusted CIDR range, into `NGINX_ALLOWED_CLIENT_IPS`.

## Restricted Client Page

Nginx maps `403` responses to `nginx/access_denied.html`. The page displays:

- access restricted message
- detected client IP
- requested host
- operator hint to update `NGINX_ALLOWED_CLIENT_IPS`

## Applying Changes

After changing `.env`, run `start_system.bat` or reload Nginx:

```powershell
C:\nginx-1.29.6\nginx.exe -t -c D:\Code\Insar_management_system_v2\nginx\nginx.conf
C:\nginx-1.29.6\nginx.exe -s reload -c D:\Code\Insar_management_system_v2\nginx\nginx.conf
```

From an allowed client:

```text
http://<server-ip>/
http://<server-ip>/tiles/gaode_image/7/107/42.webp?token=<token>
```

From a denied client, Nginx should return the restricted-access page with HTTP 403.