diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index b2e98a7308c6a764b26a5a2d6eace48f4b063476..44de1f0fd641ccc2f9ededb31f356ad3e54dd487 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -1174,6 +1174,7 @@ virtualizing Vite VMs VPCs +VSCodium Vue Vuex waitlist diff --git a/doc/development/contributing/first_contribution/configure-dev-env-gdk.md b/doc/development/contributing/first_contribution/configure-dev-env-gdk.md index c017132f9e4b0f61fbc9ffe52f40eae0c9039abc..dbe9b3566ef841904c7c6e8ae057a458bc8fd771 100644 --- a/doc/development/contributing/first_contribution/configure-dev-env-gdk.md +++ b/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.  -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> diff --git a/doc/development/vs_code_debugging.md b/doc/development/vs_code_debugging.md index 14e0ad814d34be1393252431eca05ff830b10826..013333fbc304695e3de89263871c97a016825f45 100644 --- a/doc/development/vs_code_debugging.md +++ b/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: