Configuring a devfile for a Dev Environment

A devfile is an open standard that helps you to customize your development Dev Environments across your team. A devfile is a YAML file that codifies your required development tools. By configuring a devfile, you can pre-determine the project tools and application libraries you need and Amazon CodeCatalyst installs them to your Dev Environment for you. The devfile is specific to the repository for which it was created, and you can create a separate devfile for each repository. Your Dev Environment supports commands and events, and provides a default universal devfile image.

If you create a project using the empty blueprint, you can create a devfile manually. If you create a project using a different blueprint, CodeCatalyst creates a devfile automatically. The /projects directory of a Dev Environment stores the files that are pulled from the source repository and the devfile. The /home directory, which is empty when you first create a Dev Environment, stores the files you create while using your Dev Environment. Everything in the /projects and /home directories of a Dev Environment is stored persistently.

Note

The /home folder only changes if you change the name of the devfile or devfile component name. If you change the devfile or devfile component name, the contents of the /home directory are replaced and your previous /home directory data cannot be recovered.

If you create a Dev Environment with a source repository that does not contain a devfile in its root, or if you create a Dev Environment without a source repository, a default universal devfile is applied to the source repository automatically. The same default universal devfile image is used for all IDEs. CodeCatalyst currently supports devfile version 2.0.0. For more information about the devfile, see Devfile schema - Version 2.0.0.

Note

You can only include public container images in your devfile.

Note that VPC-connected Dev Environments only support the following devfile images:

• Universal image

• Private Amazon ECR images, if the repository is in the same region as the VPC

Topics

• Editing a repository devfile for a Dev Environment
• Devfile features supported by CodeCatalyst
• Example of a devfile for a Dev Environment
• Troubleshooting a repository devfile using recovery mode
• Specifying universal devfile images for a Dev Environment
• Devfile commands
• Devfile events
• Devfile components

Devfile features supported by CodeCatalyst

CodeCatalyst supports the following devfile features on version 2.0.0. For more information about the devfile, see Devfile schema - Version 2.0.0.

Feature	Type
exec	Command
postStart	Event
container	Component
args	Component Properties
env	Component Properties
mountSources	Component Properties
volumeMounts	Component Properties

Example of a devfile for a Dev Environment

The following is an example of a simple devfile.

schemaVersion: 2.0.0
metadata:
  name: al2
components:
  - name: test
    container:
      image: public.ecr.aws/amazonlinux/amazonlinux:2
      mountSources: true
      command: ['sleep', 'infinity']
  - name: dockerstore
commands:
  - id: setupscript
    exec:
      component: test
      commandLine: "chmod +x script.sh"
      workingDir: /projects/devfiles
  - id: executescript
    exec:
      component: test
      commandLine: "/projects/devfiles/script.sh"
  - id: yumupdate
    exec:
      component: test
      commandLine: "yum -y update --security"
events:
  postStart:
    - setupscript
    - executescript
    - yumupdate

Devfile startup, command, and event logs are captured and stored in /aws/mde/logs. To debug devfile behaviour, start up your Dev Environment using a working devfile and access the logs.

Troubleshooting a repository devfile using recovery mode

If there's a problem starting your devfile, it will enter recovery mode so that you can still connect to your environment and fix your devfile. While in recovery mode, running /aws/mde/mde status won’t contain the location of your devfile.

{
            "status": "STABLE"
        }

You can check the error in the logs under /aws/mde/logs, fix the devfile, and try running /aws/mde/mde start again.