Self-hosted server for collecting, storing and mapping wireless network surveys
1.7K
A self-hosted server for collecting, storing and mapping wireless network surveys.
Wistellar is a private home for wireless network observations — WiFi, Bluetooth and cellular. Point a survey app at it, or import logs and public datasets you already have, and explore everything on an interactive map. Your survey data stays in a database on your own server.
.gz and .zip archives are
unpacked automatically.Sign in and choose Import files from the map's menu to upload CSV, KML, KMZ, ZIP or SQLite files,
optionally GZip-compressed. Archives are unpacked on the server.
You can select several files, follow their progress and review any warnings. The map refreshes when
the import finishes. See HTTP API for how to upload with curl or any other HTTP client.
The importer picks the format by content type or file extension (.csv, .kml, .sqlite, plus
.gz, .zip and .kmz wrappers), and tells the CSV formats apart by their first line.
| Format | Notes |
|---|---|
| WiGLE CSV | The WigleWifi-1.x observation logs exported by wardriving apps |
| WiGLE SQLite backup | A whole phone backup database, imported directly |
| wifidb KML / KMZ | Exports from wifidb.net; KMZ archives are unpacked on the server |
| OpenCellID CSV | Public cell-tower dataset |
| Mylnikov CSV | Public geolocation dataset |
| Network Survey CSV | The per-technology craxiom-*.csv logs (Wi-Fi, Bluetooth, LTE, NR, UMTS, GSM, CDMA) |
| App | Status |
|---|---|
| WiGLE WiFi Wardriving | Supported — see Survey app setup. |
| Network Survey | Import only — upload its CSV log files. |
Prebuilt images for linux/amd64 and linux/arm64 are published to
Docker Hub and the
GitHub Container Registry:
docker run -d --name wistellar -p 8080:8080 -v wistellar_data:/app/data --restart unless-stopped elebree/wistellar
The web interface is then at http://localhost:8080. The /app/data volume holds the SQLite database
and the generated JWT signing key — mount it somewhere persistent, or you will lose your data and
invalidate every issued token when the container is recreated.
To upgrade, pull the new image, remove the container and run the command above again; the data volume carries over:
docker pull elebree/wistellar
docker rm -f wistellar
There is no self-registration, so create your admin account before logging in:
docker exec -it wistellar dotnet Wistellar.Server.dll --add-user --username admin --password YourStrongPassword --role admin
Every user command runs the same way as the one above.
| Command | Arguments | Effect |
|---|---|---|
--add-user | --username, --password, --role (optional) | Creates a user. Fails if the name is taken. |
--update-user | --username, --password (optional), --role (optional) | Changes the password, the role, or both. |
--delete-user | --username | Removes the user. |
Roles are member (the default), moderator, contributor and admin.
Wistellar implements the API the WiGLE Android app uploads to, but the app itself has wigle.net
hardcoded and offers no setting to point it elsewhere — so it has to be rebuilt against your server.
A Docker Compose build in this repository does that for you: it clones the upstream app, rewrites the
server URLs and produces an installable APK.
→ Building the WiGLE app for Wistellar
If you would rather not rebuild an app, collect to a file and use file import instead.
Settings live under the Wistellar section of appsettings.json:
| Setting | Default | Meaning |
|---|---|---|
ConnectionString | ./data/wistellar.sqlite | Path to the SQLite database file. Created and migrated on startup. |
IssuerSigningKeyFilePath | ./data/issuer_signing_key.txt | JWT signing key. Generated on first run and reused afterwards. |
Both can be overridden with environment variables using ASP.NET Core's double-underscore syntax, for
example -e Wistellar__ConnectionString=/app/data/my-networks.sqlite on the docker run command.
The map's query box, the tile API and the browser URL all share one filter syntax:
type=W|E|B&ssid=cafe_%&time[gt]=7d&locations[gt]=5
| Parameter | Notes |
|---|---|
type | Network type letters, |-separated. W WiFi, B Bluetooth, E BLE, F NFC, G GSM, C CDMA, L LTE, D UMTS, N 5G NR |
ssid, bssid | SQL LIKE patterns (% and _ wildcards), |-separated for alternatives |
cap | A single SQL LIKE pattern matched against the capabilities string |
range[gt], range[lt] | Distance between the farthest-apart observations, in metres |
locations[gt], locations[lt] | Number of recorded observations |
dwell[gt], dwell[lt] | Time between first and last observation, as a duration (30m, 12h, 7d) |
time[gt], time[lt] | Last seen. Accepts relative offsets (30m, 12h, 7d, 3M, 1y), ISO dates, or Unix seconds |
range, locations and dwell are recalculated when the WiGLE app checks its upload status or the
web interface finishes an import. When uploading directly through the API, request
GET /api/v2/file/transactions?pagestart=0 afterwards to update these three filters.
Every endpoint except activate needs the token in an Authorization: Bearer <token> header.
| Endpoint | Purpose |
|---|---|
POST /api/v2/activate | Sign in. Form fields credential_0 (user name), credential_1 (password) and type; returns a JWT valid for one month |
POST /api/v2/file/upload | File import. Send the files as multipart/form-data; several files per request are accepted |
GET /geo/network | Networks as a GeoJSON FeatureCollection. Accepts every map filter, plus a bounding box: lat[gt], lat[lt], lon[gt], lon[lt] |
GET /geo/location | Individual observations as GeoJSON points. Filter by bssid (|-separated) and altitude[gt] / altitude[lt] |
# Sign in and keep the token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v2/activate -d credential_0=admin -d credential_1=YourStrongPassword -d type=device | jq -r .token)
# Import files
curl -X POST http://localhost:8080/api/v2/file/upload -H "Authorization: Bearer $TOKEN" -F file=@WigleWifi_20240101.csv -F [email protected]
# Export filtered networks as GeoJSON
curl -G http://localhost:8080/geo/network -H "Authorization: Bearer $TOKEN" --data-urlencode 'type=W' --data-urlencode 'time[gt]=30d' > networks.geojson
A /geo/network request without a bounding box returns every matching network in the database.
Container won't start — check the logs:
docker logs wistellar
SQLite cannot open the database file — almost always a permissions problem on the mounted data directory. Confirm what the container sees:
docker exec -it wistellar ls -la /app/data
Using a named volume (-v wistellar_data:/app/data) rather than a bind mount avoids most host
permission mismatches.
Building from source, running locally and the project layout are covered in docs/DEVELOPMENT.md.
MIT — see LICENSE.
Content type
Image
Digest
sha256:43e6f3b78…
Size
59.9 MB
Last updated
7 days ago
docker pull elebree/wistellar