### Install Stacktape via Script

Source: https://github.com/stacktape/intermediate-docs/blob/main/user-guides/installing-and-versioning.mdx

Installs Stacktape using platform-specific installation scripts. This method requires internet access to download and execute the script. After installation, users may need to manually add the Stacktape binary directory to their system's PATH environment variable.

```powershell
iwr https://installs.stacktape.com/windows.ps1 -useb | iex

```

```bash
curl -L https://installs.stacktape.com/linux.sh | sh

```

```bash
curl -L https://installs.stacktape.com/macos.sh | sh

```

```bash
curl -L https://installs.stacktape.com/macos-arm.sh | sh

```

--------------------------------

### Stacktape Domain Add Output (Initial)

Source: https://github.com/stacktape/intermediate-docs/blob/main/other-resources/domains-and-certificates.mdx

Example output from the `stacktape domain:add` command during initial domain setup, showing hosted zone creation and DNS server information.

```text
$ stacktape domain:add --region eu-west-1
✔ Domain name (example: mydomain.com) … simonobetko.net
[SUCCESS] Loading AWS credentials done in 0.7 sec. Loaded from Stacktape API.
[SUCCESS] Loading user data done in 1.98 sec. User: Šimon Obetko. Organization: Stacktape.
[SUCCESS] Fetching domain statuses done in 1.18 sec.
[INFO] To use domain simonobetko.net with Stacktape, DNS records must be in control of your AWS account.
       DNS records for domains are managed in hosted zones. (Hosted zone is a "container" for storing DNS records of your domain.)

[WARN] Currently, the domain simonobetko.net has no hosted zone created in your AWS account.
       To continue Stacktape needs to create hosted zone for your domain.
✔ Proceed with creating hosted zone for the domain simonobetko.net in your AWS account? … yes
[INFO] Hosted zone for domain simonobetko.net is created. Name servers of the AWS hosted zone are:
       - ns-1924.awsdns-48.co.uk
       - ns-290.awsdns-36.com
       - ns-913.awsdns-50.net
       - ns-1274.awsdns-31.org.

[INFO] You can finish adding your domain by:
       1. Copying DNS records from your current DNS hosting, into hosted zone created in your AWS account here: https://console.aws.amazon.com/route53/v2/hostedzones?#ListRecordSets/Z0759875A1OGK3MWN61Y
       2. Setting name server (NS) records at your current domain registrar. Name servers should point to the name servers of the hosted zone created in your AWS account(shown above).
       After domain is migrated run stacktape domain:add again to finish preparations (creating and validating TLS certs).

```

--------------------------------

### Install Stacktape CLI (Bash)

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/deploying-using-CLI.mdx

Installs the Stacktape CLI using platform-specific installation scripts. After installation, you may need to manually add the Stacktape binary directory to your system's PATH environment variable.

```bash
iwr https://installs.stacktape.com/windows.ps1 -useb | iex

```

```bash
curl -L https://installs.stacktape.com/linux.sh | sh

```

```bash
curl -L https://installs.stacktape.com/macos.sh | sh

```

```bash
curl -L https://installs.stacktape.com/macos-arm.sh | sh

```

--------------------------------

### Install Stacktape CLI Across Platforms

Source: https://github.com/stacktape/intermediate-docs/blob/main/user-guides/migrating-from-heroku.mdx

Provides commands to install the Stacktape CLI on Windows (PowerShell), Linux, macOS, and macOS ARM. These commands fetch and execute installation scripts from the Stacktape distribution server.

```bash
iwr https://installs.stacktape.com/windows.ps1 -useb | iex

```

```bash
curl -L https://installs.stacktape.com/linux.sh | sh

```

```bash
curl -L https://installs.stacktape.com/macos.sh | sh

```

```bash
curl -L https://installs.stacktape.com/macos-arm.sh | sh

```

--------------------------------

### Install Stacktape on Linux

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/deploying-using-3rd-party-CI.mdx

Installs Stacktape using a shell script for Linux environments. This is a common first step in CI/CD pipelines to ensure Stacktape is available.

```shell
curl -L https://installs.stacktape.com/linux.sh | bash
```

--------------------------------

### Run Custom Commands on Bastion Launch (YAML)

Source: https://github.com/stacktape/intermediate-docs/blob/main/security-resources/bastions.mdx

Execute custom commands as the root user when the bastion host is launched. This is useful for installing dependencies or initial setup. Modifying this list after creation forces instance replacement.

```yaml
resources:
  myBastion:
    type: bastion
    properties:
      runCommandsAtLaunch:
        - yum update
        - yum install postgresql.x86_64 -y
```

--------------------------------

### Stacktape Resource Configuration Example

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/under-the-hood.mdx

Illustrates a typical Stacktape resource definition in YAML, specifying a Lambda function with a custom buildpack and its entry file path.

```yml
resources:
  myLambda:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my/lambda.ts
```

--------------------------------

### Relational Database Configuration Example

Source: https://github.com/stacktape/intermediate-docs/blob/main/database-resources/api-reference/relational-database.mdx

Example YAML configuration for defining a relational database resource in Stacktape, including credentials and engine settings.

