Docker Swarm Usage Copy Section

Docker Swarm Usage

Healthcheck Copy Chapter

The Docker Image includes a health check with the following options:

--interval=30s

Specifies the time interval to run the health check. \

In this case, the health check is performed every 30 seconds.

--timeout=10s

Specifies the amount of time to wait for a response from the \"HEALTHCHECK\" command. \

If the response does not arrive within 10 seconds, the health check fails.

--start-period=5s

Specifies the amount of time to wait before starting the health check process. \

In this case, the health check process will begin 5 seconds after the container is started.

--retries=3

Specifies the number of times Docker should retry the health check \

before considering the container to be unhealthy.

The CMD instruction is used to define the command that will be run as part of the health check. \
In this case, the command is wget --quiet --tries=1 --spider http://localhost:3000/ || exit 1. \
This command will attempt to connect to http://localhost:3000/ \
and if it fails it will exit with a status code of 1. \
If this command returns a status code other than 0, the health check fails.

Overall, this \"HEALTHCHECK\" instruction is defining a health check process \
that runs every 30 seconds, and waits up to 10 seconds for a response, \
begins 5 seconds after the container is started, and retries up to 3 times. \
The health check attempts to connect to http://localhost:3000/ \
and will considers the container unhealthy if unable to connect.

---

Faq Copy Section

Frequently Asked Questions

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
Help! I can't install the PWA!
</summary>

<br>

Here is a good guide on how to install PWAs on different platforms: \
https://www.cdc.gov/niosh/mining/tools/installpwa.html

Chromium-based browser on Desktop (Chrome, Edge, Vivaldi, Brave, etc.) \
Easily install PairDrop PWA on your desktop by clicking the install-button in the top-right corner while on pairdrop.net.

<img width="400" src="pwa-install.png" alt="Example on how to install a pwa with Edge">

Desktop Firefox \
On Firefox, PWAs are installable via this browser extensions

Android \
PWAs are installable only by using Google Chrome or Samsung Browser:
1. Visit pairdrop.net
2. Click _Install_ on the installation pop-up or use the three-dot-menu and click on _Add to Home screen_
3. Click _Add_ on the pop-up

iOS \
PWAs are installable only by using Safari:
1. Visit pairdrop.net
2. Click on the share icon
3. Click _Add to Home Screen_
4. Click _Add_ in the top right corner

<br>

Self-Hosted Instance? \
To be able to install the PWA from a self-hosted instance, the connection needs to be established through HTTPS.
See this host your own section for more info.

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
Shortcuts?
</summary>

<br>

Available shortcuts:
- Send a message with CTRL + ENTER
- Close all "Send" and "Pair" dialogs by pressing Esc.
- Copy a received message to the clipboard with CTRL/⌘ + C.
- Accept file-transfer requests with Enter and decline with Esc.
<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
How to save images directly to the gallery on iOS?
</summary>

<br>

~~Apparently, iOS does not allow images shared from a website to be saved to the gallery directly.~~
~~It simply does not offer that option for images shared from a website.~~

~~iOS Shortcuts saves the day:~~ \
I created a simple iOS shortcut that takes your photos and saves them to your gallery:
https://routinehub.co/shortcut/13988/

Update: \
Apparently, this was only a bug that is fixed in recent iOS version (https://github.com/WebKit/WebKit/pull/13111). \
If you use an older affected iOS version this might still be of use. \
Luckily, you can now simply use Save Image/Save X Images 🎉

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
Is it possible to send files or text directly from the "Context" or "Share" menu?
</summary>

<br>

Yes, it finally is.
* Send files directly from the "Context" menu on Windows
* Send directly from the "Share" menu on iOS
* Send directly from the "Share" menu on Android

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
Is it possible to send files or text directly via CLI?
</summary>

<br>

Yes.

* Send directly from a command-line interface

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
Are there any third-party Apps?
</summary>

<br>

These third-party apps are compatible with PairDrop:

1. Snapdrop Android App
2. Snapdrop for Firefox (Addon)
3. Feel free to make one :)

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
What about the connection? Is it a P2P connection directly from device to device or is there any third-party-server?
</summary>

