Skip to main content

Create Stack and Starter via STK CLI

In this section, you will find a complete guide on how to create, validate, and publish Stacks and Starters using the STK CLI.


You will perform these steps using the STK CLI. Make sure to download it.

Create Stack via STK CLI

Before you start

Before you start, ensure that you:

Follow the steps below to create your Stack.

Step 1. Check your Plugins

Make sure you have already created and published the necessary Plugins in your Studio.

Step 2. Log in to the STK CLI

Open your terminal and run:

stk login

Step 3. Create the Stack

Run the following command to create a Stack:

stk create stack

Step 4. Answer the CLI prompts

Answer the questions shown in the terminal:

  • Name your stack: my-stack
  • Version (0.0.1): 1.0.0
  • Do you want to init a git repository? No
  • Add remote? Yes
  • Git URL to define remote origin: provide the URL
  • Stack description: describe your Stack goal

Step 5. Configure the stack.yaml file

Open the Stack folder. Then open and edit the stack.yaml file and fill out the Stack parameters.

Inside spec:, fill in the following options.

1. repository:

If you initialized a Git repository, fill in the repository as follows:

spec:
  repository: git@github.com:GitHub-UserName/my-local-repository.git

Example:

spec:
  repository: git@github.com:JohnDoe/my-stack.git

2. docs:

If you have any documentation for your Stack, name the documentation Markdown file as docs.md and place the file in the following folders:

  • docs/en_us: for English documentation;
  • docs/pt_br: for Portuguese documentation.

Example:

spec:
  # ...Other spec options above
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md

Fill in the name, URL, and picture to add a link to your Stack. The link will appear in the StackSpot Portal:

spec:
  # ...Other spec options above
  links:
    - name: My Stack link
      url: https://github.com/JohnDoe/my-stack
      picture: stack-image.png

4. plugins:

For both Plugin types, app and infra, fill the Plugins with the following syntax:

spec:
  # ...Other spec options above
  plugins:
    app:
      - name: studio-slug/app-plugin-name@<semantic-version>
    infra:
      - name: studio-slug/infra-plugin-name@<semantic-version>
tip

Plugins can be from other Studios; they do not need to be from the same Studio where you will publish the Stack, as long as you have access to them.

Example:

spec:
  # ...Other spec options above
  plugins:
    app:
      - name: my-studio/java-app-plugin@1.1.0
    infra:
      - name: my-studio/sqs-infra-plugin@2.1.0

5. actions:

To define Actions in your Stack, fill in the Action names as follows:

spec:
  # ...Other spec options above
  actions:
    - name: studio-slug/action-name1@<semantic-version>
    - name: studio-slug/action-name2@<semantic-version>
    - name: studio-slug/action-name3@<semantic-version>
tip

Actions can be from other Studios; they do not need to be from the same Studio where you will publish the Stack, as long as you have access to them.

Example:

spec:
  # ...Other spec options above
  actions:
    - name: my-studio/my-personal-action@3.0.0
    - name: organization-studio/action-with-connection@1.0.0
    - name: data-studio/action-get-data@0.0.1

Final stack.yaml example

At the end, you get a stack.yaml like the example below:

schema-version: v1
kind: stack
metadata:
  name: my-stack
  display-name: my-stack
  description: My Stack description
  version: 1.0.0
spec:
  repository: git@github.com:GitHub-UserName/my-local-repository.git
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  links:
    - name: My Stack link
      url: https://github.com/my-github-org/my-stack
      picture: stack-image.png
  plugins:
    app:
      - name: studio-slug/app-plugin-name@1.0.0
    infra:
      - name: studio-slug/infra-plugin-name@1.2.0
  actions:
    - name: studio-slug/action-name1@0.0.1
    - name: studio-slug/action-name2@1.0.1
    - name: studio-slug/action-name3@2.1.0

Step 6. Save your YAML file. You can now create your Starter.

Create Starter via STK CLI

Add the Plugins that the Starter will use, or the Stack validation command will fail.

Step 1. Ensure you are in the Stack folder

Ensure you have already created a Stack and that you are currently inside its folder to create a Starter.

Step 2. Create the Starter

Run the following command:

stk create starter

Step 3. Answer the CLI prompts

Answer the questions on your terminal:

  • Name your starter: basic-starter
  • Type: App
  • Do you want to add a git repository? Yes/No
  • Add remote? Yes/No
  • Git URL to define the remote origin: provide the URL
  • Starter description: describe your Starter
warning

Add the Starter name to your stack.yaml manually.

See the example:

spec:
  # ...Other spec options above
  starters:
    - path: starters/basic-starter
    - path: starters/java-starter

Step 4. Configure the starter.yaml file

Open the Stack folder, then open the Starter folder. Click on the starter.yaml file and fill out the Starter parameters.

1. type:

The type of the Plugins you add to the Starter. Currently, only app type is supported.

2. docs:

If you have any documentation for your Starter, name the documentation Markdown file as docs.md and place the file in the following folders:

  • docs/en_us: for English documentation;
  • docs/pt_br: for Portuguese documentation.

Example:

spec:
  # ...Other spec options above
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md

3. plugins:

In this parameter, add the required: option. Add the name of the Plugins that must be present in your Starter:

spec:
  # ...Other spec options above
  plugins:
    required:
      - name: studio-slug/<plugin-name>

Example:

spec:
  # ...Other spec options above
  plugins:
    required:
      - name: my-studio/app-java-plugin

Final starter.yaml example

Your starter.yaml will look like the example below:

schema-version: v1
kind: starter
metadata:
  name: basic-starter
  description: basic-starter
spec:
  type: app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  plugins:
    required:
      - name: my-studio/app-java-plugin
info

You can generate a basic Starter structure within a Stack. To do this, when you create the Stack, you can run the command to create the Stack with the --from option to create your Starter from an existing Stack.

Use the following syntax:

stk create stack --from [studio-slug]/[stack-slug]@[semantic-version]

Example:

stk create stack --from other-studio-slug/source-stack-slug@1.2.0

Check the name(s) of the generated Starter(s) and update the starters field in your Stack configuration file (stack.yaml).

Validate Starter

Inside your Starter folder, run the following command:

stk validate starter

Next, validate your Stack to check that all changes are correct.

Validate Stack

To validate your Stack and its Starters, follow the instructions:

  1. Enter your Stack folder;
  2. Run the command below:
stk validate stack

Publish Stack

Prerequisites

warning
  • It is mandatory that your Stack has Starters with Plugins. Plugins can be from Studios other than the Studio where you will publish the Stack, as long as you have access to them. If needed, see how to add Plugins to your Starter;
  • Check if the created Starters were added to your Stack configuration file (stack.yaml). To do this, check the starters section in how to add Starters to your Stack;
  • Your Stack folder cannot be empty.

When publishing a Stack, the Starters will be published as well and will be versioned together.

caution

If you add another Starter to your Stack, you must change the version and publish it again. The same workflow applies to the StackSpot Portal.

Step 1. Execute the publish command

Run the command:

stk publish stack

Step 2. Select your Studio

Select your Studio and press Enter, or provide your Studio name with the --studio option.

Example:

stk publish stack --studio my-personal-studio