```YAML
resources:
  myRelationalDatabase:
    type: relational-database
    properties:
      # Configures credentials for the database master user
      #
      # - Credentials for master user can be used to connect to the database.
      # - Master user credentials are used in database `connectionString` (URL).
      #
      # - Type: object
      # - Required: true
      credentials:
        # Password of the database master user
        #
        # - Password protects the database from unauthorized access to your database.
        # - Due to password being part of database `connectionString` (URL), it should not contain following characters: `[]{}(),;?*=!@`
        # - We recommend to store password as [secret](https://docs.stacktape.com/security-resources/secrets/)
        # and reference the secret using [$Secret](https://docs.stacktape.com/configuration/directives/#secret) directive to avoid secret being exposed in the config.
        #
        # - Type: string
        # - Required: true
        masterUserPassword: $Secret(database_password)
        # Username of the database master user
        #
        # - This name will be used for the main admin user in your database.
        # - Due to name being part of database `connectionString` (URL), it should not contain following characters: `[]{}(),;?*=!@`
        # - You can use this name for connecting to the database.
        #
        # > Changing this parameter after database was created will cause database replacement and data loss
        #
        # - By default this `db_master_user` is used
        #
        # - Type: string
        # - Required: false
        # - Default: db_master_user
        masterUserName: admin
      # Configures the underlying database engine and its properties
      #
      # Database engine determines the properties of your database, such as database type (PostgreSQL, MySQL...), number of instances, high availability capabilities, redundancy,
      # performance, scaling behavior, pricing etc.
      #
      # Depending on the properties they provide, we group engine types into following groups:
      #
      # **Rds Engine** group
      # - To use the RDS engine, set the `engine.type` property to `postgres`, `mysql`, `mariadb`, `oracle-ee`, `oracle-se2`, `sqlserver-ee`, `sqlserver-ex`, `sqlserver-se` or `sqlserver-web`.
      # - Fully managed single-node database engines.
      # - Configurable read replicas (additional parallelly-running, automatically-replicated instances used for read operations).
      #
      # **Aurora Engine** group
      # - To use the Aurora engine, set the `engine.type` property to `aurora-postgresql` or `aurora-mysql`.
      # - Fully-managed AWS-developed engines (based on and compatible with either PostgreSQL or MySQL) with clustering support, high-availability, increased durability & performance.
      # - Compute instances (nodes) run across multiple Availability Zones. Storage is automatically replicated 6-ways across 3
      # availability zones.
      # - Automatically load-balances read operations between nodes.
      # - Automatic failover - if a primary instance fails, one of the read replicas is elected as a new primary instance.
      # - To learn more about Aurora Engines, refer to [AWS Docs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless.how-it-works.html)
      #
      # **Aurora Serverless Engine** group
      # >
      # > We recommend using newer Aurora **Aurora Serverless V2 Engines** instead of this one.
      # >
      # - To use the Aurora engine, set the `engine.type` property to `aurora-postgresql-serverless` or `aurora-mysql-serverless`.
      # - Fully-managed AWS-developed engines (based on and compatible with either PostgreSQL or MySQL) with high-availability, increased durability & performance.
      # - Supported engines: `aurora-postgresql-serverless`, `aurora-mysql-serverless`.
      # - Similar to Aurora Engines, but automatically scales based on usage.
      # - Scaling is done using ACUs (Aurora Compute units). Each ACU has ~2GB of RAM and 1 virtual CPU.
      # - Can scale to 0 ACUs (database is paused, and you don't pay anything).
      # - To learn more about Aurora Engines, refer to [AWS Docs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless.how-it-works.html)
      #
      # **Aurora Serverless V2 Engine** group
      # - To use the Aurora engine, set the `engine.type` property to `aurora-postgresql-serverless-v2` or `aurora-mysql-serverless-v2`.
      # - Fully-managed AWS-developed engines (based on and compatible with either PostgreSQL or MySQL) with high-availability, increased durability & performance.
      # - Supported engines: `aurora-postgresql-serverless-v2`, `aurora-mysql-serverless-v2`.
      # - Similar to Aurora Serverless Engines, but is more responsive, more granular, and less disruptive when scaling.

```

--------------------------------

### Install Specific Stacktape Version

Source: https://github.com/stacktape/intermediate-docs/blob/main/user-guides/installing-and-versioning.mdx

Installs a specific version of Stacktape by setting the STACKTAPE_VERSION environment variable before running the installation script. This allows for precise control over the deployed version. Internet access is required.

```powershell
$env:STACKTAPE_VERSION="2.0.0" && iwr https://installs.stacktape.com/windows.ps1 -useb | iex

```

```bash
export STACKTAPE_VERSION="2.0.0" && curl -L https://installs.stacktape.com/linux.sh | sh

```

```bash
export STACKTAPE_VERSION="2.0.0" && curl -L https://installs.stacktape.com/macos.sh | sh

```

```bash
export STACKTAPE_VERSION="2.0.0" && curl -L https://installs.stacktape.com/macos-arm.sh | sh

```

--------------------------------

### Stacktape Resource Configurations and Permissions

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/api-reference/nextjs-web.mdx

