configure-dev-env-gdk.md

stage: none
group: unassigned
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.

Configure the GDK development environment

If you want to contribute to the GitLab codebase and want a development environment in which to test your changes, you can use the GitLab Development Kit (GDK), a local version of GitLab that's yours to play with.

It's just like an installation of self-managed GitLab. It includes sample projects you can use to test functionality, and it gives you access to administrator functionality.

GDK-in-a-box is a virtual machine (VM) pre-configured with GDK. It requires 30 GB of disk space.

Download GDK-in-a-box

1. Download and install virtualization software to run the virtual machine:
   • Mac computers with Apple silicon: UTM. Select Download from GitHub.
   • Linux / Windows / Mac computers with Intel silicon: VirtualBox
2. 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
   • Linux / Windows / Mac: VirtualBox image
3. Open UTM or VirtualBox, add the virtual machine image, then start the virtual machine:
   • UTM: gdk.utm
   • VirtualBox: gdk.vbox
4. 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.

1. Start the VM. You can minimize UTM or VirtualBox.

2. 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:

   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.

3. In VS Code, install the Remote - SSH extension:

   • VS Code
   • VSCodium

4. Connect VS Code to the VM:

   • Select Remote-SSH: Connect to host from the command palette.
   • Enter the SSH host: debian@gdk.local

5. 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.

6. In the VS Code terminal, run a curl command to run a script to configure Git in the GDK:

   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.

   To learn more about the script, you can examine the setup-git code.

7. In VS Code, select File > Open folder, and go to: /home/debian/gitlab-development-kit/gitlab/.

8. Open GitLab in your browser: http://gdk.local:3000.

9. Sign in with the username root and the password 5iveL!fe.

10. Continue to Change the code with the GDK.

Shut down GDK in the VM

You can select the power icon to shut down the virtual machine, or enter the shutdown command in the terminal. Use the password debian:

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.

Traditional, one-line GDK installation

If you already have a working GDK, update it to use the community fork.

View an interactive demo of this step.

Install and configure GitLab Development Kit (GDK)

If you already have a working GDK, update it to use the community fork.

Set aside about two hours to install the GDK. If all goes smoothly, it should take about an hour to install.

Sometimes the installation needs some tweaks to make it work, so you should also set aside some time for troubleshooting. It might seem like a lot of work, but after you have the GDK running, you'll be able to make any changes.

View an interactive demo of this step.

To install the GDK:

1. Ensure you're on one of the supported platforms.

2. Confirm that Git is installed, and that you have a source code editor.

3. Choose the directory where you want to install the GDK. The installation script installs the application to a new subdirectory called gitlab-development-kit.

   Keep the directory name short. Some users encounter issues with long directory names.

4. From the command line, go to that directory. In this example, create and change to the dev directory:

   mkdir ~/dev && cd "$_"

5. Run the one-line installation command:

   curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/install" | bash

6. For the message Where would you like to install the GDK? [./gitlab-development-kit], press Enter to accept the default location.

7. For the message Which GitLab repo URL would you like to clone?, enter the GitLab community fork URL:

   https://gitlab.com/gitlab-community/gitlab.git

8. For the message GitLab would like to collect basic error and usage data, choose your option based on the prompt.

   While the installation is running, copy any messages that are displayed. If you have any problems with the installation, you can use this output as part of troubleshooting.

9. After the installation is complete, copy the source command from the message corresponding to your shell from the message INFO: To make sure GDK commands are available in this shell:

   source ~/.asdf/asdf.sh

10. Go to the directory where the GDK was installed:

    cd gitlab-development-kit

11. Run gdk truncate-legacy-tables to ensure that the data in the main and CI databases are truncated, then gdk doctor to confirm the GDK installation:

    gdk truncate-legacy-tables && gdk doctor

    • If gdk doctor returns errors, consult the Troubleshoot GDK section.
    • If gdk doctor returns Your GDK is healthy, proceed to the next step.

12. Start the GDK:

    gdk start

13. Wait for GitLab available at http://127.0.0.1:3000, and connect to the GDK using the URL provided.

14. Sign in with the username root and the password 5iveL!fe. You will be prompted to reset your password the first time you sign in.

15. Continue to Change the code with the GDK.

Update an existing GDK installation

If you have an existing GDK installation, you should update it to use the community fork.

1. Delete the existing gitlab-development-kit/gitlab directory.

2. Clone the community fork into that location:

   cd gitlab-development-kit
   git clone https://gitlab.com/gitlab-community/gitlab.git

To confirm it was successful:

1. Ensure the gitlab-development-kit/gitlab directory exists.
2. 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 section.

Troubleshoot GDK

If you encounter issues, go to the gitlab-development-kit/gitlab directory and run gdk doctor.

If gdk doctor returns Node or Ruby-related errors, run:

yarn install && bundle install
bundle exec rails db:migrate RAILS_ENV=development

For more advanced troubleshooting, see the troubleshooting documentation and the #contribute channel on Discord.

Change the code

After the GDK is ready, continue to Contribute code with the GDK.