mirrors/PairDrop
1
0
Fork 0
mirror of https://github.com/schlagmichdoch/PairDrop.git synced 2025-04-20 07:05:05 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

host-your-own reworked

Browse source
This commit is contained in:
Allan Nordhøy 2023-07-08 13:14:07 +00:00 • committed by GitHub
parent 044d7aa20d
commit 9424f704bf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 111 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

171
docs/host-your-own.md
View file

@ -3,9 +3,10 @@ The easiest way to get PairDrop up and running is by using Docker.
> <b>TURN server for Internet Transfer</b>
>
> 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).
<br>
@ -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.
<br>
@ -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.
<br>
@ -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
<br>
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
<VirtualHost *:80>
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]
</VirtualHost>
```
#### Automatic http to https redirect:
#### Automatic HTTP to HTTPS redirect:
```apacheconf
<VirtualHost *:80>
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]
</VirtualHost>
```
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`.
<br>
## 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://<Your FQDN>: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://<Your FQDN>: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://<Your FQDN>: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://<Your FQDN>: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://<Your FQDN>:8443`.