Details the permissions required and environment variables injected for various Stacktape-managed resources, enabling secure integration and access.

```APIDOC
Resource: User Access
  Permissions:
  - Creates access "user" associated with compute resource's role to allow for secure credential-less access to the cluster.
  Injected Environment Variables:
  - CONNECTION_STRING

Resource: Relational (SQL) database
  Permissions:
  - Allows connection to a relational database with accessibilityMode set to scoping-workloads-in-vpc.
  Injected Environment Variables:
  - CONNECTION_STRING
  - JDBC_CONNECTION_STRING
  - HOST
  - PORT
  - READER_CONNECTION_STRING (for aurora multi instance cluster)
  - READER_JDBC_CONNECTION_STRING (for aurora multi instance cluster)
  - READER_HOST (for aurora multi instance cluster)

Resource: Redis cluster
  Permissions:
  - Allows connection to a redis cluster with accessibilityMode set to scoping-workloads-in-vpc.
  Injected Environment Variables:
  - HOST
  - READER_HOST
  - PORT

Resource: Event bus
  Permissions:
  - Publish events to the specified Event bus.
  Injected Environment Variables:
  - ARN

Resource: Function
  Permissions:
  - Invoke the specified function.
  - Invoke the specified function via url (if lambda has URL enabled).
  Injected Environment Variables:
  - ARN

Resource: Batch job
  Permissions:
  - Submit batch-job instance into batch-job queue.
  - List submitted job instances in a batch-job queue.
  - Describe / terminate a batch-job instance.
  - List executions of state machine which executes the batch-job according to its strategy.
  - Start / terminate execution of a state machine which executes the batch-job according to its strategy.
  Injected Environment Variables:
  - JOB_DEFINITION_ARN
  - STATE_MACHINE_ARN

Resource: User auth pool
  Permissions:
  - Full control over the user pool (cognito-idp:*).
  - Refer to AWS docs for allowed methods.
  Injected Environment Variables:
  - ID
  - CLIENT_ID
  - ARN

Resource: SNS Topic
  Permissions:
  - Confirm/list subscriptions of the topic.
  - Publish/subscribe to the topic.
  - Unsubscribe from the topic.
  Injected Environment Variables:
  - ARN
  - NAME

Resource: SQS Queue
  Permissions:
  - Send/receive/delete message.
  - Change visibility of message.
  - Purge queue.
  Injected Environment Variables:
  - ARN
  - NAME
  - URL

Resource: Upstash Kafka topic
  Injected Environment Variables:
  - TOPIC_NAME
  - TOPIC_ID
  - USERNAME
  - PASSWORD
  - TCP_ENDPOINT
  - REST_URL

Resource: Upstash Redis
  Injected Environment Variables:
  - HOST
  - PORT
  - PASSWORD
  - REST_TOKEN
  - REST_URL
  - REDIS_URL

Resource: Private service
  Injected Environment Variables:
  - ADDRESS

Macro: aws:ses
  Permissions:
  - Gives full permissions to aws ses (ses:*).
  - Refer to AWS docs for allowed methods.
  Type: array<string>
  Required: false

Configuration: connectTo
  Type: array<string>
  Description: List of resources to connect to.
  Example:
    - myDatabase
    - myBucket
  Required: false

Configuration: iamRoleStatements
  Type: array<object (reference)>
  Description: Raw AWS IAM role statements appended to your resources' role.
  Required: false
```

--------------------------------

### Stacktape connectTo Configuration Example

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/web-services.mdx

Example YAML configuration demonstrating the use of the `connectTo` property within a Stacktape `web-service` resource. This allows the service to access specified resources like a bucket or AWS services, with Stacktape managing the necessary permissions and environment variables.

```yaml
resources:
  photosBucket:
    type: bucket

  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      # {start-highlight}
      connectTo:
        # access to the bucket
        - photosBucket
        # access to AWS SES
        - aws:ses
      # {stop-highlight}
      resources:
        cpu: 0.25
        memory: 512
```

--------------------------------

### Stacktape Web App Firewall Integration

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/api-reference/nextjs-web.mdx

Configures the integration of a 'web-app-firewall' resource to protect applications from common web exploits.

```APIDOC
useFirewall: example-value
  # Type: string
  # Required: false
  # Name of the 'web-app-firewall' resource to be used with your CDN.
```

--------------------------------

### Install Stacktape on Alpine Linux

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/deploying-using-3rd-party-CI.mdx

Installs Stacktape using a shell script specifically for Alpine Linux environments. This script is optimized for Alpine's package manager.

```shell
curl -L https://installs.stacktape.com/alpine.sh | bash
```

--------------------------------

### Upstash Redis Configuration Example

Source: https://github.com/stacktape/intermediate-docs/blob/main/3rd-party-resources/api-reference/upstash-redis.mdx

Demonstrates a basic Upstash Redis resource configuration in YAML, detailing properties like `enableEviction` and its behavior.

