feat: add upgrade guide for 6.0

Author: Chickensoupwithrice

docs/admin/deploy/docker-compose/upgrade-6.0.mdx

@@ -0,0 +1,90 @@
+import { CURRENT_VERSION_STRING } from 'src/components/PreCodeBlock'
+
+# Upgrade Sourcegraph on Docker Compose to v6.0 and beyond
+
+This document describes the process to update a Docker Compose Sourcegraph instance, specifically if you are targetting versions 6.0 and above, particularly if you are running in cluster databases from before v5.10. This document provides details on the steps required to also upgrade the Postgres containers to version 16.
+If you are unfamiliar with sourcegraph versioning or releases see our [general concepts documentation](/admin/updates/).
+
+> ***⚠️ Attention: Always consult the [release notes](/admin/updates/docker_compose) for the versions your upgrade will pass over and end on.***
+
+### Multi-version upgrades to the 6.0 release and beyond
+
+---
+
+> **⚠️ Attention:** please see our [cautionary note](/admin/updates/#best-practices) on upgrades, if you have any concerns about running a multiversion upgrade, please reach out to us at [[email protected]](mailto:[email protected]) for advisement.
+
+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](/admin/updates/docker_compose#docker-compose-upgrade-notes) for the version range you're passing through.
+   - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
+
+2. **Shutdown your instance of Sourcegraph**:
+   - In order to upgrade the databess, we must first shut down your instance of Sourcegraph. In particular, you should be in the directory containing your `docker-compose.yaml` file.
+   ```sh
+   $ pwd
+   /cloned/repo/location/deploy-sourcegraph-docker/docker-compose
+   $ docker-compose down
+   ```
+
+3. **Switch to the new release version**:
+   - Run the following command in local clone of your repository.
+  ```sh
+  $ git checkout v6.0.0
+  ```
+
+4. **Start up _only_ the database containers**:
+    - The database containers contain a self-executing, upgrade in place script that needs to be perfomed before starting up the remaining containers.
+    - Note that the names of the underlying images have changed in version 5.10, if you're manually changing the image references, be sure to checkout the correct version of the underlying image. This can be done by checking the official deployment repo [deploy-sourcegraph-docker](https://github.com/sourcegraph/deploy-sourcegraph-docker/)
+    ```sh
+    $ docker-compose up -d pgsql codeintel-db codeinsights-db
+    ```
+
+5. **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](/admin/updates/migrator/migrator-operations#docker-compose).
+    > *Note: Always use the latest image version of migrator for migrator commands, except the startup command `up`*
+    1. Set the migrator `image:` in your `docker-compose.yaml` to the **latest** release of `migrator`. **Example:**
+    - You may be able to skip this step if you're using the latest version of the migrator image, by upgrading to the latest version of Sourcegraph.
+    ```yaml
+    migrator:
+      container_name: migrator
+      image: 'index.docker.io/sourcegraph/migrator:6.0.0'
+    ```
+    2. Set the migrator `command:` to `upgrade` you'll need to supply a `--to=` argument. **Example:**
+    ```yaml
+    command: ['upgrade', '--from=v5.8.0', '--to=v6.0.0']
+    ```
+    > *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:**
+    ```sh
+    $ ~/deploy-sourcegraph-docker/docker-compose/ docker-compose up migrator
+    codeintel-db is up-to-date
+    codeinsights-db is up-to-date
+    pgsql is up-to-date
+    Recreating migrator ... done
+    Attaching to migrator
+    migrator                         | ❗️ An error was returned when detecting the terminal size and capabilities:
+    migrator                         |
+    migrator                         |    GetWinsize: inappropriate ioctl for device
+    migrator                         |
+    migrator                         |    Execution will continue, but please report this, along with your operating
+    migrator                         |    system, terminal, and any other details, to:
+    migrator                         |      https://github.com/sourcegraph/sourcegraph/issues/new
+    migrator                         |
+    migrator                         | ✱ Sourcegraph migrator 6.0.0
+    migrator                         | 👉 Migrating to v6.0 (step 1 of 2)
+    migrator                         | 👉 Running schema migrations
+    migrator                         | ✅ Schema migrations complete
+    migrator                         | 👉 Running out of band migrations [23 24]
+    ✅ Out of band migrations complete
+    migrator                         | 👉 Migrating to v6.0 (step 2 of 2)
+    migrator                         | 👉 Running schema migrations
+    migrator                         | ✅ Schema migrations complete
+    migrator                         | migrator exited with code 0
+    ```
+
+6. **Start your containers again**:
+   - run `docker-compose up -d` in the folder containing your `docker-compose.yaml` file.
+   ```sh
+   $ docker-compose up -d
+   ```