initial commit

2026-09-01 18:33:56 +00:00
commit c24449ee0a
2761 changed files with 302737 additions and 0 deletions
@@ -0,0 +1,90 @@
+# Configuration
+
+First of all, I'll give an overview about the configuration options. See the 
+[config.js](https://github.com/psi-4ward/psitransfer/blob/master/config.js#L5) for 
+possible values. I do **not** recommend changing this file directly, better use one
+of the following options.
+
+## Config file: NODE_ENV related
+
+PsiTransfer searches for an config file with the name `config.<NODE_ENV>.js` in the
+root folder where `<NODE_ENV>` stands for the value of the environment parameter `NODE_ENV`.
+If you start PsiTransfer using `npm start` it's `production` so you can create a
+`config.production.js` with your settings. For example take a look at 
+[config.dev.js](https://github.com/psi-4ward/psitransfer/blob/master/config.dev.js).
+This file is used when starting the application with `npm run dev`.
+
+You are completely free to introduce own configs like `config.custom.js` and start
+the app with `NODE_ENV=custom node app.js`.
+
+## Environment variables
+
+Some Linux distributions have `/etc/default/<daemon>` or `/etc/sysconfig/<daemon>`
+files with environment configurations. Moreover, it's common to 
+configure the behaviour of Docker containers using environment parameters.
+
+PsiTransfer supports overwriting every config value by environment parameters prefixed
+with `PSITRANSFER_`.
+
+```bash
+export NODE_ENV=dev
+export PSITRANSFER_RETENTIONS='{"one-time":"one time","3600":"1 Hour"}'
+export PSITRANSFER_PORT=8080
+node app.js
+```
+
+* The above example sets the `NODE_ENV` to `dev`.  
+  If `config.dev.js` exists, it is loaded and overwrites the corresponding values from `config.js`.
+* Then it will overwrite `retentions` and `port` with the values of the environment parameters.
+
+> Environment parameters always have the highest priority.
+
+## SSL
+
+It's recommended to use Nginx for SSL termination, see [nginx-ssl-example.conf](https://github.com/psi-4ward/psitransfer/blob/master/docs/nginx-ssl-example.conf).
+
+For native SSL support provide `sslPort`, `sslKeyFile`, `sslCertFile` options. To generate
+a _snake oil_ certificate use `openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout cert.key -out cert.pem`.
+
+To disable HTTP set the `port` config value to `false`.
+
+## WebHooks
+
+For the sake of integrating PsiTransfer with other systems, PsiTransfer can notify a webhook with a POST request on the following events:
+
+### fileUploaded
+
+On completion of a file upload, if `fileUploadedWebhook` is set in `config.<NODE_ENV>.js`, PsiTransfer will make a POST request to that url.
+
+At the time of writing, the POST body will contain a data structure resembling this (serialized as json):
+```json
+{
+  "metadata": {
+    "sid": "6055ab792b6c",
+    "retention": 3600,
+    "password": "file password is in plaintext here",
+    "name": "test.png",
+    "comment": "User individual file comment goes here",
+    "type": "image/png",
+    "key": "135a3814-df46-4e23-b061-03bdda13425c",
+    "createdAt": 1589276618052
+  },
+  "date": 1589276619385
+}
+```
+
+* Note: this event will fire many times if a user uploads multiple files in a single session (`sid`), as each individual file is uploaded separately. You'll notice that the `sid` will remain the same, but the `key` will change for each file. 
+  * For file sync purposes (e.g. syncing client uploads to another service or long-term storage), you can reassemble a file fetch url with `https://<PSITRANSFER_HOST>/${sid}++${key}`
+
+### fileDownloaded
+
+When a user attempts to download a file, if `fileDownloadedWebhook` is set in `config.<NODE_ENV>.js`, PsiTransfer will make a POST request to that url.
+
+At the time of writing, the POST body will contain a data structure resembling this (serialized as json):
+```json
+{
+   "sid": "6055ab792b6c",
+   "name": "test.png",
+   "date": 1589276619415
+}
+```
@@ -0,0 +1,29 @@
+# Deployment using Docker
+
+Using Docker is the most easy and recommended way to run PsiTransfer. There is an 
+[official Container](https://hub.docker.com/r/psitrax/psitransfer/) which is 
+updated whenever a GitHub push occurs.
+
+```bash
+docker run -d -v $PWD/data:/data -p 3000:3000 psitrax/psitransfer
+```
+The above command starts the PsiTransfer Docker container and 
+ * `-d` puts the process into background (daemon mode)
+ * `-v` mounts the data volume into the container
+ * `-p` forwards the traffic from port 3000 into the container
+
+**Protipp**: There are several [container tags](https://hub.docker.com/r/psitrax/psitransfer/tags/)
+if you want to use a specific version. E.g. `1` is always the latest stable `1.x.x` and `1.1`
+correlates with `1.1.x`.
+
+If you want to customize some PsiTransfer configurations use environment parameters
+by adding `-e` flags to the `docker run` command.
+
+```bash
+docker run -v $PWD/data:/data -p 3000:8080 \
+  -e PSITRANSFER_PORT=8080 \
+  -e PSITRANSFER_DEFAULT_RETENTION=3600 \
+  psitrax/psitransfer
+```
+
+**Protipp**: By adding `--restart always` Docker will autostart the container after reboots.  
@@ -0,0 +1,43 @@
+# Deployment as Systemd service 
+
+You can also install PsiTransfer as (Linux) system service. Most distributions
+use Systemd as main init system. You should **not** run PsiTransfer with root privileges!
+
+**Preparation**
+
+```bash
+# Create a target folder for PsiTransfer
+mkdir -p /opt/psitransfer
+cd /opt/psitransfer
+
+# Download and extract a prebuild
+curl -sL https://github.com/psi-4ward/psitransfer/releases/download/1.1.0-beta/psitransfer-1.1.0-beta.tar.gz | tar xz --strip 1
+
+# Install dependencies
+npm install --production
+
+# Add a user psitransfer
+sudo useradd --system psitransfer
+ 
+# Make psitransfer owner of /opt/psitransfer
+sudo chown -R psitransfer:psitransfer /opt/psitransfer 
+```
+
+**Systemd unit file**
+
+Grab the [psitransfer.service](https://github.com/psi-4ward/psitransfer/blob/master/docs/psitransfer.service)
+sample file, put it in `/etc/systemd/system/` and adjust to your needs.
+
+```bash
+cd /etc/systemd/system
+sudo wget https://raw.githubusercontent.com/psi-4ward/psitransfer/master/docs/psitransfer.service
+
+# Start the service
+sudo systemctl start psitransfer
+
+# Show the status
+sudo systemctl status psitransfer
+
+# Enable autostart on boot
+sudo systemctl enable psitransfer
+```
@@ -0,0 +1,14 @@
+# Layout customization
+
+It is easy to customize the look of PsiTransfer. Almost all functional components are encapsulated
+in the upload- and download-app and they only need a root element where they can be mounted.
+This elements must have the attribute `id="upload"` and `id="download"`, respectively.
+
+PsiTransfer uses [Bootstrap 3](http://getbootstrap.com/) as CSS-Framework and custom styles can
+be found in [public/assets/styles.css](https://github.com/psi-4ward/psitransfer/blob/master/public/assets/styles.css).
+
+If you want to give PsiTransfer your own custom look and feel just edit the files in `public/html` and/or
+the `styles.css`. If you need to deliver assets like a custom logo put it into the `assets` folder.
+
+But consider: You have to adopt further changes on PsiTransfer updates. This sould not happen very often.
+
@@ -0,0 +1,50 @@
+# don't send the nginx version number in error pages and Server header
+server_tokens off;
+
+# redirect all http traffic to https
+server {
+  listen 80;
+  server_name transfer.example.com;
+  return 301 https://$host$request_uri;
+}
+
+server {
+  listen 443 ssl;
+  server_name transfer.example.com;
+
+  error_log  /var/log/nginx/transfer-error.log warn;
+  access_log  /var/log/nginx/transfer-access.log main;
+  
+  ### SSL ###
+  ssl_certificate /etc/nginx/certs/transfer.example.com/fullchain.pem;
+  ssl_certificate_key /etc/nginx/certs/transfer.example.com/key.pem;
+
+  # enable session resumption to improve https performance
+  # http://vincent.bernat.im/en/blog/2011-ssl-session-reuse-rfc5077.html
+  ssl_session_cache shared:SSL:50m;
+  ssl_session_timeout 5m;
+
+  # openssl dhparam -out /etc/nginx/ssl/dhparam.pem 2048
+  ssl_dhparam /etc/nginx/ssl/dhparams.pem;
+
+  # enables server-side protection from BEAST attacks
+  # http://blog.ivanristic.com/2013/09/is-beast-still-a-threat.html
+  ssl_prefer_server_ciphers on;
+  # disable SSLv3(enabled by default since nginx 0.8.19) since it's less secure then TLS http://en.wikipedia.org/wiki/Secure_Sockets_Layer#SSL_3.0
+  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
+  # ciphers chosen for forward secrecy and compatibility
+  # http://blog.ivanristic.com/2013/08/configuring-apache-nginx-and-openssl-for-forward-secrecy.html
+  ssl_ciphers "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
+
+
+  location / {
+    # Bind PsiTransfer to localhost interface
+    # ie with PSITRANSFER_IFACE=127.0.0.1
+    proxy_pass "http://127.0.0.1:3000";
+
+    proxy_http_version 1.1;
+    proxy_buffering off;
+    proxy_request_buffering off;      # needs nginx version >= 1.7.11
+    proxy_set_header Host $http_host;
+  }
+}
@@ -0,0 +1,18 @@
+[Unit]
+Description=PsiTransfer
+Documentation=https://github.com/psi-4ward/psitransfer
+After=network.target
+
+[Service]
+Type=simple
+User=psitransfer
+Restart=on-failure
+
+Environment=NODE_ENV=production
+Environment=PSITRANSFER_PORT=8080
+
+WorkingDirectory=/opt/psitransfer
+ExecStart=/usr/bin/node app.js
+
+[Install]
+WantedBy=multi-user.target