```yml
resources:
  myUpstashRedis:
    type: upstash-redis
    properties:
      # Enables automatic eviction of keys when memory is full
      #
      # - When enabled, Redis will automatically evict keys when memory limit is reached.
      # - Uses optimistic-volatile algorithm (combination of volatile-random and allkeys-random policies).
      # - Allows older data to be automatically removed to make room for new data.
      #
      # - Type: boolean
      # - Required: false
      # - Default: false
      enableEviction: false
```

--------------------------------

### Install Stacktape SDK

Source: https://github.com/stacktape/intermediate-docs/blob/main/user-guides/writing-config-in-typescript.mdx

Instructions for installing the `@stacktape/sdk` package using npm or yarn. This package provides essential types and utilities for writing Stacktape configurations.

```bash
npm install @stacktape/sdk
```

```bash
yarn add @stacktape/sdk
```

--------------------------------

### Example Server Container (TypeScript)

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/private-services.mdx

An example server application written in TypeScript using Express. It listens on the port specified by the PORT environment variable, which is automatically injected by Stacktape.

```ts
import express from 'express';

const app = express();

app.get('/', async (req, res) => {
  res.send({ message: 'Hello' });
});

// for your app use port number stored in PORT environment variable for your application
// this environment variable is automatically injected by Stacktape
app.listen(process.env.PORT, () => {
  console.info(`Server running on port ${process.env.PORT}`);
});
```

--------------------------------

### Example ExpressJS Web Service (TypeScript)

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/web-services.mdx

Demonstrates a basic ExpressJS application listening on the PORT environment variable, as automatically injected by Stacktape for web services. This example shows how to handle requests and log the port the server is running on.

```ts
import express from 'express';

const app = express();

app.get('/', async (req, res) => {
  res.send({ message: 'Hello' });
});

// for your use port number stored in PORT environment variable for your application
// this environment variable is automatically injected by Stacktape
app.listen(process.env.PORT, () => {
  console.info(`Server running on port ${process.env.PORT}`);
});
```

--------------------------------

### Stacktape Resource Configuration Example

Source: https://github.com/stacktape/intermediate-docs/blob/main/configuration/referencing-parameters.mdx

Defines a Stacktape Lambda function resource with properties including packaging and destinations, showcasing how to reference CloudFormation parameters for cross-resource dependencies.

```yml
resources:
  myBucket:
    type: bucket

  processData:
    type: function
    properties:
      packageConfig:
        filePath: path/to/my/lambda.ts
      destinations:
        onFailure: $CfResourceParam('MySnsTopic', 'Arn')
      environment:
        name: BUCKET_NAME
        value: $CfResourceParam('MyBucketBucket', 'Name')
```

--------------------------------

### Route CDN requests to an http-api-gateway

Source: https://github.com/stacktape/intermediate-docs/blob/main/other-resources/cdns.mdx

Configures the CDN to route requests matching a specific path prefix to another http-api-gateway. This example routes requests starting with `/app2/` to `appApiGateway`.

```yaml
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'http-api-gateway'
              properties:
                httpApiGatewayName: appApiGateway
```

--------------------------------

### Before Deploy Hook Example

Source: https://github.com/stacktape/intermediate-docs/blob/main/configuration/hooks.mdx

Demonstrates how to define a script (e.g., 'buildWeb') and reference it within a 'beforeDeploy' hook in the Stacktape configuration. This allows pre-deployment tasks like building an application.

```yaml
scripts:
  # {start-highlight}
  buildWeb:
    # {stop-highlight}
    type: local-script
    properties:
      executeCommand: npx gatsby build

hooks:
  beforeDeploy:
    # {start-highlight}
    - scriptName: buildWeb
    # {stop-highlight}
```

--------------------------------

### Route CDN requests to a bucket

Source: https://github.com/stacktape/intermediate-docs/blob/main/other-resources/cdns.mdx

Configures the CDN to route requests matching a specific path prefix to a designated bucket. This example routes requests starting with `/static` to `myBucket`.

```yaml
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /static/*
            routeTo:
              type: bucket
              properties:
                bucketName: myBucket
                disableUrlNormalization: true
```

--------------------------------

### Pushing to Bitbucket Repository

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/deploying-using-3rd-party-CI.mdx

Steps to initialize a Git repository, commit changes, set the remote origin to your Bitbucket repository, and push to the main branch to trigger the Bitbucket pipeline.

```shell
git init --initial-branch=main
git commit -m "setup stacktape project"
git remote add origin https://<<bitbucket-usernme>>@bitbucket.org/<<project>>/<<repository>>.git (replace with your Bitbucket repository information)
git push -u origin main
```

--------------------------------

### Get Stacktape Version (CLI)

Source: https://github.com/stacktape/intermediate-docs/blob/main/cli/commands/version.mdx

Executes the Stacktape CLI command to display the currently installed version of Stacktape. This command requires no arguments and provides immediate output of the version number.

```bash
stacktape version
```

--------------------------------

### Show Stacktape CLI Help

Source: https://github.com/stacktape/intermediate-docs/blob/main/cli/commands/help.mdx

Prints general help information for the Stacktape CLI to the console, describing available commands and their arguments.

```bash
stacktape help
```

--------------------------------

### Route CDN requests to a custom origin

Source: https://github.com/stacktape/intermediate-docs/blob/main/other-resources/cdns.mdx

