rearrange a big part of the example config file

config/config.example.js

@@ -1,30 +1,100 @@
 /* globals module */
-module.exports = {
-    httpUnsafeOrigin: 'http://localhost:3000/', // XXX
 
-    // This is for deployment in production, CryptPad uses a separate origin (domain) to host the
+/*  DISCLAIMER:
-    // cross-domain iframe. It can simply host the same content as CryptPad.
+
-    // httpSafeOrigin: "https://some-other-domain.xyz",
+    There are two recommended methods of running a CryptPad instance:
+
+    1. Using a standalone nodejs server without HTTPS (suitable for local development)
+    2. Using NGINX to serve static assets and to handle HTTPS for API server's websocket traffic
+
+    We do not officially recommend or support Apache, Docker, Kubernetes, Traefik, or any other configuration.
+    Support requests for such setups should be directed to their authors.
 
+    If you're having difficulty difficulty configuring your instance
+    we suggest that you join the project's IRC/Matrix channel.
 
+    If you don't have any difficulty configuring your instance and you'd like to
+    support us for the work that went into making it pain-free we are quite happy
+    to accept donations via our opencollective page: https://opencollective.com/cryptpad
+
+*/
+module.exports = {
+/*  CryptPad is designed to serve its content over two domains.
+ *  Account passwords and cryptographic content is handled on the 'main' domain,
+ *  while the user interface is loaded on a 'sandbox' domain
+ *  which can only access information which the main domain willingly shares.
+ *
+ *  In the event of an XSS vulnerability in the UI (that's bad)
+ *  this system prevents attackers from gaining access to your account (that's good).
+ *
+ *  Most problems with new instances are related to this system blocking access
+ *  because of incorrectly configured sandboxes. If you only see a white screen
+ *  when you try to load CryptPad, this is probably the cause.
+ *
+ *  PLEASE READ THE FOLLOWING COMMENTS CAREFULLY.
+ *
+ */
+
+/*  httpUnsafeOrigin is the URL that clients will enter to load your instance.
+ *  Any other URL that somehow points to your instance is supposed to be blocked.
+ *  The default provided below assumes you are loading CryptPad from a server
+ *  which is running on the same machine, using port 3000.
+ *
+ *  In a production instance this should be available ONLY over HTTPS
+ *  using the default port for HTTPS (443) ie. https://cryptpad.fr
+ *  In such a case this should be handled by NGINX, as documented in
+ *  cryptpad/docs/example.nginx.conf (see the $main_domain variable)
+ *
+ */
+    httpUnsafeOrigin: 'http://localhost:3000/',
+
+/*  httpSafeOrigin is the URL that is used for the 'sandbox' described above.
+ *  If you're testing or developing with CryptPad on your local machine then
+ *  it is appropriate to leave this blank. The default behaviour is to serve
+ *  the main domain over port 3000 and to serve the content over port 3001.
+ *
+ *  This is not appropriate in a production environment where invasive networks
+ *  may filter traffic going over abnormal ports.
+ *  To correctly configure your production instance you must provide a URL
+ *  with a different domain (a subdomain is sufficient).
+ *  It will be used to load the UI in our 'sandbox' system.
+ *
+ *  This value corresponds to the $sandbox_domain variable
+ *  in the example nginx file.
+ *
+ *  CUSTOMIZE AND UNCOMMENT THIS FOR PRODUCTION INSTALLATIONS.
+ */
+    // httpSafeOrigin: "https://some-other-domain.xyz",
 
-    // the address you want to bind to, :: means all ipv4 and ipv6 addresses
+/*  httpAddress specifies the address on which the nodejs server
-    // this may not work on all operating systems
+ *  should be accessible. By default it will listen on 127.0.0.1
+ *  (IPv4 localhost on most systems). If you want it to listen on
+ *  all addresses, including IPv6, set this to '::'.
+ *
+ */
     //httpAddress: '::',
 
-    // the port on which your httpd will listen
+/*  httpPort specifies on which port the nodejs server should listen.
+ *  By default it will serve content over port 3000, which is suitable
+ *  for both local development and for use with the provided nginx example,
+ *  which will proxy websocket traffic to your node server.
+ *
+ */
     //httpPort: 3000,
 
-    // This is for allowing the cross-domain iframe to function when developing
+/*  httpSafePort allows you to specify an alternative port from which
-    httpSafePort: 3001,
+ *  the node process should serve sandboxed assets. The default value is
-
+ *  that of your httpPort + 1. You probably don't need to change this.
+ *
+ */
+    //httpSafePort: 3001,
 
     /* =====================
      *         Admin
      * ===================== */
 
     /*
-     *  CryptPad now contains an administration panel. Its access is restricted to specific
+     *  CryptPad contains an administration panel. Its access is restricted to specific
      *  users using the following list.
      *  To give access to the admin panel to a user account, just add their user id,
      *  which can be found on the settings page for registered users.
@@ -48,87 +118,42 @@ module.exports = {
      *
      */
     // supportMailboxPublicKey: "",
-    supportMailboxPublicKey: 'oxuMPm3xXHFALYaeFdAepVZyCpEPNTAPBO8MlpjdQw8=',
 
-    /* =====================
+    /*  We're very proud that CryptPad is available to the public as free software!
-     *      Infra setup
+     *  We do, however, still need to pay our bills as we develop the platform.
-     * ===================== */
-
-    /*  Your CryptPad server will share this value with clients
-     *  via its /api/config endpoint.
      *
-     *  If you want to host your API and asset servers on different hosts
+     *  By default CryptPad will prompt users to consider donating to
-     *  specify a URL for your API server websocket endpoint, like so:
+     *  our OpenCollective campaign. We publish the state of our finances periodically
-     *  wss://api.yourdomain.com/cryptpad_websocket
+     *  so you can decide for yourself whether our expenses are reasonable.
      *
-     *  Otherwise, leave this commented and your clients will use the default
+     *  You can disable any solicitations for donations by setting 'removeDonateButton' to true,
-     *  websocket (wss://yourdomain.com/cryptpad_websocket)
+     *  but we'd appreciate it if you didn't!
      */
-    //externalWebsocketURL: 'wss://api.yourdomain.com/cryptpad_websocket
+    //removeDonateButton: false,
 
-    /* =====================
+    /*  CryptPad will display a point of contact for your instance on its contact page
-     *     Subscriptions
+     *  (/contact.html) if you provide it below.
-     * ===================== */
-
-    /*  Limits, Donations, Subscriptions and Contact
-     *
-     *  By default, CryptPad limits every registered user to 50MB of storage. It also shows a
-     *  subscribe button which allows them to upgrade to a paid account. We handle payment,
-     *  and keep 50% of the proceeds to fund ongoing development.
-     *
-     *  You can:
-     *  A: leave things as they are
-     *  B: disable accounts but display a donate button
-     *  C: hide any reference to paid accounts or donation
-     *
-     *  If you chose A then there's nothing to do.
-     *  If you chose B, set 'allowSubscriptions' to false.
-     *  If you chose C, set 'removeDonateButton' to true
-     */
-    //allowSubscriptions: true,
-    removeDonateButton: false,
-
-    /*
-     *  By default, CryptPad also contacts our accounts server once a day to check for changes in
-     *  the people who have accounts. This check-in will also send the version of your CryptPad
-     *  instance and your email so we can reach you if we are aware of a serious problem. We will
-     *  never sell it or send you marketing mail. If you want to block this check-in and remain
-     *  completely invisible, set this and allowSubscriptions both to false.
      */
     adminEmail: 'i.did.not.read.my.config@cryptpad.fr',
 
     /*
-     *  If you are using CryptPad internally and you want to increase the per-user storage limit,
+     *  By default, CryptPad contacts one of our servers once a day.
-     *  change the following value.
+     *  This check-in will also send some very basic information about your instance including its
+     *  version and the adminEmail so we can reach you if we are aware of a serious problem.
+     *  We will never sell it or send you marketing mail.
      *
-     *  Please note: This limit is what makes people subscribe and what pays for CryptPad
+     *  If you want to block this check-in and remain set 'blockDailyCheck' to true.
-     *    development. Running a public instance that provides a "better deal" than cryptpad.fr
-     *    is effectively using the project against itself.
      */
-    //defaultStorageLimit: 50 * 1024 * 1024,
+    //blockDailyCheck: false,
 
     /*
-     *  CryptPad allows administrators to give custom limits to their friends.
+     *  By default users get 50MB of storage by registering on an instance.
-     *  add an entry for each friend, identified by their user id,
+     *  You can set this value to whatever you want.
-     *  which can be found on the settings page. Include a 'limit' (number of bytes),
-     *  a 'plan' (string), and a 'note' (string).
      *
-     *  hint: 1GB is 1024 * 1024 * 1024 bytes
+     *  hint: 50MB is 50 * 1024 * 1024
      */
-/*
+    //defaultStorageLimit: 50 * 1024 * 1024,
-    customLimits: {
+
-        "https://my.awesome.website/user/#/1/cryptpad-user1/YZgXQxKR0Rcb6r6CmxHPdAGLVludrAF2lEnkbx1vVOo=": {
-            limit: 20 * 1024 * 1024 * 1024,
-            plan: 'insider',
-            note: 'storage space donated by my.awesome.website'
-        },
-        "https://my.awesome.website/user/#/1/cryptpad-user2/GdflkgdlkjeworijfkldfsdflkjeEAsdlEnkbx1vVOo=": {
-            limit: 10 * 1024 * 1024 * 1024,
-            plan: 'insider',
-            note: 'storage space donated by my.awesome.website'
-        }
-    },
-*/
 
     /* =====================
      *        STORAGE
@@ -166,8 +191,35 @@ module.exports = {
      */
     //maxUploadSize: 20 * 1024 * 1024,
 
-    // XXX
+    /*
-    premiumUploadSize: 100 * 1024 * 1024,
+     *  CryptPad allows administrators to give custom limits to their friends.
+     *  add an entry for each friend, identified by their user id,
+     *  which can be found on the settings page. Include a 'limit' (number of bytes),
+     *  a 'plan' (string), and a 'note' (string).
+     *
+     *  hint: 1GB is 1024 * 1024 * 1024 bytes
+     */
+/*
+    customLimits: {
+        "https://my.awesome.website/user/#/1/cryptpad-user1/YZgXQxKR0Rcb6r6CmxHPdAGLVludrAF2lEnkbx1vVOo=": {
+            limit: 20 * 1024 * 1024 * 1024,
+            plan: 'insider',
+            note: 'storage space donated by my.awesome.website'
+        },
+        "https://my.awesome.website/user/#/1/cryptpad-user2/GdflkgdlkjeworijfkldfsdflkjeEAsdlEnkbx1vVOo=": {
+            limit: 10 * 1024 * 1024 * 1024,
+            plan: 'insider',
+            note: 'storage space donated by my.awesome.website'
+        }
+    },
+*/
+
+    /*  Users with premium accounts (those with a plan included in their customLimit)
+     *  can benefit from an increased upload size limit. By default they are restricted to the same
+     *  upload size as any other registered user.
+     *
+     */
+    //premiumUploadSize: 100 * 1024 * 1024,
 
     /* =====================
      *   DATABASE VOLUMES