From 64d69a0ed9e9da281072f39c8b62ebb92a5739ac Mon Sep 17 00:00:00 2001 From: schlagmichdoch Date: Sun, 12 Feb 2023 02:30:07 +0100 Subject: [PATCH] restructure host-your-own.md documentation and prepare moving files needed only for local development into separate branch --- docker-compose.yml | 4 +- .../nginx/{development.conf => default.conf} | 0 docker/nginx/production.conf | 37 --- docs/host-your-own.md | 221 ++++++------------ docs/how-to.md | 2 + docs/technical-documentation.md | 3 + 6 files changed, 72 insertions(+), 195 deletions(-) rename docker/nginx/{development.conf => default.conf} (100%) delete mode 100644 docker/nginx/production.conf diff --git a/docker-compose.yml b/docker-compose.yml index 3788105..a3982a8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -17,9 +17,7 @@ services: - ./public:/usr/share/nginx/html - ./docker/certs:/etc/ssl/certs - ./docker/openssl:/mnt/openssl - # Use production.conf instead of development.conf to redirect http to https (/ca.crt still available via http) - - ./docker/nginx/development.conf:/etc/nginx/conf.d/default.conf -# - ./docker/nginx/production.conf:/etc/nginx/conf.d/default.conf + - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf ports: - "8080:80" - "8443:443" diff --git a/docker/nginx/development.conf b/docker/nginx/default.conf similarity index 100% rename from docker/nginx/development.conf rename to docker/nginx/default.conf diff --git a/docker/nginx/production.conf b/docker/nginx/production.conf deleted file mode 100644 index 8a7a6df..0000000 --- a/docker/nginx/production.conf +++ /dev/null @@ -1,37 +0,0 @@ -server { - listen 80; - - expires epoch; - - location / { - return 301 https://$host:8443$request_uri; - } - - location /ca.crt { - alias /etc/ssl/certs/snapdropCA.crt; - } - # To allow POST on static pages - error_page 405 =200 $uri; -} - -server { - listen 443 ssl http2; - ssl_certificate /etc/ssl/certs/snapdrop-dev.crt; - ssl_certificate_key /etc/ssl/certs/snapdrop-dev.key; - - expires epoch; - - location / { - proxy_connect_timeout 300; - proxy_pass http://node:3000; - proxy_set_header Connection "upgrade"; - proxy_set_header Upgrade $http_upgrade; - } - - location /ca.crt { - alias /etc/ssl/certs/snapdropCA.crt; - } - # To allow POST on static pages - error_page 405 =200 $uri; -} - diff --git a/docs/host-your-own.md b/docs/host-your-own.md index 41cf27f..ff32e26 100644 --- a/docs/host-your-own.md +++ b/docs/host-your-own.md @@ -1,46 +1,4 @@ -# Local Development -## Install - -First, [Install docker with docker-compose.](https://docs.docker.com/compose/install/) - -Then, clone the repository and run docker-compose: -```shell - git clone https://github.com/schlagmichdoch/PairDrop.git - - cd PairDrop - - docker-compose up -d -``` -Now point your 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`. - - -
- -## Testing PWA related features -PWAs require that the app is 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. - -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. - -The site is served on `https://:8443`. - - # Deployment Notes -The client expects the server at http(s)://your.domain/server. - -When serving the node server behind a proxy, the `X-Forwarded-For` header has to be set by the proxy. Otherwise, all clients that are served by the proxy will be mutually visible. ## Deployment with node @@ -115,117 +73,28 @@ npm start -- --include-ws-fallback npm run start:prod ``` -## HTTP-Server -You must use nginx or apache to set the x-forwarded-for header correctly. Otherwise, all clients will be mutually visible. - -### Using nginx -#### Allow http and https requests -``` -server { - listen 80; - - expires epoch; - - location / { - proxy_connect_timeout 300; - proxy_pass http://node:3000; - proxy_set_header Connection "upgrade"; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header X-Forwarded-for $remote_addr; - } -} - -server { - listen 443 ssl http2; - ssl_certificate /etc/ssl/certs/pairdrop-dev.crt; - ssl_certificate_key /etc/ssl/certs/pairdrop-dev.key; - - expires epoch; - - location / { - proxy_connect_timeout 300; - proxy_pass http://node:3000; - proxy_set_header Connection "upgrade"; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header X-Forwarded-for $remote_addr; - } -} -``` -#### Automatic http to https redirect: -``` -server { - listen 80; - - expires epoch; - - location / { - return 301 https://$host:8443$request_uri; - } -} - -server { - listen 443 ssl http2; - ssl_certificate /etc/ssl/certs/pairdrop-dev.crt; - ssl_certificate_key /etc/ssl/certs/pairdrop-dev.key; - - expires epoch; - - location / { - proxy_connect_timeout 300; - proxy_pass http://node:3000; - proxy_set_header Connection "upgrade"; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header X-Forwarded-for $remote_addr; - } -} -``` - - - -### Using Apache -#### Allow http and https requests -``` - - RewriteEngine on - RewriteCond %{HTTP:Upgrade} websocket [NC] - RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "ws://127.0.0.1:3000/$1" [P,L] - - - RewriteEngine on - RewriteCond %{HTTP:Upgrade} websocket [NC] - RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "wws://127.0.0.1:3000/$1" [P,L] - -``` -#### Automatic http to https redirect: -``` - - Redirect permanent / https://127.0.0.1:3000/ - - - RewriteEngine on - RewriteCond %{HTTP:Upgrade} websocket [NC] - RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "wws://127.0.0.1:3000/$1" [P,L] - -``` ## Deployment with Docker The easiest way to get PairDrop up and running is by using Docker. -By default, docker listens on ports 8080 (http) and 8443 (https) (specified in `docker-compose.yml`). +By default, docker listens on port 3000 for (http and https). -When running PairDrop via Docker, the `X-Forwarded-For` header has to be set by a proxy. Otherwise, all clients will be mutually visible. +By default, PairDrop is started with auto-start and rate-limit enabled. To run PairDrop with [the options listed above](#public-run) you have to edit the `CMD` command in the Dockerfile accordingly. -To run PairDrop with [the options listed above](#public-run) you have to edit the `npm start` command in the `docker-compose.yml` accordingly. +### Build the image +```bash +docker build . -f Dockerfile -t pairdrop +``` +> A GitHub action is set up to do this step automatically -### Installation -[See Local Development > Install](#install) +### Run the image +```bash +docker run -d pairdrop +``` -Use nginx or apache to set the header correctly: +## HTTP-Server +When running PairDrop, the `X-Forwarded-For` header has to be set by a proxy. Otherwise, all clients will be mutually visible. ### Using nginx -(This differs from `/docker/nginx/*.conf`) #### Allow http and https requests ``` server { @@ -235,7 +104,7 @@ server { location / { proxy_connect_timeout 300; - proxy_pass http://127.0.0.1:8080; + proxy_pass http://127.0.0.1:3000; proxy_set_header Connection "upgrade"; proxy_set_header Upgrade $http_upgrade; proxy_set_header X-Forwarded-for $remote_addr; @@ -251,13 +120,14 @@ server { location / { proxy_connect_timeout 300; - proxy_pass http://127.0.0.1:8443; + proxy_pass http://127.0.0.1:3000; proxy_set_header Connection "upgrade"; proxy_set_header Upgrade $http_upgrade; proxy_set_header X-Forwarded-for $remote_addr; } } ``` + #### Automatic http to https redirect: ``` server { @@ -266,7 +136,7 @@ server { expires epoch; location / { - return 301 https://$host:8443$request_uri; + return 301 https://$host:3000$request_uri; } } @@ -279,7 +149,7 @@ server { location / { proxy_connect_timeout 300; - proxy_pass http://127.0.0.1:8443; + proxy_pass http://127.0.0.1:3000; proxy_set_header Connection "upgrade"; proxy_set_header Upgrade $http_upgrade; proxy_set_header X-Forwarded-for $remote_addr; @@ -307,31 +177,31 @@ Create a new configuration file under `/etc/apache2/sites-available` (on debian) #### Allow http and https requests ``` - ProxyPass / http://127.0.0.1:8080/ + ProxyPass / http://127.0.0.1:3000/ RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "ws://127.0.0.1:8080/$1" [P,L] + RewriteRule ^/?(.*) "ws://127.0.0.1:3000/$1" [P,L] - ProxyPass / https://127.0.0.1:8443/ + ProxyPass / https://127.0.0.1:3000/ RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "wws://127.0.0.1:8443/$1" [P,L] + RewriteRule ^/?(.*) "wws://127.0.0.1:3000/$1" [P,L] ``` #### Automatic http to https redirect: ``` - Redirect permanent / https://127.0.0.1:8443/ + Redirect permanent / https://127.0.0.1:3000/ - ProxyPass / https://127.0.0.1:8443/ + ProxyPass / https://127.0.0.1:3000/ RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "wws://127.0.0.1:8443/$1" [P,L] + RewriteRule ^/?(.*) "wws://127.0.0.1:3000/$1" [P,L] ``` Activate the new virtual host and reload apache: @@ -342,4 +212,45 @@ a2ensite pairdrop service apache2 reload ``` +# Local Development +## Install +All files needed for developing are available on the branch `dev`. + +First, [Install docker with docker-compose.](https://docs.docker.com/compose/install/) + +Then, clone the repository and run docker-compose: +```shell + git clone https://github.com/schlagmichdoch/PairDrop.git + + cd PairDrop + + git checkout dev + + docker-compose up -d +``` +Now point your 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`. + + +
+ +## Testing PWA related features +PWAs require that the app is 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. + +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. + +The site is served on `https://:8443`. + [< Back](/README.md) diff --git a/docs/how-to.md b/docs/how-to.md index e6eb816..18c0fbd 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -37,3 +37,5 @@ The [Web Share Target API](https://developer.mozilla.org/en-US/docs/Web/Manifest When the PWA is installed, it should register itself to the share-menu of the device automatically. Please test this feature and create an issue if it does not work. + +[< Back](/README.md) diff --git a/docs/technical-documentation.md b/docs/technical-documentation.md index 199f2b1..bf050ae 100644 --- a/docs/technical-documentation.md +++ b/docs/technical-documentation.md @@ -45,3 +45,6 @@ to each other analog to peers with the same ip-address are discoverable to each What I really like about this approach, and the reason why I implemented it, is that devices on the same network are always visible regardless whether any devices are paired or not. The main user flow is never obstructed. Paired devices are simply shown additionally. This makes it in my idea better than the idea of using a room system as [discussed here](https://github.com/RobinLinus/snapdrop/pull/214). + + +[< Back](/README.md)