Configures the CDN to route requests matching a specific path prefix to a custom domain origin. This example routes requests starting with `/external` to `my-custom-origin.example.com`.

```yaml
resources:
  myLoadBalancer:
    type: 'application-load-balancer'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /external/*
            routeTo:
              type: custom-origin
              properties:
                domainName: my-custom-origin.example.com
```

--------------------------------

### Route CDN requests to an application load balancer

Source: https://github.com/stacktape/intermediate-docs/blob/main/other-resources/cdns.mdx

Configures the CDN to route requests matching a specific path prefix to an application load balancer. This example routes requests starting with `/app2` to `myLoadBalancer`.

```yaml
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'application-load-balancer'
              properties:
                loadBalancerName: myLoadBalancer
```

--------------------------------

### Initialize T3 App with npm

Source: https://github.com/stacktape/intermediate-docs/blob/main/tutorials/t3-nextjs-app.mdx

Scaffolds a new full-stack, typesafe Next.js application using the create-t3-app CLI. This command initiates the project setup process, prompting the user for various configuration choices.

```bash
npm create t3-app@latest
```

--------------------------------

### Stacktape CLI Basic Usage

Source: https://github.com/stacktape/intermediate-docs/blob/main/cli/using-cli.mdx

Demonstrates the fundamental structure of Stacktape CLI commands, showing the general syntax with placeholders for commands, options, and values.

```bash
stacktape <<command>> --option1 <<option1>> --option2 <<option2>> ...more options...
```

--------------------------------

### Nixpacks Packaging Configuration Example

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/api-reference/worker-service.mdx

This YAML snippet demonstrates how to configure the Nixpacks packaging type for a worker service. It outlines properties such as source directory, build image, providers, start command, and include files.

```yaml
resources:
  myWorkerService:
    type: worker-service
    properties:
      # Configures an image used for the service container
      #
      # - Type: object
      # - Required: true
      packaging:
        #
        # - Type: string
        # - Required: true
        type: nixpacks
        #
        # - Type: object
        # - Required: true
        properties:
          # Path to the directory where the buildpack will be executed
          #
          # - Type: string
          # - Required: true
          sourceDirectoryPath: ./
          # Build Image
          #
          # - The image to use as the base when building the application.
          # - To learn more, refer to [nixpacks docs](https://nixpacks.com/docs/configuration/file#build-image)
          #
          # - Type: string
          # - Required: false
          buildImage: example-value
          # Providers
          #
          # - A list of provider names used to determine build and runtime environments.
          #
          # - Type: array<string>
          # - Required: false
          providers:
            - example-value
          # Start Command
          #
          # - The command to execute when starting the application.
          # - Overrides default start commands inferred by nixpacks.
          #
          # - Type: string
          # - Required: false
          startCmd: example-value
          # Start Run Image
          #
          # - The image to use as the base when running the application.
          #
          # - Type: string
          # - Required: false
          startRunImage: example-value
          # Start Only Include Files
          #
          # - A list of file paths to include in the runtime environment.
          # - Other files will be excluded.
          #
          # - Type: array<string>
          # - Required: false
          startOnlyIncludeFiles:
            - example-value
          # Phases
          #
          # - Defines the build phases for the application.
          # - Each phase specifies commands, dependencies, and settings.
          #
          # - Type: array<object (reference)>
          # - Required: false
          phases:
```

--------------------------------

### Stacktape CLI init command API Reference

Source: https://github.com/stacktape/intermediate-docs/blob/main/cli/commands/init.mdx

Provides detailed information about the parameters and options available for the `stacktape init` command, including descriptions, types, aliases, and allowed values.

```APIDOC
stacktape init [options]

Initializes a Stacktape project in the specified directory.

Options:
  --initializeProjectTo <string>  Path to the directory where the starter project should be initialized to.
                                  If not specified, you will be prompted to specify it interactively using CLI.
                                  If the directory is not empty, its contents will be deleted.
                                  Alias: -ipt

  --logFormat <string>            Format of logs printed to your console.
                                  Available options:
                                  - fancy: Logs are colorized and dynamically re-rendered.
                                  - normal: Logs are colorized but not dynamically re-rendered.
                                  - basic: Simple text only
                                  - json: Logs are printed as JSON objects
                                  Alias: -lf

  --logLevel <string>             Level of logs that are being printed to the console.
                                  Available options:
                                  - info: Prints basic information about everything that's happening.
                                  - error: Prints only errors.
                                  - debug: Prints detailed information about everything that's happening.
                                  Alias: -ll

  --projectDirectory <string>     Path to the root project directory where the configuration should be generated to.
                                  Alias: -pd

  --starterId <string>            Identifier of the starter project to initialize.
                                  Alias: -sid

  --templateId <string>           Id of the template to download.
                                  The list of available templates is available on the Config builder page (https://console.stacktape.com/templates).
                                  Alias: -ti
```

--------------------------------

### Configure External Buildpack Packaging

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/api-reference/worker-service.mdx

This YAML configuration illustrates the setup for `external-buildpack` packaging. It covers properties such as the source directory path, the builder image to use, specific buildpacks to apply, and the command to execute when the container starts.

