# Code Editor administrator guide
<a name="code-editor-admin"></a>

You can use Code Editor with an On-Demand Instance for faster start-up time, and configurable storage. You can launch a Code Editor application through Amazon SageMaker Studio or through the AWS CLI. You can also edit Code Editor default settings within the domain console. For more information, see [Edit domain settings](domain-edit.md). The following topics outline how administrators can configure Code Editor, based on Code-OSS, Visual Studio Code - Open Source by changing storage options, customizing environments, and managing user access, as well as giving information about the prerequisites needed to use Code Editor.

**Topics**
+ [

# Complete prerequisites
](code-editor-admin-prerequisites.md)
+ [

# Give your users access to private spaces
](code-editor-admin-user-access.md)
+ [

# Change the default storage size
](code-editor-admin-storage-size.md)
+ [

# Code Editor lifecycle configurations
](code-editor-use-lifecycle-configurations.md)
+ [

# Custom images
](code-editor-custom-images.md)

# Complete prerequisites
<a name="code-editor-admin-prerequisites"></a>

To use Code Editor, based on Code-OSS, Visual Studio Code - Open Source, you must complete the following prerequisites.

1. You must first onboard to Amazon SageMaker AI domain and create a user profile. For more information, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md).

1. If you are interacting with your Code Editor application using the AWS CLI, you must also complete the following prerequisites.

   1.  Update the AWS CLI by following the steps in [Installing the current AWS CLI Version](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html#install-tool-bundled). 

   1.  From your local machine, run `aws configure` and provide your AWS credentials. For information about AWS credentials, see [Understanding and getting your AWS credentials](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html). 

1. (Optional) To get more storage and compute for your application, you can request an increase to your AWS quotas. For more information about requesting a quota increase, see [Amazon SageMaker AI endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/sagemaker.html).

# Give your users access to private spaces
<a name="code-editor-admin-user-access"></a>

**Important**  
Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions).  
[AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources.

This section provides a policy that grants user access to private spaces. You can also use the policy to restrict private spaces and applications that are associated with them to the owner associated with the user profile. 

You must provide your users with permissions to the following:
+ Private spaces
+ The user profile required for access to the private spaces

To provide permissions, attach the following policy to the IAM roles of your users.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {

      "Effect": "Allow",
      "Action": [
        "sagemaker:CreateApp",
        "sagemaker:DeleteApp"
      ],
      "Resource": "arn:aws:sagemaker:us-east-1:111122223333:app/*",
      "Condition": {
        "Null": {
          "sagemaker:OwnerUserProfileArn": "true"
        }
      }
    },
    {
      "Sid": "SMStudioCreatePresignedDomainUrlForUserProfile",
      "Effect": "Allow",
      "Action": [
        "sagemaker:CreatePresignedDomainUrl"
      ],
      "Resource": "arn:aws:sagemaker:us-east-1:111122223333:user-profile/domain-id/user-profile-name"
    },
    {
      "Sid": "SMStudioAppPermissionsListAndDescribe",
      "Effect": "Allow",
      "Action": [
        "sagemaker:ListApps",
        "sagemaker:ListDomains",
        "sagemaker:ListUserProfiles",
        "sagemaker:ListSpaces",
        "sagemaker:DescribeApp",
        "sagemaker:DescribeDomain",
        "sagemaker:DescribeUserProfile",
        "sagemaker:DescribeSpace"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SMStudioAppPermissionsTagOnCreate",
      "Effect": "Allow",
      "Action": [
        "sagemaker:AddTags"
      ],
      "Resource": "arn:aws:sagemaker:us-east-1:111122223333:*/*",
      "Condition": {
        "Null": {
          "sagemaker:TaggingAction": "false"
        }
      }
    },
    {
      "Sid": "SMStudioRestrictSharedSpacesWithoutOwners",
      "Effect": "Allow",
      "Action": [
        "sagemaker:CreateSpace",
        "sagemaker:UpdateSpace",
        "sagemaker:DeleteSpace"
      ],
      "Resource": "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/*",
      "Condition": {
        "Null": {
          "sagemaker:OwnerUserProfileArn": "true"
        }
      }
    },
    {
      "Sid": "SMStudioRestrictSpacesToOwnerUserProfile",
      "Effect": "Allow",
      "Action": [
        "sagemaker:CreateSpace",
        "sagemaker:UpdateSpace",
        "sagemaker:DeleteSpace"
      ],
      "Resource": "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/*",
      "Condition": {
        "ArnLike": {
        "sagemaker:OwnerUserProfileArn": "arn:aws:sagemaker:us-east-1:111122223333:user-profile/domain-id/user-profile-name"
        },
        "StringEquals": {
          "sagemaker:SpaceSharingType": [
            "Private",
            "Shared"
          ]
        }
      }
    },
    {
      "Sid": "SMStudioRestrictCreatePrivateSpaceAppsToOwnerUserProfile",
      "Effect": "Allow",
      "Action": [
        "sagemaker:CreateApp",
        "sagemaker:DeleteApp"
      ],
      "Resource": "arn:aws:sagemaker:us-east-1:111122223333:app/domain-id/*",
      "Condition": {
        "ArnLike": {
        "sagemaker:OwnerUserProfileArn": "arn:aws:sagemaker:us-east-1:111122223333:user-profile/domain-id/user-profile-name"
        },
        "StringEquals": {
          "sagemaker:SpaceSharingType": [
            "Private"
          ]
        }
      }
    }
  ]
}
```

------

# Change the default storage size
<a name="code-editor-admin-storage-size"></a>

You can change the default storage settings of your users. You can also change the default storage settings based on your organizational requirements and the needs of your users.

To change the storage size of your users, do the following:

1. Update the Amazon EBS storage settings in the domain. 

1. Create a user profile and specify the storage settings within it.

Use the following AWS Command Line Interface (AWS CLI) command to update the domain.

```
aws --region $REGION sagemaker update-domain \
--domain-id $DOMAIN_ID \
--default-user-settings '{
    "SpaceStorageSettings": {
        "DefaultEbsStorageSettings":{
            "DefaultEbsVolumeSizeInGb":5,
            "MaximumEbsVolumeSizeInGb":100
        }
    }
}'
```

Use the following AWS CLI command to create the user profile and specify the default storage settings.

```
aws --region $REGION sagemaker create-user-profile \
--domain-id $DOMAIN_ID \
--user-profile-name $USER_PROFILE_NAME \
--user-settings '{
    "SpaceStorageSettings": {
        "DefaultEbsStorageSettings":{
            "DefaultEbsVolumeSizeInGb":5,
            "MaximumEbsVolumeSizeInGb":100
        }
    }
}'
```

Use the following AWS CLI commands to update the default storage settings in the user profile.

```
aws --region $REGION sagemaker update-user-profile \
--domain-id $DOMAIN_ID \
--user-profile-name $USER_PROFILE_NAME \
--user-settings '{
    "SpaceStorageSettings": {
        "DefaultEbsStorageSettings":{
            "DefaultEbsVolumeSizeInGb":25,
            "MaximumEbsVolumeSizeInGb":200
        }
    }
}'
```

# Code Editor lifecycle configurations
<a name="code-editor-use-lifecycle-configurations"></a>

You can use Code Editor lifecycle configurations to automate customization for your Studio environment. This customization includes installing custom packages, configuring extensions, preloading datasets, and setting up source code repositories

The following instructions use the AWS Command Line Interface (AWS CLI) to create, attach, debug, and detach lifecycle configurations for the `CodeEditor` application type:
+ [Create and attach lifecycle configurations in Studio](code-editor-use-lifecycle-configurations-studio-create.md)
+ [Debug lifecycle configurations in Studio](code-editor-use-lifecycle-configurations-studio-debug.md)
+ [Detach lifecycle configurations in Studio](code-editor-use-lifecycle-configurations-studio-detach.md)

# Create and attach lifecycle configurations in Studio
<a name="code-editor-use-lifecycle-configurations-studio-create"></a>

The following section provides AWS CLI commands to create a lifecycle configuration, attach a lifecycle configuration when creating a new user profile, and attach a lifecycle configuration when updating a user profile. For prerequisites and general steps on creating and attaching lifecycle configurations in Studio, see [Lifecycle configuration creation](jl-lcc-create.md). 

When creating your Studio lifecycle configuration with the `create-studio-lifecycle-config` command, be sure to specify that the `studio-lifecycle-config-app-type` is `CodeEditor`. The following example shows how to create a new Studio lifecycle configuration for your Code Editor application.

```
aws sagemaker create-studio-lifecycle-config \
--studio-lifecycle-config-name my-code-editor-lcc \
--studio-lifecycle-config-content $LCC_CONTENT \
--studio-lifecycle-config-app-type CodeEditor
```

Note the ARN of the newly created lifecycle configuration that is returned. When attaching a lifecycle configuration, provide this ARN within the `LifecycleConfigArns` list of `CodeEditorAppSettings`. 

You can attach a lifecycle configuration when creating a user profile or domain. The following example shows how to create a new user profile with the lifecycle configuration attached. You can also create a new domain with a lifecycle configuration attached by using the [create-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/opensearch/create-domain.html) command.

```
# Create a new UserProfile
aws sagemaker create-user-profile \
--domain-id domain-id \
--user-profile-name user-profile-name \
--user-settings '{
"CodeEditorAppSettings": {
  "LifecycleConfigArns":
    [lifecycle-configuration-arn-list]
  }
}'
```

You can alternatively attach a lifecycle configuration when updating a user profile or domain. The following example shows how to update a user profile with the lifecycle configuration attached. You can also update a new domain with a lifecycle configuration attached by using the [update-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-domain.html) command.

```
# Update a UserProfile
aws sagemaker update-user-profile \
--domain-id domain-id \
--user-profile-name user-profile-name \
--user-settings '{
"CodeEditorAppSettings": {
  "LifecycleConfigArns":
    [lifecycle-configuration-arn-list]
  }
}'
```

# Debug lifecycle configurations in Studio
<a name="code-editor-use-lifecycle-configurations-studio-debug"></a>

To debug lifecycle configuration scripts for Code Editor, you must use Studio. For instructions about debugging lifecycle configurations in Studio, see [Debug lifecycle configurations](jl-lcc-debug.md). To find the logs for a specific application, search the log streams using the following format:

```
domain-id/space-name/CodeEditor/default/LifecycleConfigOnStart
```

# Detach lifecycle configurations in Studio
<a name="code-editor-use-lifecycle-configurations-studio-detach"></a>

To detach lifecycle configurations for Code Editor, you can use either the console or the AWS CLI. For steps on detaching lifecycle configurations from the Studio console, see [Detach lifecycle configurations](jl-lcc-delete.md).

To detach a lifecycle configuration using the AWS CLI, remove the desired lifecycle configuration from the list of lifecycle configurations attached to the resource. Then pass the list as part of the respective command:
+ [update-user-profile](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-user-profile.html)
+ [update-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-domain.html)

For example, the following command removes all lifecycle configurations for the Code Editor application attached to the domain.

```
aws sagemaker update-domain --domain-id domain-id \
--default-user-settings '{
"CodeEditorAppSettings": {
  "LifecycleConfigArns":
    []
  }
}'
```

# Create a lifecycle configuration to clone repositories into a Code Editor application
<a name="code-editor-use-lifecycle-configurations-repositories"></a>

This section shows how to clone a repository and create a Code Editor application with the lifecycle configuration attached.

1. From your local machine, create a file named `my-script.sh` with the following content:

   ```
   #!/bin/bash
   set -eux
   ```

1. Clone the repository of your choice in your lifecycle configuration script. 

   ```
   export REPOSITORY_URL="https://github.com/aws-samples/sagemaker-studio-lifecycle-config-examples.git"
   git -C /home/sagemaker-user clone $REPOSITORY_URL
   ```

1. After finalizing your script, create and attach your lifecycle configuration. For more information, see [Create and attach lifecycle configurations in Studio](code-editor-use-lifecycle-configurations-studio-create.md).

1. Create your Code Editor application with the lifecycle configuration attached.

   ```
   aws sagemaker create-app \
   --domain-id domain-id \
   --space-name space-name \
   --app-type CodeEditor \
   --app-name default \
   --resource-spec "SageMakerImageArn=arn:aws:sagemaker:region:image-account-id:image/sagemaker-distribution-cpu,LifecycleConfigArn=arn:aws:sagemaker:region:user-account-id:studio-lifecycle-config/my-code-editor-lcc,InstanceType=ml.t3.large"
   ```

   For more information about available Code Editor image ARNs, see [Code Editor application instances and images](code-editor-use-instances.md).

# Create a lifecycle configuration to install Code Editor extensions
<a name="code-editor-use-lifecycle-configurations-extensions"></a>

This section shows how to create a lifecycle configuration to install extensions from the [Open VSX Registry](https://open-vsx.org/) in your Code Editor environment.

1. From your local machine, create a file named `my-script.sh` with the following content:

   ```
   #!/bin/bash
   set -eux
   ```

1. Within the script, install the [Open VSX Registry](https://open-vsx.org/) extension of your choice:

   ```
   sagemaker-code-editor --install-extension AmazonEMR.emr-tools --extensions-dir /opt/amazon/sagemaker/sagemaker-code-editor-server-data/extensions
   ```

   You can retrieve the extension name from the URL of the extension in the [Open VSX Registry](https://open-vsx.org/). The extension name to use in the `sagemaker-code-editor` command should contain all text that follows `https://open-vsx.org/extension/` in the URL. Replace all instances of a slash (`/`) with a period (`.`). For example, `AmazonEMR/emr-tools` should be `AmazonEMR.emr-tools`.  