<br>

It uses a WebRTC peer-to-peer connection.
WebRTC needs a signaling server that is only used to establish a connection.
The server is not involved in the file transfer.

If the devices are on the same network,
none of your files are ever sent to any server.

If your devices are paired and behind a NAT,
the PairDrop TURN Server is used to route your files and messages.
See the Technical Documentation
to learn more about STUN, TURN and WebRTC.

If you host your own instance
and want to support devices that do not support WebRTC,
you can start the PairDrop instance with an activated WebSocket fallback.

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
What about privacy? Will files be saved on third-party servers?
</summary>

<br>

Files are sent directly between peers.
PairDrop doesn't even use a database.
If curious, study the signaling server.
WebRTC encrypts the files in transit.

If the devices are on the same network,
none of your files are ever sent to any server.

If your devices are paired and behind a NAT,
the PairDrop TURN Server is used to route your files and messages.
See the Technical Documentation
to learn more about STUN, TURN and WebRTC.

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
What about security? Are my files encrypted while sent between the computers?
</summary>

<br>

Yes. Your files are sent using WebRTC, encrypting them in transit.
Still you have to trust the PairDrop server. To ensure the connection is secure and there is no MITM there is a plan to make PairDrop
zero trust by encrypting the signaling and implementing a verification process. See issue #180 to keep updated.

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
Transferring many files with paired devices takes too long
</summary>

<br>

Naturally, if traffic needs to be routed through the TURN server
because your devices are behind different NATs, transfer speed decreases.

You can open a hotspot on one of your devices to bridge the connection,
which omits the need of the TURN server.

- How to open a hotspot on Windows
- How to open a hotspot on macOS
- Library to open a hotspot on Linux

You can also use mobile hotspots on phones to do that.
Then, all data should be sent directly between devices and not use your data plan.

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
Why don't you implement feature xyz?
</summary>

<br>

Snapdrop and PairDrop are a study in radical simplicity.
The user interface is insanely simple.
Features are chosen very carefully because complexity grows quadratically
since every feature potentially interferes with each other feature.
We focus very narrowly on a single use case: instant file transfer.
Not facilitating optimal edge-cases means better flow for average users.
Don't be sad. We may decline your feature request for the sake of simplicity.

Read Insanely Simple: The Obsession that Drives Apple's Success,
and/or Thinking, Fast and Slow to learn more.

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
PairDrop is awesome. How can I support it?
</summary>

<br>

* Buy me a coffee to pay for the domain and the server, and support libre software.
* File bugs, give feedback, submit suggestions
* Share PairDrop on social media.
* Fix bugs and create a pull request.
* Do some security analysis and make suggestions.
* Participate in active discussions

<br>

</details>

<details>
<summary style="font-size:1.25em;margin-top: 24px; margin-bottom: 16px; font-weight: var(--base-text-weight-semibold, 600); line-height: 1.25;">
How does it work?
</summary>

<br>

See here for info about the technical implementation

<br>

</details>

< Back

---

Host Your Own Copy Section

Deployment Notes

TURN server for Internet Transfer Copy Chapter

Beware that you have to host your own TURN server to enable transfers between different networks.

Follow this guide to either install coturn directly on your system (Step 1)
or deploy it via Docker (Step 5).

You can use the docker-compose-coturn.yml in this repository. See Coturn and PairDrop via Docker Compose.

Alternatively, use a free, pre-configured TURN server like OpenRelay

<br>

PairDrop via HTTPS Copy Chapter

On some browsers PairDrop must be served over TLS in order for some features to work properly.
These may include:
- Copying an incoming message via the 'copy' button
- Installing PairDrop as PWA
- Persistent pairing of devices
- Changing of the display name
- Notifications

Naturally, this is also recommended to increase security.

<br>

Deployment with Docker Copy Chapter

The easiest way to get PairDrop up and running is by using Docker.

Docker Image from Docker Hub Copy Section

docker run -d --restart=unless-stopped --name=pairdrop -p 127.0.0.1:3000:3000 lscr.io/linuxserver/pairdrop

