From 669f9e9a993f8cebce1eff4ecb6dacce46f02b5d Mon Sep 17 00:00:00 2001
From: Mikael Finstad <finstaden@gmail.com>
Date: Tue, 16 Apr 2024 14:52:49 +0200
Subject: [PATCH] improve companion middleware/standalone docs (#166)

Co-authored-by: Antoine du Hamel <antoine@transloadit.com>
---
 docs/companion.md | 109 +++++++++++++++++++++++-----------------------
 1 file changed, 54 insertions(+), 55 deletions(-)

diff --git a/docs/companion.md b/docs/companion.md
index 78780a0e9..e33924a2e 100644
--- a/docs/companion.md
+++ b/docs/companion.md
@@ -70,11 +70,10 @@ files to arrive at Transloadit servers, much like Uppy.
 
 Companion is installed from npm. Depending on how you want to run Companion, the
 install process is slightly different. Companion can be integrated as middleware
-into your [Express](https://expressjs.com/) app or as a standalone server.
-
-```bash
-npm install @uppy/companion
-```
+into your [Express](https://expressjs.com/) app or as a standalone server. Most
+people probably want to run it as a standalone server, while the middleware
+could be used to further customise Companion or integrate it into your own HTTP
+server code.
 
 :::note
 
@@ -88,7 +87,56 @@ accept improvements in this area, but we can’t provide support.
 
 :::
 
-### Express middleware
+### Standalone mode
+
+You can use the standalone version if you want to run Companion as it’s own
+Node.js process. It’s a configured Express server with sessions, logging, and
+security best practices. First you’ll typically want to install it globally:
+
+```bash
+npm install -g @uppy/companion
+```
+
+Standalone Companion will always serve HTTP (not HTTPS) and expects a reverse
+proxy with SSL termination in front of it when running in production. See
+[`COMPANION_PROTOCOL`](#server) for more information.
+
+Companion ships with an executable file (`bin/companion`) which is the
+standalone server. Unlike the middleware version, options are set via
+environment variables.
+
+:::info
+
+Checkout [options](#options) for the available options in JS and environment
+variable formats.
+
+:::
+
+You need at least these three to get started:
+
+```bash
+export COMPANION_SECRET="shh!Issa Secret!"
+export COMPANION_DOMAIN="YOUR SERVER DOMAIN"
+export COMPANION_DATADIR="PATH/TO/DOWNLOAD/DIRECTORY"
+```
+
+Then run:
+
+```bash
+companion
+```
+
+You can also pass in the path to your JSON config file, like so:
+
+```bash
+companion --config /path/to/companion.json
+```
+
+You may also want to run Companion in a process manager like
+[PM2](https://pm2.keymetrics.io/) to make sure it gets restarted on upon
+crashing as well as allowing scaling to many instances.
+
+### Express middleware mode
 
 First install it into your Node.js project with your favorite package manager:
 
@@ -150,55 +198,6 @@ companion.socket(server);
 If WebSockets fail for some reason Uppy and Companion will fallback to HTTP
 polling.
 
-### Standalone
-
-You can use the standalone version if you want to run Companion as it’s own Node
-process. It’s a configured Express server with sessions, logging, and security
-best practices. First you’ll typically want to install it globally:
-
-```bash
-npm install -g @uppy/companion
-```
-
-Standalone Companion will always serve HTTP (not HTTPS) and expects a reverse
-proxy with SSL termination in front of it when running in production. See
-[`COMPANION_PROTOCOL`](#server) for more information.
-
-Companion ships with an executable file (`bin/companion`) which is the
-standalone server. Unlike the middleware version, options are set via
-environment variables.
-
-:::info
-
-Checkout [options](#options) for the available options in JS and environment
-variable formats.
-
-:::
-
-You need at least these three to get started:
-
-```bash
-export COMPANION_SECRET="shh!Issa Secret!"
-export COMPANION_DOMAIN="YOUR SERVER DOMAIN"
-export COMPANION_DATADIR="PATH/TO/DOWNLOAD/DIRECTORY"
-```
-
-Then run:
-
-```bash
-companion
-```
-
-You can also pass in the path to your JSON config file, like so:
-
-```bash
-companion --config /path/to/companion.json
-```
-
-You may also want to run Companion in a process manager like
-[PM2](https://pm2.keymetrics.io/) to make sure it gets restarted on upon
-crashing as well as allowing scaling to many instances.
-
 ### Running many instances
 
 We recommend running at least two instances in production, so that if the