GDK-in-a-box as recommended

Tucks the one-line installation into a details component.

doc/.vale/gitlab/spelling-exceptions.txt

@@ -1174,6 +1174,7 @@ virtualizing
 Vite
 VMs
 VPCs
+VSCodium
 Vue
 Vuex
 waitlist

doc/development/contributing/first_contribution/configure-dev-env-gdk.md

@@ -15,15 +15,100 @@ to test functionality, and it gives you access to administrator functionality.
 
 ![GDK](../img/gdk_home.png)
 
-To contribute code without the overhead of setting up a local development environment,
-you should use Gitpod.
+[GDK-in-a-box](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/gdk_in_a_box.md)
+is a virtual machine (VM) pre-configured with GDK.
+It requires 30 GB of disk space.
+
+<!--
+The steps here are a version of the steps in the GDK repo
+https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/gdk_in_a_box.md
+-->
+
+## Download GDK-in-a-box
+
+1. Download and install virtualization software to run the virtual machine:
+   - Mac computers with [Apple silicon](https://support.apple.com/en-us/116943):
+   [UTM](https://docs.getutm.app/installation/macos/). Select **Download from GitHub**.
+   - Linux / Windows / Mac computers with Intel silicon: [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
+1. Download and unzip GDK-in-a-box. The file is up to 10 GB and might take some time to download:
+   - Mac computers with Apple silicon: [UTM image](https://go.gitlab.com/cCHpCP)
+   - Linux / Windows / Mac: [VirtualBox image](https://go.gitlab.com/5iydBP)
+1. Open UTM or VirtualBox, add the virtual machine image, then start the virtual machine:
+   - UTM: `gdk.utm`
+   - VirtualBox: `gdk.vbox`
+1. Continue to **Use VS Code to connect to GDK in the VM**.
+
+## Use VS Code to connect to GDK in the VM
+
+[View a demo video of this step](https://go.gitlab.com/b54mHb).
+
+1. Start the VM. You can minimize UTM or VirtualBox.
+
+1. In VS Code, select **Terminal > New terminal** and run a `curl` command that executes a script to
+   add an SSH key to your local `~/.ssh/config`:
+
+   ```shell
+   curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/gdk-in-a-box/setup-ssh-key" | bash
+   ```
+
+   To learn more about the script, you can examine the
+   [`setup-ssh-key` code](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/support/gdk-in-a-box/setup-ssh-key).
+
+1. In VS Code, install the **Remote - SSH** extension:
+   - [VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
+   - [VSCodium](https://open-vsx.org/extension/jeanp413/open-remote-ssh)
+1. Connect VS Code to the VM:
+   - Select **Remote-SSH: Connect to host** from the command palette.
+   - Enter the SSH host: `debian@gdk.local`
+1. A new VS Code window opens.
+   You can close or minimize the old window to avoid confusion.
+
+   Complete the remaining steps in this section in the new VS Code window.
+
+1. In the VS Code terminal, run a `curl` command to run a script to configure Git in the GDK:
+
+   ```shell
+   curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/gdk-in-a-box/setup-git" | bash
+   ```
+
+   - Enter your name and email address when prompted.
+   - Add the displayed [SSH key to your profile](https://gitlab.com/-/profile/keys).
+
+   To learn more about the script, you can examine the
+   [`setup-git` code](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/support/gdk-in-a-box/setup-git).
+
+1. In VS Code, select **File > Open folder**, and go to: `/home/debian/gitlab-development-kit/gitlab/`.
+1. Open GitLab in your browser: [http://gdk.local:3000](http://gdk.local:3000).
+1. Sign in with the username `root` and the password `5iveL!fe`.
+1. Continue to [Change the code with the GDK](contribute-gdk.md).
+
+### Shut down GDK in the VM
+
+You can select the power icon <i class="fa fa-power-off" aria-hidden="true"></i> to shut down
+the virtual machine, or enter the `shutdown` command in the terminal. Use the password `debian`:
+
+```shell
+sudo shutdown now
+```
+
+### Update GDK-in-a-box
+
+You can update GDK-in-a-box while connected to `debian@gdk.local` in VS Code.
+
+In the VS Code terminal, enter `gdk update`.
+
+## Install GDK and its dependencies
+
+If you prefer to install GDK without a virtual machine, you can use the one-line GDK-installation.
+
+<details><summary>Traditional, one-line GDK installation</summary>
 
 If you already have a working GDK,
 [update it to use the community fork](#update-an-existing-gdk-installation).
 
 [View an interactive demo of this step](https://gitlab.navattic.com/xtk20s8x).
 
-## Install and configure GitLab Development Kit (GDK)
+### Install and configure GitLab Development Kit (GDK)
 
 If you already have a working GDK,
 [update it to use the community fork](#update-an-existing-gdk-installation).
@@ -134,7 +219,8 @@ To confirm it was successful:
 1. Ensure the `gitlab-development-kit/gitlab` directory exists.
 1. Go to the top `gitlab-development-kit` directory and run `gdk stop` and `gdk start`.
 
-If you get errors, run `gdk doctor` to troubleshoot. For more advanced troubleshooting, continue to the [Troubleshoot GDK](#troubleshoot-gdk) section.
+If you get errors, run `gdk doctor` to troubleshoot.
+For more advanced troubleshooting, continue to the [Troubleshoot GDK](#troubleshoot-gdk) section.
 
 ### Troubleshoot GDK
 
@@ -152,6 +238,8 @@ For more advanced troubleshooting, see
 the [troubleshooting documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/doc/troubleshooting)
 and the [#contribute channel on Discord](https://discord.com/channels/778180511088640070/997442331202564176).
 
-## Change the code
+### Change the code
 
 After the GDK is ready, continue to [Contribute code with the GDK](contribute-gdk.md).
+
+</details>

doc/development/vs_code_debugging.md

@@ -6,7 +6,7 @@ info: Any user with at least the Maintainer role can merge updates to this conte
 
 # VS Code debugging
 
-This document describes how to set up Rails debugging in [Visual Studio Code (VS Code)](https://code.visualstudio.com/) using the [GitLab Development Kit (GDK)](contributing/first_contribution/configure-dev-env-gdk.md#install-and-configure-gitlab-development-kit-gdk).
+This document describes how to set up Rails debugging in [Visual Studio Code (VS Code)](https://code.visualstudio.com/) using the [GitLab Development Kit (GDK)](contributing/first_contribution/configure-dev-env-gdk.md).
 
 ## Setup
 
@@ -65,7 +65,7 @@ The VS Code Ruby extension might have issues finding the correct Ruby installati
 
 ### Prerequisites
 
-- You must have a running [GDK](contributing/first_contribution/configure-dev-env-gdk.md#install-and-configure-gitlab-development-kit-gdk) instance.
+- You must have a running [GDK](contributing/first_contribution/configure-dev-env-gdk.md) instance.
 
 To start debugging, do one of the following: