Add Telebit client wrapper

README.md

@@ -0,0 +1,153 @@
+# Telebit Relay
+
+Self-hosted Telebit relay and management API for running behind an external nginx wildcard HTTPS setup.
+
+## Server Setup
+
+Create `.env` from `.env.example`:
+
+```sh
+cp .env.example .env
+```
+
+Set at least:
+
+```env
+DOMAIN=example.com
+TUNNEL_DOMAIN=example.com
+SECRET=change-this-to-a-long-random-secret
+POSTGRES_PASSWORD=change-this-postgres-password
+TELEBIT_PORT=8085
+MGMT_PORT=6468
+```
+
+Start the relay:
+
+```sh
+docker compose up -d --build
+```
+
+The relay listens on `127.0.0.1:8085` through Docker's published port, and management is bound to `127.0.0.1:6468`.
+
+## Nginx
+
+Nginx should terminate HTTPS. The relay container is patched to run as a plain HTTP/WebSocket backend and should not handle Let's Encrypt itself.
+
+Use plain `http://` upstreams:
+
+```nginx
+server {
+    listen 80;
+    listen [::]:80;
+    server_name t.example.com *.t.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+
+    server_name t.example.com *.t.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/t.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/t.example.com/privkey.pem;
+
+    location = /ws {
+        proxy_pass http://127.0.0.1:8085/ws;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header Authorization $http_authorization;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:6468/api/;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:8085;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Reload:
+
+```sh
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+## Client Wrapper
+
+`telebitctl` manages local client keys and runs the Telebit client.
+
+Build local binaries with Docker:
+
+```sh
+./telebitctl build
+```
+
+This writes:
+
+```text
+bin/telebit
+bin/signjwt
+```
+
+Create a new tunnel key for a subdomain:
+
+```sh
+./telebitctl bind test
+```
+
+This creates `test.$DOMAIN` and writes `telebit-client.env`.
+
+Run the tunnel to a local service:
+
+```sh
+./telebitctl up test 80
+```
+
+That forwards:
+
+```text
+https://test.$DOMAIN -> localhost:80
+```
+
+`up` also installs the active client config to:
+
+```text
+~/.config/telebit/client.env
+```
+
+Rotate the client key:
+
+```sh
+./telebitctl auth refresh test
+```
+
+Release a subdomain:
+
+```sh
+./telebitctl release test
+```
+
+## Notes
+
+- `.env`, `telebit-client.env`, and `bin/` are ignored by git.
+- `SECRET` in `.env` is the management/relay master secret. Do not use it directly as a long-lived client key.
+- Client keys are one-time registration secrets. Use `bind` or `auth refresh` to create device-specific keys.
+- If `/ws` returns nginx `502`, nginx is probably still proxying to `https://127.0.0.1:8085`; it must use `http://127.0.0.1:8085`.