upgrades: Update docs (#53783)

Author: efritz

doc/admin/deploy/docker-compose/upgrade.md

@@ -10,7 +10,7 @@ A [standard upgrade](../../updates/index.md#upgrade-types) occurs between a Sour
 
 If you've [configured Docker Compose with a release branch](index.md#step-1-prepare-the-deployment-repository), please merge the upstream release tag for the next minor version into your `release` branch. In the following example, the release branch is being upgraded to v3.43.2.
 
-```bash
+```sh
 # first, checkout the release branch
 git checkout release
 # fetch updates
@@ -34,7 +34,7 @@ For each conflict, you need to reconcile any customizations you made with the up
 
 SSH into your instance and navigate to the appropriate folder:  
 
-```bash
+```sh
 # AWS
 cd /home/ec2-user/deploy-sourcegraph-docker/docker-compose
 # Azure, Digital Ocean, Google Cloud
@@ -43,38 +43,42 @@ cd /root/deploy-sourcegraph-docker/docker-compose
 
 Download all the latest docker images to your local docker daemon:
 
-```bash
-docker-compose pull --include-deps
+```sh
+$ docker-compose pull --include-deps
 ```
 
 Restart Docker Compose using the new minor version along with your customizations:
 
-```bash
-docker-compose up -d --remove-orphans
+```sh
+$ docker-compose up -d --remove-orphans
 ```
 
 ### Multi-version upgrades
 
+If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perform an [**automatic multi-version upgrade**](../../updates/automatic.md). The following instructions are still applicable, just the manual version of what automatic multi-version upgrade do for you now (and therefore is valuable information during a bumpy upgrade).
+
+---
+
 > **⚠️ Attention:** please see our [cautionary note](../../updates/index.md#best-practices) on upgrades, if you have any concerns about running a multiversion upgrade, please reach out to us at [[email protected]](emailto:[email protected]) for advisement.
 
-To perform a multi-version upgrade on a Sourcegraph instance running on Docker compose follow the procedure below:
+To perform a **manual** multi-version upgrade on a Sourcegraph instance running on Docker compose follow the procedure below:
 
 1. **Check Upgrade Readiness**:
    - Check the [upgrade notes](../../updates/docker_compose.md#docker-compose-upgrade-notes) for the version range you're passing through.
    - Check the `Site Admin > Updates` page to determine [upgrade readiness](../../updates/index.md#upgrade-readiness).
 
 2. **Disable Connections to the Database**:
    - Run the following command in the directory containing your `docker-compose.yaml` file.
-  ```
-  docker-compose stop && docker-compose up -d pgsql codeintel-db codeinsights-db
+  ```sh
+  $ docker-compose stop && docker-compose up -d pgsql codeintel-db codeinsights-db
   ```
 3. **Run Migrator with the `upgrade` command**:
    - The following procedure describes running migrator in brief, for more detailed instructions and available command flags see our [migrator docs](../../updates/migrator/migrator-operations.md#docker-compose).
     1. Set the migrator `image:` in your `docker-compose.yaml` to the **latest** release of `migrator`. **Example:**
     ```yaml
-      migrator:
-    container_name: migrator
-    image: 'index.docker.io/sourcegraph/migrator:5.0.4'
+    migrator:
+      container_name: migrator
+      image: 'index.docker.io/sourcegraph/migrator:5.0.4'
     ```
     > *Note: Always use the latest image version of migrator for migrator commands, except the startup command `up`*
     2. Set the migrator `command:` to `upgrade` you'll need to supply a `--to=` argument. **Example:**
@@ -83,7 +87,7 @@ To perform a multi-version upgrade on a Sourcegraph instance running on Docker c
     ```
     > *Note: you may add the `--dry-run` flag to the `command:` to test things out before altering the dbs*
     3. Run migrator with `docker-compose up migrator` **Example:**
-    ```bash
+    ```sh
     $ ~/deploy-sourcegraph-docker/docker-compose/ docker-compose up migrator
     codeintel-db is up-to-date
     codeinsights-db is up-to-date
@@ -116,7 +120,6 @@ To perform a multi-version upgrade on a Sourcegraph instance running on Docker c
 
 5. **Start your containers again**:
    - run `docker-compose up -d` in the folder containing your `docker-compose.yaml` file.
+   ```sh
+   $ docker-compose up -d
    ```
-   docker-compose up -d
-   ```
-   

doc/admin/deploy/docker-single-container/index.md

@@ -86,24 +86,24 @@ This is required to [collect debug data](../../pprof.md).
 
 The docker run command for single-container Sourcegraph needs an additional publish flag to expose the debug port:
 
-```bash script
-docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 --publish 127.0.0.1:6060:6060 --rm --volume ~/.sourcegraph/config:/etc/sourcegraph --volume ~/.sourcegraph/data:/var/opt/sourcegraph sourcegraph/server:5.0.6
+```sh
+$ docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 --publish 127.0.0.1:6060:6060 --rm --volume ~/.sourcegraph/config:/etc/sourcegraph --volume ~/.sourcegraph/data:/var/opt/sourcegraph sourcegraph/server:5.0.6
 ```
 
 If Sourcegraph is deployed to a remote server, then access via an SSH tunnel using a tool
 such as [sshuttle](https://github.com/sshuttle/sshuttle) is required to establish a secure connection.
 To access the remote server using `sshuttle` from your local machine:
 
-```bash script
-sshuttle -r user@host 0/0
+```sh
+$ sshuttle -r user@host 0/0
 ```
 
 ### Environment variables
 
 Add the following to your docker run command:
 
-```
-docker run [...]
+```sh
+$ docker run [...]
 -e (YOUR CODE)
 sourcegraph/server:5.0.6
 ```
@@ -116,16 +116,16 @@ sourcegraph/server:5.0.6
 
 Get the Docker container ID for Sourcegraph:
 
-```bash
-docker ps
+```sh
+$ docker ps
 CONTAINER ID        IMAGE
 d039ec989761        sourcegraph/server:VERSION
 ```
 
 Open a PostgreSQL interactive terminal:
 
-```bash
-docker container exec -it d039ec989761 psql -U postgres sourcegraph
+```sh
+$ docker container exec -it d039ec989761 psql -U postgres sourcegraph
 ```
 
 Run your SQL query:
@@ -170,8 +170,8 @@ To perform a multi-version upgrade on a Sourcegraph instance running on Docker S
 
 <p />
 
-```bash
-docker run \
+```sh
+$ docker run \
   --rm \
   --name migrator_${SG_VERSION} \
   -e PGHOST='pgsql' \
@@ -209,8 +209,8 @@ Let `${PATH}` be the directory mounted into `/var/opt/sourcegraph` of your insta
 
 For example, `${PATH}` is `~/.sourcegraph/data` in `-v ~/.sourcegraph/data:/var/opt/sourcegraph`.
 
-```bash
-docker run --rm -it \
+```sh
+$ docker run --rm -it \
   -v ${PATH}/postgresql:/data/pgdata-${PG_VERSION} \
   -u 70 \
   -p 5432:5432 \
@@ -243,7 +243,7 @@ To achieve better performance, you can do any of the following:
 
 - For better clone performance, clone the repository on your host machine and then [add it to Sourcegraph Server](../../repo/add.md#add-repositories-already-cloned-to-disk).
 - Try adding the `:delegated` suffix the data volume mount. [Learn more](https://github.com/docker/for-mac/issues/1592).
-  ```
+  ```sh
   --volume ~/.sourcegraph/data:/var/opt/sourcegraph:delegated
   ```
 
@@ -297,8 +297,8 @@ To test new development builds of Sourcegraph (triggered by commits to `main`),
 
 > WARNING: `insiders` builds may be unstable, so back up Sourcegraph's data and config (usually `~/.sourcegraph`) beforehand.
 
-```bash
-docker run --publish 7080:7080 --rm --volume ~/.sourcegraph/config:/etc/sourcegraph --volume ~/.sourcegraph/data:/var/opt/sourcegraph sourcegraph/server:insiders
+```sh
+$ docker run --publish 7080:7080 --rm --volume ~/.sourcegraph/config:/etc/sourcegraph --volume ~/.sourcegraph/data:/var/opt/sourcegraph sourcegraph/server:insiders
 ```
 
 To keep this up to date, run `docker pull sourcegraph/server:insiders` to pull in the latest image, and restart the container to access new changes.