```yaml
resources:
  myWorkerService:
    type: worker-service
    properties:
      # Configures an image used for the service container
      #
      # - Type: object
      # - Required: true
      packaging:
        #
        # - Type: string
        # - Required: true
        type: external-buildpack
        #
        # - Type: object
        # - Required: true
        properties:
          # Path to the directory where the buildpack will be executed
          #
          # - Type: string
          # - Required: true
          sourceDirectoryPath: "./"
          # Buildpack Builder to use
          #
          # - By default, [paketobuildpacks/builder-jammy-base](https://github.com/paketo-buildpacks/builder-jammy-base) is used.
          #
          # - Type: string
          # - Required: false
          # - Default: paketobuildpacks/builder-jammy-base
          builder: paketobuildpacks/builder-jammy-base
          # Buildpack to use
          #
          # - By default, buildpacks is detected automatically.
          #
          # - Type: array<string>
          # - Required: false
          buildpacks:
            - example-value
          # Command to be executed when the container starts.
          #
          # - Example: `['app.py']`.
          #
          # - Type: array<string>
          # - Required: false
          command:
            - node
            - dist/index.js
```

--------------------------------

### Bitbucket Pipeline with Stacktape Direct Deploy

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/deploying-using-3rd-party-CI.mdx

Example Bitbucket pipeline configuration using `stacktape deploy`. This method performs all deployment operations, such as packaging and uploading artifacts, directly within the pipeline container. It requires the container image to have all necessary dependencies pre-installed.

```yaml
image: public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:5.0

pipelines:
  default:
    - step:
        name: "Deploy"
        deployment: production
        script:
          # install stacktape
          - curl -L https://installs.stacktape.com/linux.sh | sh
          - export PATH="/root/.stacktape/bin:\$PATH"
          # run stacktape
          - stacktape deploy --projectName my-project-1 --stage production --region eu-west-1
```

--------------------------------

### Configure Datadog Log Forwarding (YAML)

Source: https://github.com/stacktape/intermediate-docs/blob/main/security-resources/api-reference/bastion.mdx

This YAML snippet configures log forwarding to Datadog. It specifies the log forwarding type as 'datadog' and requires an API key for authentication. An optional endpoint URL can be provided, with a default value if not specified. This setup leverages Amazon Kinesis Data Firehose for log delivery.

```yaml
resources:
  myBastion:
    type: bastion
    properties:
      logging:
        messages:
          logForwarding:
            type: datadog
            properties:
              apiKey: example-value
              endpointUrl: https://aws-kinesis-http-intake.logs.datadoghq.com/v1/input
```

--------------------------------

### Configure Bastion Resource Properties (YAML)

Source: https://github.com/stacktape/intermediate-docs/blob/main/security-resources/api-reference/bastion.mdx

This YAML snippet defines the configuration for a bastion resource in Stacktape. It specifies the instance size, commands to execute upon launch, and detailed logging settings for system messages, including retention policies and log forwarding destinations.

```yaml
resources:
  myBastion:
    type: bastion
    properties:
      # Host instance size
      #
      # - Instance size you wish to use for your bastion host
      # - Default instance size is `t3.micro` (Free Tier eligible)
      #
      # - Type: string
      # - Required: false
      # - Default: t3.micro
      instanceSize: t3.micro
      # Commands to be ran on launch (creation) of the bastion instance
      #
      # - Commands are run as the root user (do not use sudo).
      # - Modifying this list after bastion was already created will force replacement of the bastion instance.
      # This means that any data that was manually created on the old bastion instance will be lost.
      # - Use this if to install dependencies and packages that might be required for your bastion scripts
      #
      # - Type: array<string>
      # - Required: false
      runCommandsAtLaunch:
        - example-value
      # Configures logging for bastion host
      #
      # - Multiple log types are collected from you bastion host. You can specify log behaviour for each different log type.
      #
      # - Type: object
      # - Required: false
      logging:
        # Configures log behavior for log group collecting logs from `/var/log/messages` of your bastion host
        #
        # - Logs contain global system messages, including the messages that are logged during system startup.
        # There are several things that are logged in /var/log/messages including mail, cron, daemon, kern, auth, etc.
        # - By default "messages" logs are retained for 30 days.
        #
        # - Type: object
        # - Required: false
        messages:
          # Disables the collection of logs to CloudWatch
          #
          #
          # - Type: boolean
          # - Required: false
          # - Default: false
          disabled: false
          # Amount of days the logs will be retained in the log group
          #
          # - Type: enum: [1, 120, 14, 150, 180, 1827, 3, 30, 365, 3653, 400, 5, 545, 60, 7, 731, 90]
          # - Required: false
          # - Allowed values: [1, 120, 14, 150, 180, 1827, 3, 30, 365, 3653, 400, 5, 545, 60, 7, 731, 90]
          retentionDays: 1
          # Configures forwarding of logs to specified destination
          #
          # - Log forwarding is done using [Amazon Kinesis Data Firehose](https://aws.amazon.com/kinesis/data-firehose/) delivery stream.
          # - When using log forwarding, you will incur costs based on the amount of data being transferred to the destination (~$0.03 per transferred GB).
          # Refer to [AWS Kinesis Firehose Pricing](https://aws.amazon.com/kinesis/firehose/pricing/?nc=sn&loc=3) page to see details.
          # - Currently supported destinations for logs:
          # - `http-endpoint`
          # - delivers logs to any HTTP endpoint.
          # - The endpoint must follow [Firehose request and response specifications](https://docs.aws.amazon.com/firehose/latest/dev/httpdeliveryrequestresponse.html).
          # (Many of the third party vendors are compliant with this specifications out of the box.)
          # - `datadog`
          # - delivers logs to [Datadog](https://www.datadoghq.com/).
          # - `highlight`
          # - delivers logs to [Highlight.io](https://www.highlight.io/) project.
          #
          # Refer to [our docs](https://docs.stacktape.com/configuration/log-forwarding/) for more information.
          #
          # > Logs that fail to be delivered to the destination even after multiple retries (time spend on retries can be configured) are put into bucket with name `{stackName}-{resourceName}-logs-{generatedHash}`
          #
          # - Type: union (anyOf)
          # - Required: false
          #
          # - Type: object
          # - Required: false
          logForwarding:
            #
            # - Type: string
            # - Required: true
            type: http-endpoint
            #
            # - Type: object
            # - Required: true
            properties:
              # HTTPS endpoint where logs will be forwarded
              #
              # - Type: string
              # - Required: true
              endpointUrl: https://example.com
              # Specifies whether to use GZIP compression for the request
              #
              # - When enabled, Firehose uses the content encoding to compress the body of a request before sending the request to the destination
              #
              # - Type: boolean
              # - Required: false
              gzipEncodingEnabled: true
              # Parameters included in each call to HTTP endpoint
              #
              # - Key/Value pairs containing additional metadata you wish to send to the HTTP endpoint.
              # - Parameters are delivered within **X-Amz-Firehose-Common-Attributes** header as a JSON object with following format: `{"commonAttributes":{"param1":"val1", "param2":"val2"}}`

```

