Writing configuration

Stacktape is an Infrastructure as a Code tool, building on top of the many advantages of this approach.

For people coming from a world of ClickOps (clicking in a GUI), this might seem inconvenient.

This is why most of the Stacktape configuration can also be done using a GUI.

Config editor

The most convenient way to write your configuration, is to use our interactive config editor.

The editor wraps monaco editor (the one used by VS code), and adds interactive capabilities, autocomplete, validation and more.

You can try a (limited) version of it below.

Interactive example

1. Select a preset

This will add a backbone of your configuration to the editor.

2. Configure resource details

All of the capital, green words are interactive. Click on them to open a configuration modal.

Configure details using a dropdown menu.

3. View the built in documentation

Hover over any property in the configuration to view its documentation.

4. Price estimator

After you configure enough properties for a resource, Stacktape will automatically calculate its estimated monthly costs.

5. Configure more properties

You can configure many more properties on your resources. To view all of the properties and their meaning, go to the respective documentation for that resource, or you can even trigger autosuggest in the editor using ctrl + space (fn + ctrl + space on certain systems).

6. View generated CloudFormation

After you configure all of the required properties, click on the Compiled CloudFormation tab to see the generated template.

7. Add more resources

You can add more resources by clicking on the + button and selecting New Stacktape resource.

8. Extend using CloudFormation

Stacktape templates can be extended using any AWS CloudFormation resource.

9. Add deployment scripts

You can also add a deployment script for tasks such as database migrations.

Using directives

Directives can be used to add dynamic behavior to your templates.

This guide only shows a fraction of what you can do using directives. To learn more about directives, refer to directives docs.

Built-in directives

For example, you can use built-in directives to dynamically set domain name for your web services.

Copy
resources:
  myHttpApi:
    type: http-api-gateway
    properties:
      customDomains:
        - domainName: $Format('{}-{}', $Stage(), 'api.mydomain.com')

Custom directives

You can use custom directives to add dynamic behavior to your templates.

1. Write the directive

Copy
export const getDbInstanceSize = (stage: string) => {
  if (stage === "production") {
    return "db.m5.xlarge";
  }
  return "db.t2.micro";
};

2. Register the directive

Copy
directives:
  - name: getDbInstanceSize
    filePath: directives.ts:getDbInstanceSize

3. Use the directive

Copy
resources:
  myDatabase:
    type: relational-database
    properties:
      engine:
        type: postgres
        properties:
          primaryInstance:
            instanceSize: $getDbInstanceSize($Stage())
      ...more properties...

Writing configuration in Typescript

Besides YAML, you can write your configuration in Javascript and Typescript.

If you also want to have type safety for your configurations, install @stacktape/sdk package from npm.

Copy
npm install --dev @stacktape/sdk

or

Copy
yarn add --dev @stacktape/sdk

For javascript files, you can use it in the following way:

Copy
/** @type {import('@stacktape/sdk').StacktapeConfig} */
const config = {
  // your config
};

export default config;

For typescript files:

Copy
import { StacktapeConfig } from "@stacktape/sdk";

const config: StacktapeConfig = {
  // your config
};

export default config;

Adding dynamic behavior

If your typescript file exports getConfig function, Stacktape executes this function to generate your config. The function receives an object containing stack parameters and must return a valid Stacktape configuration.

The following example shows how to adjust container resources based on stage (environment).

Copy
import type { GetConfigFunction } from '@stacktape/sdk';

export const getConfig: GetConfigFunction = ({ stage }) => {
  return {
    resources: {
      webService: {
        type: "web-service",
        properties: {
          resources: {
            cpu: stage === 'production' ? 0.5 : 2,
            memory: stage === 'production' ? 512 : 4096
          }
        ...more properties...
      },
    }
  }
};