Configure GDK-in-a-box

If you want to contribute to the GitLab codebase and want a development environment in which to test your changes, you can use GDK-in-a-box. GDK-in-a-box is available as a multi-platform container image, pre-configured with the GitLab Development Kit (GDK).

[!warning] GDK-in-a-box Virtual Machine (VM) images are no longer supported and were deprecated in favor of the container-based images.

The GDK is a local development environment that includes an installation of GitLab Self-Managed, sample projects, and administrator access with which you can test functionality.

It requires 30 GB of disk space.

If you prefer to use GDK locally without a container, use the steps in Install the GDK development environment

Download GDK-in-a-box

1. Install a container runtime.

   • Multiple options are available, including Docker Desktop, Docker Engine, and Rancher Desktop.
   • Docker Desktop can also be installed through package managers like Homebrew.
   • Note: On Rancher Desktop, you may want to disable Kubernetes under "Preferences".
   • Other container runtimes that support Docker-compatible commands should also work.

2. Pull the container image. The image requires a download of more than 8 GB and might take some time to download.

   • docker pull registry.gitlab.com/gitlab-org/gitlab-development-kit/gitlab-gdk-in-a-box:latest

3. Create a container from the image:

   shellCopy

   docker run -d -h gdk.local --name gdk \
   -p 2022:2022 \
   -p 2222:2222 \
   -p 3000:3000 \
   -p 3005:3005 \
   -p 3010:3010 \
   -p 3038:3038 \
   -p 5100:5100 \
   -p 5778:5778 \
   -p 9000:9000 \
   registry.gitlab.com/gitlab-org/gitlab-development-kit/gitlab-gdk-in-a-box:latest
   

4. Continue to Use VS Code to connect to GDK.

Use VS Code to connect to GDK

View a demo video of this step.

[!note] You might need to modify the system configuration of your container runtime (CPU cores and RAM) before starting it. A suggested configuration is at least 12 GB RAM, and 4 cores.

1. Start the container.

2. In VS Code, select Terminal > New terminal, then run a curl command to add an SSH key to your local ~/.ssh/config:

   shellCopy

   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 the script, type 1 to select the Container installation.

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

   • VS Code
   • VSCodium

5. Connect VS Code to the container:

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

6. A new VS Code window opens. You can close the old window to avoid confusion. Complete the remaining steps in the new window.

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

   shellCopy

   curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/gdk-in-a-box/first_time_setup" | 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 first_time_setup code.

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

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

   • If the page does not load, add 127.0.0.1 gdk.local to your local machine's hosts file.

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

11. Continue to change the code with the GDK.

Shut down the GDK Container

You can stop the container by running the following command on your host:

docker stop gdk

Start the GDK Container

You can start the container again by running the following command on your host:

docker start gdk

Remove the GDK Container

[!warning] This deletes the current container and any data inside. Ensure you have committed any changes before running this command.

You can remove the container by running the following command on your host:

docker rm gdk

Update GDK-in-a-box

You can update GDK-in-a-box while connected to gdk.local in VS Code.

In the VS Code terminal, enter:

gdk update

Change the code

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