diff options
Diffstat (limited to 'doc/user/workspace/create_image.md')
-rw-r--r-- | doc/user/workspace/create_image.md | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/doc/user/workspace/create_image.md b/doc/user/workspace/create_image.md new file mode 100644 index 00000000000..43140a622e0 --- /dev/null +++ b/doc/user/workspace/create_image.md @@ -0,0 +1,119 @@ +--- +stage: Create +group: IDE +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tutorial: Create a custom workspace image that supports arbitrary user IDs (Beta) **(PREMIUM ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. + +WARNING: +This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). + +In this tutorial, you'll learn how to create a custom workspace image that supports arbitrary user IDs. +You can then use this custom image with any [workspace](index.md) you create in GitLab. + +To create a custom workspace image that supports arbitrary user IDs, you'll: + +1. [Create a base Dockerfile](#create-a-base-dockerfile). +1. [Add support for arbitrary user IDs](#add-support-for-arbitrary-user-ids). +1. [Build the custom workspace image](#build-the-custom-workspace-image). +1. [Push the custom workspace image to the GitLab Container Registry](#push-the-custom-workspace-image-to-the-gitlab-container-registry). +1. [Use the custom workspace image in GitLab](#use-the-custom-workspace-image-in-gitlab). + +## Prerequisites + +- A GitLab account with permission to create and push container images to the GitLab Container Registry +- Docker installation + +## Create a base Dockerfile + +To create a base Dockerfile for the container image, let's use the Python `3.11-slim-bullseye` image from Docker Hub: + +```Dockerfile +FROM python:3.11-slim-bullseye +``` + +Next, you'll modify this base image. + +## Add support for arbitrary user IDs + +To add support for arbitrary user IDs to the base image, let's: + +1. Add a new `gitlab-workspaces` user with a `5001` user ID. +1. Set the necessary directory permissions. + +```Dockerfile +RUN useradd -l -u 5001 -G sudo -md /home/gitlab-workspaces -s /bin/bash -p gitlab-workspaces gitlab-workspaces + +ENV HOME=/home/gitlab-workspaces + +WORKDIR $HOME + +RUN mkdir -p /home/gitlab-workspaces && chgrp -R 0 /home && chmod -R g=u /etc/passwd /etc/group /home + +USER 5001 +``` + +Now that the image supports arbitrary user IDs, it's time to build the custom workspace image. + +## Build the custom workspace image + +To build the custom workspace image, run this command: + +```shell +docker build -t my-gitlab-workspace . +``` + +When the build is complete, you can test the image locally: + +```shell +docker run -ti my-gitlab-workspace sh +``` + +You should now be able to run commands as the `gitlab-workspaces` user. + +## Push the custom workspace image to the GitLab Container Registry + +To push the custom workspace image to the GitLab Container Registry: + +1. Sign in to your GitLab account: + + ```shell + docker login registry.gitlab.com + ``` + +1. Tag the image with the GitLab Container Registry URL: + + ```shell + docker tag my-gitlab-workspace registry.gitlab.com/your-namespace/my-gitlab-workspace:latest + ``` + +1. Push the image to the GitLab Container Registry: + + ```shell + docker push registry.gitlab.com/your-namespace/my-gitlab-workspace:latest + ``` + +Now that you've pushed the custom workspace image to the GitLab Container Registry, you can use the image in GitLab. + +## Use the custom workspace image in GitLab + +To use the custom workspace image in GitLab, in your project's `.devfile.yaml`, update the container image: + +```yaml +schemaVersion: 2.2.0 +components: + - name: tooling-container + attributes: + gl/inject-editor: true + container: + image: registry.gitlab.com/your-namespace/my-gitlab-workspace:latest +``` + +You're all set! You can now use this custom image with any [workspace](index.md) you create in GitLab. |