diff --git a/docs/host-your-own.md b/docs/host-your-own.md index 41ebe9b..5816a95 100644 --- a/docs/host-your-own.md +++ b/docs/host-your-own.md @@ -3,9 +3,10 @@ The easiest way to get PairDrop up and running is by using Docker. > TURN server for Internet Transfer > -> Beware that you have to host your own TURN server in order to enable transfers between different networks. +> Beware that you have to host your own TURN server to enable transfers between different networks. > -> You can follow [this guide](https://gabrieltanner.org/blog/turn-server/) to either install coturn directly on your system (Step 1) or deploy it via docker-compose (Step 5). +> Follow [this guide](https://gabrieltanner.org/blog/turn-server/) to either install coturn directly on your system (Step 1) \ +> or deploy it via docker-compose (Step 5). ## Deployment with Docker @@ -15,9 +16,11 @@ The easiest way to get PairDrop up and running is by using Docker. docker run -d --restart=unless-stopped --name=pairdrop -p 127.0.0.1:3000:3000 lscr.io/linuxserver/pairdrop ``` -> You must use a server proxy to set the X-Forwarded-For to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). +> You must use a server proxy to set the X-Forwarded-For \ +> to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). > -> To prevent bypassing the proxy by reaching the docker container directly, `127.0.0.1` is specified in the run command. +> To prevent bypassing the proxy by reaching the docker container directly, \ +> `127.0.0.1` is specified in the run command. #### Options / Flags Set options by using the following flags in the `docker run` command: @@ -39,21 +42,30 @@ Set options by using the following flags in the `docker run` command: ```bash -e IPV6_LOCALIZE=4 ``` -> To enable Peer Discovery among IPv6 peers, you can specify a reduced number of segments of the client IPv6 address to be evaluated as the peer's IP. This can be especially useful when using Cloudflare as a proxy. +> To enable Peer Discovery among IPv6 peers, you can specify a reduced number of segments \ +> of the client IPv6 address to be evaluated as the peer's IP. \ +> This can be especially useful when using Cloudflare as a proxy. > -> The flag must be set to an **integer** between `1` and `7`. The number represents the number of IPv6 [hextets](https://en.wikipedia.org/wiki/IPv6#Address_representation) to match the client IP against. The most common value would be `4`, which will group peers within the same `/64` subnet. +> The flag must be set to an **integer** between `1` and `7`. \ +> The number represents the number of IPv6 [hextets](https://en.wikipedia.org/wiki/IPv6#Address_representation) \ +> to match the client IP against. The most common value would be `4`, \ +> which will group peers within the same `/64` subnet. ##### Websocket Fallback (for VPN) ```bash -e WS_FALLBACK=true ``` -> Provides PairDrop to clients with an included websocket fallback if the peer to peer WebRTC connection is not available to the client. +> Provides PairDrop to clients with an included websocket fallback \ +> if the peer to peer WebRTC connection is not available to the client. > -> This is not used on the official https://pairdrop.net, but you can activate it on your self-hosted instance. -> This is especially useful if you connect to your instance via a VPN as most VPN services block WebRTC completely in order to hide your real IP address ([read more](https://privacysavvy.com/security/safe-browsing/disable-webrtc-chrome-firefox-safari-opera-edge/)). +> This is not used on the official https://pairdrop.net website, \ +> but you can activate it on your self-hosted instance. +> This is especially useful if you connect to your instance via a VPN (as most VPN services block WebRTC completely in order to hide your real IP address). ([Read more here](https://privacysavvy.com/security/safe-browsing/disable-webrtc-chrome-firefox-safari-opera-edge/)). > -> **Warning:** All traffic sent between devices using this fallback is routed through the server and therefor not peer to peer! -> Beware that the traffic routed via this fallback is readable by the server. Only ever use this on instances you can trust. +> **Warning:** All traffic sent between devices using this fallback \ +> is routed through the server and therefor not peer to peer! \ +> Beware that the traffic routed via this fallback is readable by the server. \ +> Only ever use this on instances you can trust. \ > Additionally, beware that all traffic using this fallback debits the servers data plan. ##### Specify STUN/TURN Servers @@ -61,7 +73,8 @@ Set options by using the following flags in the `docker run` command: -e RTC_CONFIG="rtc_config.json" ``` -> Specify the STUN/TURN servers PairDrop clients use by setting `RTC_CONFIG` to a JSON file including the configuration. +> Specify the STUN/TURN servers PairDrop clients use by setting \ +> `RTC_CONFIG` to a JSON file including the configuration. \ > You can use `pairdrop/rtc_config_example.json` as a starting point. > > To host your own TURN server you can follow this guide: https://gabrieltanner.org/blog/turn-server/ @@ -83,8 +96,10 @@ Set options by using the following flags in the `docker run` command: -e DEBUG_MODE="true" ``` -> Use this flag to enable debugging information about the connecting peers IP addresses. This is quite useful to check whether the [#HTTP-Server](#http-server) -> is configured correctly, so the auto discovery feature works correctly. Otherwise, all clients discover each other mutually, independently of their network status. +> Use this flag to enable debugging information about the connecting peers IP addresses. \ +> This is quite useful to check whether the [#HTTP-Server](#http-server) \ +> is configured correctly, so the auto-discovery feature works correctly. \ +> Otherwise, all clients discover each other mutually, independently of their network status. > > If this flag is set to `"true"` each peer that connects to the PairDrop server will produce a log to STDOUT like this: > ``` @@ -97,7 +112,7 @@ Set options by using the following flags in the `docker run` command: > if IP is private, '127.0.0.1' is used instead > ----DEBUGGING-PEER-IP-END---- > ``` -> If the IP PairDrop uses is the public IP of your device everything is correctly setup. +> If the IP PairDrop uses is the public IP of your device, everything is set up correctly. \ >To find out your devices public IP visit https://www.whatismyip.com/. > > To preserve your clients' privacy, **never use this flag in production!** @@ -109,13 +124,17 @@ Set options by using the following flags in the `docker run` command: ```bash docker run -d --restart=unless-stopped --name=pairdrop -p 127.0.0.1:3000:3000 ghcr.io/schlagmichdoch/pairdrop npm run start:prod ``` -> You must use a server proxy to set the X-Forwarded-For to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). +> You must use a server proxy to set the X-Forwarded-For to prevent \ +> all clients from discovering each other (See [#HTTP-Server](#http-server)). > -> To prevent bypassing the proxy by reaching the docker container directly, `127.0.0.1` is specified in the run command. +> To prevent bypassing the proxy by reaching the Docker container directly, \ +> `127.0.0.1` is specified in the run command. > -> To specify options replace `npm run start:prod` according to [the documentation below.](#options--flags-1) +> To specify options replace `npm run start:prod` \ +> according to [the documentation below.](#options--flags-1) -> The Docker Image includes a Healthcheck. To learn more see [Docker Swarm Usage](docker-swarm-usage.md#docker-swarm-usage) +> The Docker Image includes a healthcheck. \ +> Read more about [Docker Swarm Usage](docker-swarm-usage.md#docker-swarm-usage). ### Docker Image self-built #### Build the image @@ -130,13 +149,17 @@ docker build --pull . -f Dockerfile -t pairdrop ```bash docker run -d --restart=unless-stopped --name=pairdrop -p 127.0.0.1:3000:3000 -it pairdrop npm run start:prod ``` -> You must use a server proxy to set the X-Forwarded-For to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). +> You must use a server proxy to set the X-Forwarded-For \ +> to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). > -> To prevent bypassing the proxy by reaching the docker container directly, `127.0.0.1` is specified in the run command. +> To prevent bypassing the proxy by reaching the Docker container \ +> directly, `127.0.0.1` is specified in the run command. > -> To specify options replace `npm run start:prod` according to [the documentation below.](#options--flags-1) +> To specify options replace `npm run start:prod` \ +> according to [the documentation below.](#options--flags-1) -> The Docker Image includes a Healthcheck. To learn more see [Docker Swarm Usage](docker-swarm-usage.md#docker-swarm-usage) +> The Docker Image includes a Healthcheck. \ +Read more about [Docker Swarm Usage](docker-swarm-usage.md#docker-swarm-usage).
@@ -162,9 +185,11 @@ services: Run the compose file with `docker compose up -d`. -> You must use a server proxy to set the X-Forwarded-For to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). +> You must use a server proxy to set the X-Forwarded-For \ +> to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). > -> To prevent bypassing the proxy by reaching the docker container directly, `127.0.0.1` is specified in the run command. +> To prevent bypassing the proxy by reaching the Docker container \ +> directly, `127.0.0.1` is specified in the run command.
@@ -190,7 +215,7 @@ or npm start ``` -> Remember to check your IP Address using your OS command to see where you can access the server. +> Remember to check your IP address using your OS command to see where you can access the server. > By default, the node server listens on port 3000. @@ -212,7 +237,8 @@ $env:PORT=3010; npm start ```bash IPV6_LOCALIZE=4 ``` -> Truncate a portion of the client IPv6 address to make peers more discoverable. See [Options/Flags](#options--flags) above. +> Truncate a portion of the client IPv6 address to make peers more discoverable. \ +> See [Options/Flags](#options--flags) above. #### Specify STUN/TURN Server On Unix based systems @@ -223,10 +249,12 @@ On Windows ```bash $env:RTC_CONFIG="rtc_config.json"; npm start ``` -> Specify the STUN/TURN servers PairDrop clients use by setting `RTC_CONFIG` to a JSON file including the configuration. +> Specify the STUN/TURN servers PairDrop clients use by setting `RTC_CONFIG` \ +> to a JSON file including the configuration. \ > You can use `pairdrop/rtc_config_example.json` as a starting point. > -> To host your own TURN server you can follow this guide: https://gabrieltanner.org/blog/turn-server/ +> To host your own TURN server you can follow this guide: \ +> https://gabrieltanner.org/blog/turn-server/ > > Default configuration: > ```json @@ -250,10 +278,13 @@ On Windows $env:DEBUG_MODE="true"; npm start ``` -> Use this flag to enable debugging information about the connecting peers IP addresses. This is quite useful to check whether the [#HTTP-Server](#http-server) -> is configured correctly, so the auto discovery feature works correctly. Otherwise, all clients discover each other mutually, independently of their network status. +> Use this flag to enable debugging info about the connecting peers IP addresses. \ +> This is quite useful to check whether the [#HTTP-Server](#http-server) \ +> is configured correctly, so the auto discovery feature works correctly. \ +> Otherwise, all clients discover each other mutually, independently of their network status. > -> If this flag is set to `"true"` each peer that connects to the PairDrop server will produce a log to STDOUT like this: +> If this flag is set to `"true"` each peer that connects to the \ +> PairDrop server will produce a log to STDOUT like this: > ``` > ----DEBUGGING-PEER-IP-START---- > remoteAddress: ::ffff:172.17.0.1 @@ -264,10 +295,10 @@ $env:DEBUG_MODE="true"; npm start > if IP is private, '127.0.0.1' is used instead > ----DEBUGGING-PEER-IP-END---- > ``` -> If the IP PairDrop uses is the public IP of your device everything is correctly setup. ->To find out your devices public IP visit https://www.whatismyip.com/. +> If the IP PairDrop uses is the public IP of your device everything is set up correctly. \ +>Find your devices public IP by visiting https://www.whatismyip.com/. > -> To preserve your clients' privacy, **never use this flag in production!** +> Preserve your clients' privacy. **Never use this flag in production!** ### Options / Flags @@ -277,9 +308,11 @@ npm start -- --localhost-only ``` > Only allow connections from localhost. > -> You must use a server proxy to set the X-Forwarded-For to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). +> You must use a server proxy to set the X-Forwarded-For \ +> to prevent all clients from discovering each other (See [#HTTP-Server](#http-server)). > -> Use this when deploying PairDrop with node to prevent bypassing the proxy by reaching the docker container directly. +> Use this when deploying PairDrop with node to prevent \ +> bypassing the proxy by reaching the Docker container directly. #### Automatic restart on error ```bash @@ -301,13 +334,19 @@ npm start -- --rate-limit ```bash npm start -- --include-ws-fallback ``` -> Provides PairDrop to clients with an included websocket fallback if the peer to peer WebRTC connection is not available to the client. +> Provides PairDrop to clients with an included websocket fallback \ +> if the peer to peer WebRTC connection is not available to the client. > -> This is not used on the official https://pairdrop.net, but you can activate it on your self-hosted instance. -> This is especially useful if you connect to your instance via a VPN as most VPN services block WebRTC completely in order to hide your real IP address ([read more](https://privacysavvy.com/security/safe-browsing/disable-webrtc-chrome-firefox-safari-opera-edge/)). +> This is not used on the official https://pairdrop.net, \ +but you can activate it on your self-hosted instance. \ +> This is especially useful if you connect to your instance \ +> via a VPN as most VPN services block WebRTC completely in order to hide your real IP address. +> ([Read more](https://privacysavvy.com/security/safe-browsing/disable-webrtc-chrome-firefox-safari-opera-edge/)). > -> **Warning:** All traffic sent between devices using this fallback is routed through the server and therefor not peer to peer! -> Beware that the traffic routed via this fallback is readable by the server. Only ever use this on instances you can trust. +> **Warning:** All traffic sent between devices using this fallback \ +> is routed through the server and therefor not peer to peer! \ +> Beware that the traffic routed via this fallback is readable by the server. \ +> Only ever use this on instances you can trust. \ > Additionally, beware that all traffic using this fallback debits the servers data plan.
@@ -321,10 +360,12 @@ npm run start:prod ```bash npm run start:prod -- --localhost-only --include-ws-fallback ``` -> To prevent connections to the node server from bypassing the proxy server you should always use "--localhost-only" on production. +> To prevent connections to the node server from bypassing \ +> the proxy server you should always use "--localhost-only" on production. ## HTTP-Server -When running PairDrop, the `X-Forwarded-For` header has to be set by a proxy. Otherwise, all clients will be mutually visible. +When running PairDrop, the `X-Forwarded-For` header has to be set by a proxy. \ +Otherwise, all clients will be mutually visible. To check if your setup is configured correctly [use the environment variable `DEBUG_MODE="true"`](#debug-mode). @@ -405,10 +446,10 @@ a2enmod proxy_wstunnel
-Create a new configuration file under `/etc/apache2/sites-available` (on debian) +Create a new configuration file under `/etc/apache2/sites-available` (on Debian) **pairdrop.conf** -#### Allow http and https requests +#### Allow HTTP and HTTPS requests ```apacheconf ProxyPass / http://127.0.0.1:3000/ @@ -425,7 +466,7 @@ Create a new configuration file under `/etc/apache2/sites-available` (on debian) RewriteRule ^/?(.*) "wws://127.0.0.1:3000/$1" [P,L] ``` -#### Automatic http to https redirect: +#### Automatic HTTP to HTTPS redirect: ```apacheconf Redirect permanent / https://127.0.0.1:3000/ @@ -438,7 +479,7 @@ Create a new configuration file under `/etc/apache2/sites-available` (on debian) RewriteRule ^/?(.*) "wws://127.0.0.1:3000/$1" [P,L] ``` -Activate the new virtual host and reload apache: +Activate the new virtual host and reload Apache: ```bash a2ensite pairdrop ``` @@ -462,28 +503,38 @@ Then, clone the repository and run docker-compose: docker-compose up -d ``` -Now point your browser to `http://localhost:8080`. +Now point your web browser to `http://localhost:8080`. -- To restart the containers run `docker-compose restart`. -- To stop the containers run `docker-compose stop`. -- To debug the NodeJS server run `docker logs pairdrop_node_1`. +- To restart the containers, run `docker-compose restart`. +- To stop the containers, run `docker-compose stop`. +- To debug the NodeJS server, run `docker logs pairdrop_node_1`.
## Testing PWA related features -PWAs require that the app is served under a correctly set up and trusted TLS endpoint. +PWAs requires the app to be served under a correctly set up and trusted TLS endpoint. -The nginx container creates a CA certificate and a website certificate for you. To correctly set the common name of the certificate, you need to change the FQDN environment variable in `docker/fqdn.env` to the fully qualified domain name of your workstation. +The NGINX container creates a CA certificate and a website certificate for you. \ +To correctly set the common name of the certificate, \ +you need to change the FQDN environment variable in `docker/fqdn.env` \ +to the fully qualified domain name of your workstation. -If you want to test PWA features, you need to trust the CA of the certificate for your local deployment. For your convenience, you can download the crt file from `http://:8080/ca.crt`. Install that certificate to the trust store of your operating system. -- On Windows, make sure to install it to the `Trusted Root Certification Authorities` store. -- On macOS, double-click the installed CA certificate in `Keychain Access`, expand `Trust`, and select `Always Trust` for SSL. -- Firefox uses its own trust store. To install the CA, point Firefox at `http://:8080/ca.crt`. When prompted, select `Trust this CA to identify websites` and click OK. -- When using Chrome, you need to restart Chrome so it reloads the trust store (`chrome://restart`). Additionally, after installing a new cert, you need to clear the Storage (DevTools -> Application -> Clear storage -> Clear site data). +If you want to test PWA features, you need to trust the CA of the certificate for your local deployment. \ +For your convenience, you can download the crt file from `http://:8080/ca.crt`. \ +Install that certificate to the trust store of your operating system. \ +- On Windows, make sure to install it to the `Trusted Root Certification Authorities` store. \ +- On macOS, double-click the installed CA certificate in `Keychain Access`, \ +- expand `Trust`, and select `Always Trust` for SSL. \ +- Firefox uses its own trust store. To install the CA, \ +- point Firefox at `http://:8080/ca.crt`. \ +- When prompted, select `Trust this CA to identify websites` and click \"OK\". \ +- When using Chrome, you need to restart Chrome so it reloads the trust store (`chrome://restart`). \ +- Additionally, after installing a new cert, \ +- you need to clear the Storage (DevTools → Application → Clear storage → Clear site data). Please note that the certificates (CA and webserver cert) expire after a day. -Also, whenever you restart the nginx docker, container new certificates are created. +Also, whenever you restart the NGINX Docker, container new certificates are created. The site is served on `https://:8443`.