--------------------------------

### Stacktape Serverless Function Warm-up and Edge Lambda Configuration

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/api-reference/nextjs-web.mdx

Manages serverless function performance by keeping instances warm or utilizing Lambda@Edge. `warmServerInstances` periodically invokes the function to mitigate cold starts, but does not work with Lambda@Edge. `useEdgeLambda` deploys the function closer to users for reduced latency but disables warmers and increases deployment times.

```yaml
warmServerInstances: 100
```

```yaml
useEdgeLambda: false
```

--------------------------------

### secret:get Command API Reference

Source: https://github.com/stacktape/intermediate-docs/blob/main/cli/commands/secret-get.mdx

Detailed API reference for the `stacktape secret:get` command, including all parameters, their types, allowed values, and descriptions.

```APIDOC
secret:get
  Prints details about the specified secret to the console.

  Parameters:
    --region <string> (required, alias: -r)
      AWS region to use for the current operation.
      Allowed values: af-south-1, ap-east-1, ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, eu-central-1, eu-north-1, eu-south-1, eu-west-1, eu-west-2, eu-west-3, me-south-1, sa-east-1, us-east-1, us-east-2, us-west-1, us-west-2
    --awsAccount <string> (optional, alias: -aa)
      Name of the AWS account used to perform the operation.
      The account must be first connected in the Stacktape console.
    --help (optional, alias: -h)
      Shows help for the command.
      If specified, the command won't perform any action besides printing help.
    --logFormat <string> (optional, alias: -lf)
      Format of logs printed to your console.
      Available options: fancy, normal, basic, json.
      - fancy: Logs are colorized and dynamically re-rendered.
      - normal: Logs are colorized but not dynamically re-rendered.
      - basic: Simple text only
      - json: Logs are printed as JSON objects
    --logLevel <string> (optional, alias: -ll)
      Level of logs that are being printed to the console.
      Available options: debug, error, info.
      - info: Prints basic information about everything that's happening.
      - error: Prints only errors.
      - debug: Prints detailed information about everything that's happening.
    --profile <string> (optional, alias: -p)
      AWS profile to use with the command.
      You can manage AWS profiles on your system using `aws-profile:create`, `aws-profile:update` or `aws-profile:delete` command.
      You can configure the default profile used with every Stacktape command using the `defaults:configure` command.

  Example:
    stacktape secret:get --region <<region>>
```

--------------------------------

### Stacktape API: Server Function Configuration Parameters

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/api-reference/nextjs-web.mdx

Defines configuration options for server functions within Stacktape. This includes network connectivity, performance optimization, build processes, and data handling for streaming services.

