update docs #95.

docs/getting-started/troubleshooting.md

@@ -0,0 +1,189 @@
+# Troubleshooting
+
+Neko UI loads but you don't see the screen and it gives you `connection timeout` or `disconnected` error?
+
+## Test your client
+
+Test whether your cleint can connect to WebRTC here: https://test.webrtc.org/
+
+## Networking
+
+Most problems are networking related.
+
+### Check if your ports are correctly exposed using docker
+
+Check that your ephemeral port range `NEKO_EPR` is correctly exposed as `/udp` port range.
+
+In following example, specified range `52000-52100` must be also exposed using docker.
+
+```diff
+version: "3.4"
+services:
+  neko:
+    image: "m1k1o/neko:latest"
+    restart: "unless-stopped"
+    shm_size: "2gb"
+    ports:
+      - "8080:8080"
++      - "52000-52100:52000-52100/udp"
+    environment:
+     NEKO_SCREEN: 1920x1080@30
+     NEKO_PASSWORD: neko
+     NEKO_PASSWORD_ADMIN: admin
++     NEKO_EPR: 52000-52100
+     NEKO_ICELITE: 1
+```
+
+### Validate UDP ports reachability
+
+Ensure, that your ports are reachable through your external IP.
+
+To validate UDP connection the simpliest way, run this on your server:
+
+```shell
+nc -ul 52101
+```
+
+And this on your local client:
+
+```shell
+nc -u [server ip] 52101
+```
+Then try to type on one end, you should see characters on the other side.
+
+![nc command example](udp-ports-nc.png)
+
+If it does not work for you, then most likely your port forwarding is not working correctly. Or your ISP is blocking traffic.
+
+### Check if your external IP was determined correctly
+
+One of the first logs, when the server starts, writes down your external IP that will be sent to your clients to conenct to.
+
+```shell
+docker-compose logs neko | grep nat_ips
+```
+
+You should see this:
+
+```
+11:11AM INF webrtc starting ephemeral_port_range=52000-52100 ice_lite=true ice_servers="[{URLs:[stun:stun.l.google.com:19302] Username: Credential:<nil> CredentialType:password}]" module=webrtc nat_ips=<your-IP>
+```
+
+If your IP is not correct, you can specify own IP resover using `NEKO_IPFETCH`. It needs to return IP address that will be used.
+
+```diff
+version: "3.4"
+services:
+  neko:
+    image: "m1k1o/neko:latest"
+    restart: "unless-stopped"
+    shm_size: "2gb"
+    ports:
+      - "8080:8080"
+      - "52000-52100:52000-52100/udp"
+    environment:
+     NEKO_SCREEN: 1920x1080@30
+     NEKO_PASSWORD: neko
+     NEKO_PASSWORD_ADMIN: admin
+     NEKO_EPR: 52000-52100
+     NEKO_ICELITE: 1
++     NEKO_IPFETCH: https://ifconfig.co/ip
+```
+
+Or you can specify your IP address manually using `NEKO_NAT1TO1`:
+
+```diff
+version: "3.4"
+services:
+  neko:
+    image: "m1k1o/neko:latest"
+    restart: "unless-stopped"
+    shm_size: "2gb"
+    ports:
+      - "8080:8080"
+      - "52000-52100:52000-52100/udp"
+    environment:
+     NEKO_SCREEN: 1920x1080@30
+     NEKO_PASSWORD: neko
+     NEKO_PASSWORD_ADMIN: admin
+     NEKO_EPR: 52000-52100
+     NEKO_ICELITE: 1
++     NEKO_NAT1TO1: <your-IP>
+```
+
+If you want to use n.eko only locally, you must put here your local IP address, otherwise public address will be used.
+
+## Debug mode
+
+To see verbose information from n.eko server, you can enable debug mode using `NEKO_DEBUG`.
+
+```diff
+version: "3.4"
+services:
+  neko:
+    image: "m1k1o/neko:latest"
+    restart: "unless-stopped"
+    shm_size: "2gb"
+    ports:
+      - "8080:8080"
+      - "52000-52100:52000-52100/udp"
+    environment:
+     NEKO_SCREEN: 1920x1080@30
+     NEKO_PASSWORD: neko
+     NEKO_PASSWORD_ADMIN: admin
+     NEKO_EPR: 52000-52100
+     NEKO_ICELITE: 1
++     NEKO_DEBUG: 1
+```
+
+Ensure, that you have enabled debug mode in javascript console too, in order to see verbose information from client.
+
+## Frequently Encountered Errors
+
+### Common server errors
+
+```
+WRN session created with and error error="invalid 1:1 NAT IP mapping"
+```
+
+Check your `NEKO_NAT1TO1` or ensure, that `NEKO_IPFETCH` returns correct IP.
+
+---
+
+```
+WRN could not get server reflexive address udp6 stun:stun.l.google.com:19302: write udp6 [::]:52042->[2607:f8b0:4001:c1a::7f]:19302: sendto: cannot assign requested address
+```
+
+Check if your DNS is set up correctly, and if your IPv6 connectivity is working properly, or is disabled.
+
+---
+
+```
+WRN undeclaredMediaProcessor failed to open SrtcpSession: the DTLS transport has not started yet module=webrtc subsystem=
+```
+
+Check if your UDP ports are exposed correctly and reachable.
+
+### Common client errors
+
+```
+Firefox can’t establish a connection to the server at ws://<your-IP>/ws?password=neko.
+```
+
+Check if your TCP port is exposed correctly and your reverse proxy is correctly proxying websocket connections. And if your browser has not disabled websocket connections.
+
+---
+
+```
+Getting black screen with a cursor, but no browser.
+```
+
+Most likely you forgot to add `-cap-add=SYS_ADMIN` when using chromium-based brwosers.
+
+### Unrelated server errors
+
+```
+[ERROR:bus.cc(393)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
+```
+
+This error originates from browser, that it could not connect to dbus. This does not affect us and can be ignored.