![\[The Amazon EMR extension page in the Open VSX Registry.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/code-editor/code-editor-emr-extension.png)

1. After finalizing your script, create and attach your lifecycle configuration. For more information, see [Create and attach lifecycle configurations in Studio](code-editor-use-lifecycle-configurations-studio-create.md).

1. Create your Code Editor application with the lifecycle configuration attached:

   ```
   aws sagemaker create-app \
   --domain-id domain-id \
   --space-name space-name \
   --app-type CodeEditor \
   --app-name default \
   --resource-spec "SageMakerImageArn=arn:aws:sagemaker:region:image-account-id:image/sagemaker-distribution-cpu,LifecycleConfigArn=arn:aws:sagemaker:region:user-account-id:studio-lifecycle-config/my-code-editor-lcc,InstanceType=ml.t3.large"
   ```

   For more information about available Code Editor image ARNs, see [Code Editor application instances and images](code-editor-use-instances.md). For more information about connections and extensions, see [Code Editor Connections and Extensions](code-editor-use-connections-and-extensions.md).

# Custom images
<a name="code-editor-custom-images"></a>

If you need functionality that is different than what's provided by SageMaker distribution, you can bring your own image with your custom extensions and packages. You can also use it to personalize the Code Editor UI for your own branding or compliance needs.

The following page will provide Code Editor-specific information and templates to create your own custom SageMaker AI images. This is meant to supplement the Amazon SageMaker Studio information and instructions on creating your own SageMaker AI image and bringing your own image to Studio. To learn about custom Amazon SageMaker AI images and how to bring your own image to Studio, see [Bring your own image (BYOI)](studio-updated-byoi.md). 

**Topics**
+ [

## Health check and URL for applications
](#code-editor-custom-images-app-healthcheck)
+ [

## Dockerfile examples
](#code-editor-custom-images-dockerfile-templates)

## Health check and URL for applications
<a name="code-editor-custom-images-app-healthcheck"></a>
+ `Base URL` – The base URL for the BYOI application must be `CodeEditor/default`. You can only have one application and it must always be named `default`.
+ Health check endpoint – You must host your Code Editor server at 0.0.0.0 port 8888 for SageMaker AI to detect it.
+  Authentication – You must pass `--without-connection-token` when opening `sagemaker-code-editor` to allow SageMaker AI to authenticate your users.

**Note**  
If you are using Amazon SageMaker Distribution as the base image, these requirements are already taken care of as part of the included `entrypoint-code-editor` script.

## Dockerfile examples
<a name="code-editor-custom-images-dockerfile-templates"></a>

The following examples are `Dockerfile`s that meets the above information and [Custom image specifications](studio-updated-byoi-specs.md).

**Note**  
If you are bringing your own image to SageMaker Unified Studio, you will need to follow the [Dockerfile specifications](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html) in the *Amazon SageMaker Unified Studio User Guide*.  
`Dockerfile` examples for SageMaker Unified Studio can be found in [Dockerfile example](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html#byoi-specifications-example) in the *Amazon SageMaker Unified Studio User Guide*.

------
#### [ Example micromamba Dockerfile ]

The following is an example Dockerfile to create an image from scratch using a [https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) base environment: 

```
FROM mambaorg/micromamba:latest
ARG NB_USER="sagemaker-user"
ARG NB_UID=1000
ARG NB_GID=100

USER root

RUN micromamba install -y --name base -c conda-forge sagemaker-code-editor

USER $NB_UID

CMD eval "$(micromamba shell hook --shell=bash)"; \
    micromamba activate base; \
    sagemaker-code-editor --host 0.0.0.0 --port 8888 \
        --without-connection-token \
        --base-path "/CodeEditor/default"
```

------
#### [ Example SageMaker AI Distribution Dockerfile ]

The following is an example Dockerfile to create an image based on [Amazon SageMaker AI Distribution](https://github.com/aws/sagemaker-distribution/tree/main):

```
FROM public.ecr.aws/sagemaker/sagemaker-distribution:latest-cpu
ARG NB_USER="sagemaker-user"
ARG NB_UID=1000
ARG NB_GID=100
ENV MAMBA_USER=$NB_USER

USER root

 # install scrapy in the base environment
RUN micromamba install -y --name base -c conda-forge scrapy

 # download VSCodeVim
RUN \
  wget https://github.com/VSCodeVim/Vim/releases/download/v1.27.2/vim-1.27.2.vsix \
  -P /tmp/exts/ --no-check-certificate

 # Install the extension
RUN \
  extensionloc=/opt/amazon/sagemaker/sagemaker-code-editor-server-data/extensions \
  && sagemaker-code-editor \
    --install-extension "/tmp/exts/vim-1.27.2.vsix" \
    --extensions-dir "${extensionloc}"

USER $MAMBA_USER
ENTRYPOINT ["entrypoint-code-editor"]
```

------