```APIDOC
ServerFunctionConfig:
  joinDefaultVpc: boolean
    description: "Specifies whether to connect the function to the default VPC. Connecting to the VPC may restrict internet access but is required for accessing VPC-internal resources like databases. VPC gateway endpoints are automatically created for S3 and DynamoDB access."
    required: false
    default: false

  warmServerInstances: number
    description: "Configures the number of server lambda instances to keep warm to mitigate cold start latency. A warmer function periodically invokes the server function. This feature is not compatible with lambda@edge."
    required: false
    default: 0

  useEdgeLambda: boolean
    description: "Enables the use of Lambda@Edge for the server function, executing it closer to users globally for reduced response times. Downsides include slower deployments and the inability to use the warmer function."
    required: false
    default: false

  buildCommand: string
    description: "Allows specifying a custom build command for Next.js applications. Useful for projects with non-standard build requirements."
    required: false

  fileOptions: array<object>
    description: "An array of objects to manually set headers (e.g., cache-control, content-type) for files matching specific filter patterns."
    required: false
    example:
      - "**/*.html":
          cacheControl: "public, max-age=3600"

  environmentVariables: object
    description: "Injects environment variables into the runtime environment of the server function. Used for passing configuration details about other infrastructure components."
    required: false
    example:
      USER_POOL_ID: "us-east-1_xxxxxxxxx"
      API_GATEWAY_ENDPOINT: "https://api.example.com/v1"
```

--------------------------------

### Stacktape CLI: Get Secret

Source: https://github.com/stacktape/intermediate-docs/blob/main/cli/commands/secret-get.mdx

Command to print details of a specified secret to the console.

```bash
stacktape secret:get --region <<region>>
```

--------------------------------

### GitHub Actions Workflow: Stacktape deploy

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/deploying-using-3rd-party-CI.mdx

This GitHub Actions workflow shows how to deploy an application using Stacktape's 'deploy' command. This approach executes all deployment operations, including packaging and artifact uploads, directly within the GitHub Actions runner. It requires a container image with dependencies like Docker and Node.js pre-installed.

```yaml
name: Deploy application using Stacktape
on:
  push:
    branches:
      - main
jobs:
  deploy-app:
    runs-on: ubuntu-latest
    container:
      image: public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:5.0
    steps:
      - name: Install Stacktape
        run: curl -L https://installs.stacktape.com/linux.sh | bash
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Deploy the stack
        run: stacktape deploy --stage <<stage>> --region <<region>> --projectName <<projectName>>
        env:
          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
```

--------------------------------

### Stacktape CLI param:get Command

Source: https://github.com/stacktape/intermediate-docs/blob/main/cli/commands/param-get.mdx

Details the parameters for the Stacktape CLI 'param:get' command. It outlines required and optional arguments, their types, aliases, and descriptions, including specific allowed values for certain parameters like region and log format.

```APIDOC
Stacktape CLI param:get Command

This command retrieves parameters. It accepts several arguments to specify the operation context and behavior.

Command Signature:
param:get <paramName> [--region <region>] [--stage <stage>] [--awsAccount <awsAccount>] [--configPath <configPath>] [--logFormat <logFormat>] [--logLevel <logLevel>] [-pn <paramName>] [-r <region>] [-s <stage>] [-aa <awsAccount>] [-cp <configPath>] [-lf <logFormat>] [-ll <logLevel>] [-h]

Parameters:

- paramName (string, required, alias: pn):
  The name of the parameter to retrieve.

- region (string, required, alias: r):
  AWS region to use for the current operation.
  Allowed values: "af-south-1", "ap-east-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "eu-central-1", "eu-north-1", "eu-south-1", "eu-west-1", "eu-west-2", "eu-west-3", "me-south-1", "sa-east-1", "us-east-1", "us-east-2", "us-west-1", "us-west-2"

- resourceName (string, required, alias: rn):
  The name of the resource.

- stage (string, required, alias: s):
  Stage used for the operation.
  Example stages are `production`, `staging`, `testing` or `dev-john`.
  You can configure the default stage used with every Stacktape command using the `defaults:configure` command.
  Maximum allowed length is 12 characters.

- awsAccount (string, optional, alias: aa):
  Name of the AWS account used to perform the operation.
  The account must be first connected in the Stacktape console.

- configPath (string, optional, alias: cp):
  Path to your stacktape configuration file.
  Relative to CWD (current working directory).

- help (boolean, optional, alias: h):
  Shows help for the command.
  If specified, the command won't perform any action besides printing help.

- logFormat (string, optional, alias: lf):
  Format of logs printed to your console.
  Available options: `fancy`, `normal`, `basic`, `json`.

- logLevel (string, optional, alias: ll):
  Level of logs that are being printed to the console.
  Available options: `debug`, `error`, `info`.
```

--------------------------------

### GitHub Actions Workflow - Basic Structure

Source: https://github.com/stacktape/intermediate-docs/blob/main/getting-started/deploying-using-3rd-party-CI.mdx

Provides a basic structure for a GitHub Actions workflow file. This YAML file defines the steps to install and execute Stacktape within a CI/CD pipeline.

```yaml
# Example workflow configuration file path: .github/workflows/<<your-workflow-name>>.yml
# This file configures automated CI/CD workflows, including installing and running Stacktape.
```

--------------------------------

### Example Worker Service Application (TypeScript)

Source: https://github.com/stacktape/intermediate-docs/blob/main/compute-resources/worker-services.mdx

A basic TypeScript example for a continuously running application within a worker service container.

```ts
import myContinuouslyRunningApp from './my-app';

const app = myContinuouslyRunningApp();

app.run();
```