This image is hosted by linuxserver.io. For more information visit https://hub.docker.com/r/linuxserver/pairdrop

<br>

Docker Image from GitHub Container Registry (ghcr.io) Copy Section

docker run -d --restart=unless-stopped --name=pairdrop -p 127.0.0.1:3000:3000 ghcr.io/schlagmichdoch/pairdrop

<br>

Docker Image self-built Copy Section

#### Build the image

docker build --pull . -f Dockerfile -t pairdrop

A GitHub action is set up to do this step automatically at the release of new versions.

> --pull ensures always the latest node image is used.

#### Run the image

docker run -d --restart=unless-stopped --name=pairdrop -p 127.0.0.1:3000:3000 -it pairdrop

You must use a server proxy to set the X-Forwarded-For header

to prevent all clients from discovering each other (See #HTTP-Server).

> To prevent bypassing the proxy by reaching the docker container directly,

127.0.0.1 is specified in the run command.

<br>

Flags Copy Section

Set options by using the following flags in the docker run command:

#### Port

-p 127.0.0.1:8080:3000

Specify the port used by the docker image

> - 3000 -> -p 127.0.0.1:3000:3000

- 8080 -> -p 127.0.0.1:8080:3000

#### Set Environment Variables via Docker

Environment Variables are set directly in the docker run command: \
e.g. docker run -p 127.0.0.1:3000:3000 -it pairdrop -e DEBUG_MODE="true"

Overview of available Environment Variables are found here.

Example:

docker run -d \
    --name=pairdrop \
    --restart=unless-stopped \
    -p 127.0.0.1:3000:3000 \
    -e PUID=1000 \
    -e PGID=1000 \
    -e WS_SERVER=false \
    -e WS_FALLBACK=false \
    -e RTC_CONFIG=false \
    -e RATE_LIMIT=false \
    -e DEBUG_MODE=false \
    -e TZ=Etc/UTC \
    lscr.io/linuxserver/pairdrop

<br>

Deployment with Docker Compose Copy Chapter

Here's an example docker compose file:

version: "3"
services:
    pairdrop:
        image: "lscr.io/linuxserver/pairdrop:latest"
        container_name: pairdrop
        restart: unless-stopped
        environment:
            - PUID=1000 # UID to run the application as
            - PGID=1000 # GID to run the application as
            - WS_FALLBACK=false # Set to true to enable websocket fallback if the peer to peer WebRTC connection is not available to the client.
            - RATE_LIMIT=false # Set to true to limit clients to 1000 requests per 5 min.
            - RTC_CONFIG=false # Set to the path of a file that specifies the STUN/TURN servers.
            - DEBUG_MODE=false # Set to true to debug container and peer connections.
            - TZ=Etc/UTC # Time Zone
        ports:
            - "127.0.0.1:3000:3000" # Web UI

Run the compose file with docker compose up -d.

You must use a server proxy to set the X-Forwarded-For header

to prevent all clients from discovering each other (See #HTTP-Server).

> To prevent bypassing the proxy by reaching the Docker container

directly, 127.0.0.1 is specified in the ports argument.

<br>

Deployment with Node.js Copy Chapter

Clone this repository and enter the folder

git clone https://github.com/schlagmichdoch/PairDrop.git && cd PairDrop

Install all dependencies with NPM:

npm install

Start the server with:

npm start

By default, the node server listens on port 3000.

<br>

Options / Flags Copy Section

These are some flags only reasonable when deploying via Node.js

#### Port

PORT=3000

Default: 3000

> Environment variable to specify the port used by the Node.js server \

e.g. PORT=3010 npm start

#### Local Run

npm start -- --localhost-only

Only allow connections from localhost.

> You must use a server proxy to set the X-Forwarded-For header

to prevent all clients from discovering each other (See #HTTP-Server).

> Use this when deploying PairDrop with node to prevent

bypassing the reverse proxy by reaching the Node.js server directly.

#### Automatic restart on error

npm start -- --auto-restart

Restarts server automatically on error

#### Production (autostart and rate-limit)

npm run start:prod

shortcut for RATE_LIMIT=5 npm start -- --auto-restart

#### Production (autostart, rate-limit, localhost-only)

npm run start:prod -- --localhost-only

To prevent connections to the node server from bypassing \

the proxy server you should always use "--localhost-only" on production.

#### Set Environment Variables via Node.js

To specify environment variables set them in the run command in front of npm start.
The syntax is different on Unix and Windows.

On Unix based systems

PORT=3000 RTC_CONFIG="rtc_config.json" npm start

On Windows

$env:PORT=3000 RTC_CONFIG="rtc_config.json"; npm start

Overview of available Environment Variables are found here.

<br>

Environment Variables Copy Chapter

Debug Mode Copy Section

DEBUG_MODE="true"

Default: false

> Logs the used environment variables for debugging.

> Prints debugging information about the connecting peers IP addresses.

> This is quite useful to check whether the #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:

> ``

`

RATE_LIMIT=1

Default: false

> 1. Start PairDrop with DEBUG_MODE=True and RATE_LIMIT=1

2. Make a get request to /ip of the PairDrop instance (e.g. https://pairdrop-example.net/ip)

4. You have found the correct number if the IP addresses match. If not, then increase RATE_LIMIT by one and redo 1. - 4.

IPV6_LOCALIZE=4

Default: false

> The flag must be set to an integer between 1 and 7. \

to match the client IP against. The most common value would be 4, \

which will group peers within the same /64 subnet.


<br>

Websocket Fallback (for VPN) Copy Section

WS_FALLBACK=true

Default: false

RTC_CONFIG="rtc_config.json"

Default: false

RTC_CONFIG to a JSON file including the configuration. \

You can use rtc_config_example.json as a starting point.

> `json

`

<br>

You can host an instance that uses another signaling server
This can be useful if you don't want to trust the client files that are hosted on another instance but still want to connect to devices that use https://pairdrop.net.

Specify Signaling Server Copy Section

SIGNALING_SERVER="pairdrop.net"

Default: false

> By using SIGNALING_SERVER, you can host an instance that uses another signaling server.

> SIGNALING_SERVER must be a valid url without the protocol prefix.

Examples of valid values: pairdrop.net, pairdrop.your-domain.com:3000, your-domain.com/pairdrop

<br>

Customizable buttons for the _About PairDrop_ page Copy Section

DONATION_BUTTON_ACTIVE=true
DONATION_BUTTON_LINK="https://www.buymeacoffee.com/pairdrop"
DONATION_BUTTON_TITLE="Buy me a coffee"
TWITTER_BUTTON_ACTIVE=true
TWITTER_BUTTON_LINK="https://twitter.com/account"
TWITTER_BUTTON_TITLE="Find me on Twitter"
MASTODON_BUTTON_ACTIVE=true
MASTODON_BUTTON_LINK="https://mastodon.social/account"
MASTODON_BUTTON_TITLE="Find me on Mastodon"
BLUESKY_BUTTON_ACTIVE=true
BLUESKY_BUTTON_LINK="https://bsky.app/profile/account"
BLUESKY_BUTTON_TITLE="Find me on Bluesky"
CUSTOM_BUTTON_ACTIVE=true
CUSTOM_BUTTON_LINK="https://your-custom-social-network.net/account"
CUSTOM_BUTTON_TITLE="Find me on this custom social network"
PRIVACYPOLICY_BUTTON_ACTIVE=true
PRIVACYPOLICY_BUTTON_LINK="https://link-to-your-privacy-policy.net"
PRIVACYPOLICY_BUTTON_TITLE="Open our privacy policy"

Default: unset

> _BUTTON_ACTIVE: set this to true to show a natively hidden button or to false to hide a normally shown button

_BUTTON_LINK: set this to any URL to overwrite the href attribute of the button

_BUTTON_TITLE: set this to overwrite the hover title of the button. This will prevent the title from being translated.

<br>

Healthcheck Copy Chapter

The Docker Image hosted on ghcr.io and the self-built Docker Image include a healthcheck.

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".

Using nginx Copy Section

#### Allow http and https requests

server {
    listen       80;
    expires epoch;
    location / {
        proxy_connect_timeout 300;
        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;
    }
}
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://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 {
    listen       80;
    expires epoch;
    location / {
        return 301 https://$host:3000$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://127.0.0.1:3000;
        proxy_set_header Connection "upgrade";
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header X-Forwarded-for $remote_addr;
    }
}


<br>

Using Apache Copy Section

install modules proxy, proxy_http, mod_proxy_wstunnel

a2enmod proxy

a2enmod proxy_http

<br>

Create a new configuration file under /etc/apache2/sites-available (on Debian)

pairdrop.conf

#### Allow HTTP and HTTPS requests

<VirtualHost *:80>
	ProxyPass / http://127.0.0.1:3000/ upgrade=websocket
</VirtualHost>
<VirtualHost *:443>
	ProxyPass / https://127.0.0.1:3000/ upgrade=websocket
</VirtualHost>

#### Automatic HTTP to HTTPS redirect:

<VirtualHost *:80>
	Redirect permanent / https://127.0.0.1:3000/
</VirtualHost>
<VirtualHost *:443>
	ProxyPass / http://127.0.0.1:3000/ upgrade=websocket
</VirtualHost>

Activate the new virtual host and reload Apache:

a2ensite pairdrop

service apache2 reload

<br>

Coturn and PairDrop via Docker Compose Copy Chapter

Setup container Copy Section

1. Generate or retrieve certificates for your <DOMAIN> (e.g. letsencrypt / certbot)
2. Create ./ssl folder: mkdir ssl
3. Copy your ssl-certificates and the privkey to ./ssl
4. Restrict access to ./ssl: chown -R nobody:nogroup ./ssl
5. Create a dh-params file: openssl dhparam -out ./ssl/dhparams.pem 4096
6. Copy rtc_config_example.json to rtc_config.json
7. Copy turnserver_example.conf to turnserver.conf
8. Change <DOMAIN> in both files to the domain where your PairDrop instance is running
9. Change username and password in turnserver.conf and rtc-config.json
10. To start the container including coturn run: \
docker compose -f docker-compose-coturn.yml up -d

<br>

#### Setup container
To restart the container including coturn run: \
docker compose -f docker-compose-coturn.yml restart

<br>

#### Setup container
To stop the container including coturn run: \
docker compose -f docker-compose-coturn.yml stop

<br>

Firewall Copy Section

All files needed for developing are available in the folder ./dev.

For convenience, there is also a docker compose file for developing:

#### Developing with docker compose
First, Install docker with docker compose.

Then, clone the repository and run docker compose:

git clone https://github.com/schlagmichdoch/PairDrop.git && cd PairDrop

docker compose -f docker-compose-dev.yml up --no-deps --build

Now point your web browser to http://localhost:8080.

- To debug the Node.js server, run docker logs pairdrop.
- After changes to the code you have to rerun the docker compose command

<br>

#### Testing PWA related features

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-compose-dev.yml
to the fully qualified domain name of your workstation. (Default: localhost)

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. \

##### Windows
- Make sure to install it to the Trusted Root Certification Authorities store.

##### macOS
- Double-click the installed CA certificate in Keychain Access,
- expand Trust, and select Always Trust for SSL.

##### Firefox
Firefox uses its own trust store. To install the CA:
- point Firefox at http://<Your FQDN>:8080/ca.crt (Default: http://localhost:8080/ca.crt)
- When prompted, select Trust this CA to identify websites and click _OK_.

Alternatively:
1. Download ca.crt from http://<Your FQDN>:8080/ca.crt (Default: http://localhost:8080/ca.crt)
2. Go to about:preferences#privacy scroll down to Security and Certificates and click View Certificates
3. Import the downloaded certificate file (step 1)

##### Chrome
- 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).

##### Google Chrome
- To skip the installation of the certificate, you can also open chrome://flags/#unsafely-treat-insecure-origin-as-secure
- The feature Insecure origins treated as secure must be enabled and the list must include your PairDrop test instance. E.g.: http://127.0.0.1:3000,https://127.0.0.1:8443

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://<Your FQDN>:8443 (Default: https://localhost:8443).

< Back

---

How To Copy Section

How-To

Send directly from share menu on iOS Copy Chapter

pairdrop -h

Send files or text with PairDrop via command-line interface.
Current domain: https://pairdrop-dev.onrender.com/
Usage:
Open PairDrop:		pairdrop
Send files:		pairdrop file1/directory1 (file2/directory2 file3/directory3 ...)
Send text:		pairdrop -t "text"
Specify domain:		pairdrop -d "https://pairdrop.net/"
Show this help text:	pairdrop (-h|--help)
This pairdrop-cli version was released alongside v1.10.4

wget "https://github.com/schlagmichdoch/PairDrop/releases/download/v1.11.2/pairdrop-cli.zip"

curl -LO "https://github.com/schlagmichdoch/PairDrop/releases/download/v1.11.2/pairdrop-cli.zip"

sudo unzip pairdrop-cli.zip -d /usr/share/pairdrop-cli/

sudo cp /usr/share/pairdrop-cli/.pairdrop-cli-config.example /usr/share/pairdrop-cli/.pairdrop-cli-config

sudo chmod +x /usr/share/pairdrop-cli/pairdrop

sudo ln -s /usr/share/pairdrop-cli/pairdrop /usr/local/bin/pairdrop

#### Windows
1. Download the latest _pairdrop-cli.zip_ from the releases page
2. Put file in a preferred folder e.g. C:\Program Files\pairdrop-cli
3. Inside this folder, copy the file _.pairdrop-cli-config.example_ to _.pairdrop-cli-config_
4. Search for and open Edit environment variables for your account
5. Click Environment Variables…
6. Under _System Variables_ select Path and click _Edit..._
7. Click _New_, insert the preferred folder (C:\Program Files\pairdrop-cli), click OK until all windows are closed
8. Reopen Command prompt window

Requirements

As Windows cannot execute bash scripts natively, you need to install Git Bash.

Then, you can also use pairdrop-cli from the default Windows Command Prompt
by using the shell file instead of the bash file which then itself executes
_pairdrop-cli_ (the bash file) via the Git Bash.


pairdrop.sh -h

<br>

Send multiple files and directories directly from context menu on Windows Copy Chapter

Registering to open files with PairDrop Copy Section

cp /usr/share/pairdrop-cli/send-with-pairdrop ~/.local/share/nautilus/scripts/

chmod +x ~/.local/share/nautilus/scripts/send-with-pairdrop

_context menu_ > _Scripts_ > _send-with-pairdrop_

<br>

File Handling API Copy Chapter

< Back

---

Technical Documentation Copy Section

Technical Documentation

Encryption, WebRTC, STUN and TURN Copy Chapter

Encryption is mandatory for WebRTC connections and completely done by the browser itself.

When the peers are first connecting, \
a channel is created by exchanging their signaling info. \
This signaling information includes some sort of public key \
and is specific to the clients IP address. \
That is what the STUN Server is used for: \
it simply returns your public IP address \
as you only know your local ip address \
if behind a NAT (router).

The transfer of the signaling info is done by the \
PairDrop / Snapdrop server using secure websockets. \
After that the channel itself is completely peer-to-peer \
and all info can only be decrypted by the receiver. \
When the two peers are on the same network \
or when they are not behind any NAT system \
(which they are always for classic \
Snapdrop and for not paired users on PairDrop) \
the files are send directly peer-to-peer.

When a user is behind a NAT (behind a router) \
the contents are channeled through a TURN server. \
But again, the contents send via the channel \
can only be decrypted by the receiver. \
So a rogue TURN server could only \
see that there is a connection, but not what is sent. \
Obviously, connections which are channeled through a TURN server \
are not as fast as peer-to-peer.

The selection whether a TURN server is needed \
or not is also done automatically by the web browser. \
It simply iterated through the configured \
RTC iceServers and checks what works. \
Only if the STUN server is not sufficient, \
the TURN server is used.

_Diagram created by wowza.com_

Good thing: if your device has an IPv6 address \
it is uniquely reachable by that address. \
As I understand it, when both devices are using \
IPv6 addresses there is no need for a TURN server in any scenario.

Learn more by reading https://www.wowza.com/blog/webrtc-encryption-and-security \
which gives a good insight into STUN, TURN and WebRTC.

Device Pairing Copy Chapter

The pairing functionality uses the IndexedDB API.

It works by creating long secrets that are served \
by the server to the initiating and requesting pair peer, \
when the inserted key is correct. \
These long secrets are then saved to an \
indexedDB database in the web browser. \
IndexedDB is somewhat the successor of localStorage \
as saved data is shared between all tabs. \
It goes one step further by making the data persistent \
and available offline if implemented to a PWA.

All secrets a client has saved to its database \
are sent to the PairDrop server. \
Peers with a common secret are discoverable \
to each other analog to peers with the same \
IP address are discoverable by each other.

What I really like about this approach (and the reason 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.

< Back

---

CONTRIBUTING Copy Section

Priorities

Agenda

If you want to learn more about simplicity you can read Insanely Simple: The Obsession that Drives Apple's Success or Thinking, Fast and Slow.

Contributing guidelines

- Before opening an issue of a pull request, please check if the issue or the pull request already exists.
- Pull requests for packages updates are not allowed since there is Dependabot that checks them automatically.
- If you don't know how to contribute, also if you don't know JavaScript or Node.js, you can still share your awesome ideas with a new issue (feature request) and check the whole project for misspellings, too.

---

README Copy Section

<div align="center">
<a href="https://github.com/schlagmichdoch/PairDrop">
<img src="public/images/android-chrome-512x512.png" alt="Logo" width="150" height="150">
</a>

# _Send it_, with PairDrop

<p>
Local file sharing <a href="https://pairdrop.net"><strong>in your web browser</strong></a>.
<br>
Inspired by Apple's AirDrop.
<br>
Fork of Snapdrop.
<br>
<br>
<a href="https://github.com/schlagmichdoch/PairDrop/issues">Report a bug</a>
<br />
<a href="https://github.com/schlagmichdoch/PairDrop/issues">Request feature</a>
</p>
</div>
<br>

Features Copy Chapter

- A multi-platform AirDrop-like solution that works.
- Send images, documents or text via peer-to-peer connection to devices on the same local network.
- Internet transfers
- Join temporary public rooms to transfer files easily over the Internet.
- Web-app
- Works on all devices with a modern web-browser.

Send a file from your phone to your laptop?
<br>Share photos in original quality with friends using Android and iOS?
<br>Share private files peer-to-peer between Linux systems?

<img src="docs/pairdrop_screenshot_mobile.gif" alt="Screenshot GIF showing PairDrop in use" style="width: 300px">

Differences to the Snapdrop it is based on Snapdrop it is based on')" title="Copy chapter prompt for LLMs"> Copy Chapter

Paired Devices and Public Rooms — Internet Transfer Copy Section

#### Persistent Device Pairing

Always connect to known devices

* Pair devices via a 6-digit code or a QR-Code.
* Paired devices always find each other via shared secrets independently of their local network.
* Pairing is persistent. You find your devices even after reopening PairDrop.
* You can edit and unpair devices easily.

#### Temporary Public Rooms

Connect to others in complex network situations, or over the Internet.

* Enter a public room via a 5-letter code or a QR-code.
* Enter a public room to temporarily connect to devices outside your local network.
* All devices in the same public room see each other.
* Public rooms are temporary. Closing PairDrop leaves all rooms.

Improved UI for Sending/Receiving Files Improved UI for Sending/Receiving Files')" title="Copy section prompt for LLMs"> Copy Section

Send Files or Text Directly From Share Menu, Context Menu or CLI Copy Section

Other Changes Copy Section

</details>

Translate PairDrop on Hosted Weblate Hosted Weblate')" title="Copy chapter prompt for LLMs"> Copy Chapter

Built with the following awesome technologies: Copy Chapter

FAQ

Host your own instance with Docker or Node.js.

Support Copy Chapter

PairDrop is libre, and always will be. \
If you find it useful and want to support free and open-source software, please consider donating using the button above. \
I footed the bill for the domain and the server, and you can help create and maintain great software by supporting me. \
Thank you very much for your contribution!

Contributing Copy Chapter

---