Creating devfiles

Most dev tools can utilize the devfile registry to fetch the stacks needed to begin development on projects. Sometimes, however, you might need to create a devfile from scratch or to create your own devfile template(s). This guide runs through the process, starting from a minimum devfile and building sample templates for common use cases.

Prerequisites

Procedure

Creating a minimal devfile:
- schemaVersion is the only required root element
- metadata is optional but it is recommended to have in your templates
Minimal Devfile
devfile.yaml
```
schemaVersion: 2.3.0
```
Minimal Devfile with Metadata
devfile.yaml
```
schemaVersion: 2.3.0
metadata:
  name: devfile-sample
  version: 2.0.0
```

Creating a web service template:

Template metadata
- Set the template name and version
- Set a description for the template
- Set the projectType and language to describe what kind of stack is being used
- Set provider to tell who is providing this template
- Set tags to give keyword which describe the elements of the stack
- Set architectures to specify the platforms support in the template
- For improved readability on devfile registries, set displayName to the title that will be the display text for this template and icon to tie a stack icon to the template:
```
  schemaVersion: 2.3.0
  metadata:
    name: web-service
    version: 1.0.0
    description: A web service template.
    projectType: Go
    language: Go
    provider: Red Hat
    tags: [ 'Go', 'Gin', 'pq' ]
    architectures: [ 'amd64' ]
    displayName: Simple Web Service
    icon: https://raw.githubusercontent.com/devfile-samples/devfile-stack-icons/main/golang.svg
```
Setup components
- A name is required for a component
- If a container entity is defined, an image property must be specified
- Though endpoints is optional, it is needed to expose the port for web connections and requires:
  - An endpoint name
  - A targetPort to expose, for example, 8080 if that is your http port
- The web service might need to connect to an external database using environment variables. In this case, define environment variable names and values for the container component under env:
```
components:
  - name: web
    container:
      endpoints:
        - name: http
          targetPort: 8080
      env:
        DATABASE_HOST: db.example.com
        DATABASE_PORT: 5432
        DATABASE_NAME: dev
        DATABASE_USER: devuser
        DATABASE_PASSWORD: devpassword
      image: quay.io/devfile/golang:latest
```

Adding commands

An id to identify the command
An exec entity must be defined with a commandLine string and a reference to a component
- This implies that at least one component entity is defined under the root components element
The workingDir is set to where the project source is stored
Command groups can be used to define automation that is useful for executing a web service:

commands:
  - id: build
    exec:
      commandLine: go build main.go
      component: web
      workingDir: ${PROJECT_SOURCE}
      group:
        kind: build
        isDefault: true
  - id: run
    exec:
      commandLine: ./main
      component: web
      workingDir: ${PROJECT_SOURCE}
      group:
        kind: run
        isDefault: true

Define starter projects

Add a starter project under starterProjects including at least a name and remote location, either git or zip

It is recommended to include a starter project description:

starterProjects:
  - name: web-starter
    description: A web service starting point.
    git:
      remotes:
        origin: https://github.com/devfile-samples/devfile-stack-go.git

Completing the content, the complete devfile should look like the following:

Complete Web Service Template

devfile.yaml

schemaVersion: 2.3.0
metadata:
  name: web-service
  version: 1.0.0
  description: A web service template.
  projectType: Go
  language: Go
  provider: Red Hat
  tags: [ 'Go', 'Gin', 'pq' ]
  architectures: [ 'amd64' ]
  displayName: Simple Web Service
  icon: https://raw.githubusercontent.com/devfile-samples/devfile-stack-icons/main/golang.svg
components:
  - name: web
    container:
      endpoints:
        - name: http
          targetPort: 8080
      env:
        DATABASE_HOST: db.example.com
        DATABASE_PORT: 5432
        DATABASE_NAME: dev
        DATABASE_USER: devuser
        DATABASE_PASSWORD: devpassword
      image: quay.io/devfile/golang:latest
commands:
  - id: build
    exec:
      commandLine: go build main.go
      component: web
      workingDir: ${PROJECT_SOURCE}
      group:
        kind: build
        isDefault: true
  - id: run
    exec:
      commandLine: ./main
      component: web
      workingDir: ${PROJECT_SOURCE}
      group:
        kind: run
        isDefault: true
starterProjects:
  - name: web-starter
    description: A web service starting point.
    git:
      remotes:
        origin: https://github.com/devfile-samples/devfile-stack-go.git

Devfile.io

Creating devfiles

Prerequisites

Procedure

Minimal Devfile

Minimal Devfile with Metadata

Complete Web Service Template

Additional Resources