Getting Started Guide

Basic Concepts

Welcome to Runway! To get a basic understanding of Runway, we have listed out the key concepts below that you will need to get started with deploying your first module.

Runway Config File

The Runway config file is usually stored at the root of a project repo. It defines the modules that will be managed by Runway.

Deployment

A deployment contains a list of modules and options for all the modules in the deployment. A Runway config file can contain multiple deployments and a deployment can contain multiple modules.

Module

A module is a directory containing a single infrastructure-as-code tool configuration of an application, a component, or some infrastructure (eg. a set of CloudFormation templates). It is defined in a deployment by path. Modules can also contain granular options that only pertain to it.

Environment

Environments are used for selecting the options/variables/parameters to be used with each modules. They can be defined by the name of a directory (if its not a git repo), git branch, or environment variable (DEPLOY_ENVIRONMENT). Standard environments would be something like prod, dev, and test.

No matter how the environment is determined, the name is made available to be consumed by your modules as the DEPLOY_ENVIRONMENT environment variable.

Deploying Your First Module

  1. Create a directory for our project and change directory into the new directory.

    # macOS example
    $ mkdir sample-project
    $ cd sample-project
    
  2. Initialize the the new directory as a git repo and checkout branch ENV-dev. This will give us an environment of dev.

    # macOS example
    $ git init
    $ git checkout -b ENV-dev
    
  3. Download Runway using curl. Be sure to use the endpoint that corresponds to your operating system. Then, change the downloaded file’s permissions to allow execution.

    # macOS example
    $ curl -L https://oni.ca/runway/latest/osx -o runway
    $ chmod +x runway
    
  4. Use Runway to generate a sample module using the gen-sample command. This will give us a preformatted module that is ready to be deployed after we change a few variables. To read more about the directory structure, see Repo Structure.

    $ ./runway gen-sample cfn
    
  5. To finish configuring our CloudFormation module , lets open the dev-us-east-1.env file that was created in sampleapp.cfn/. Here is where we will define values for our stacks that will be deployed as part of the dev environment in the us-east-1 region. Replace the place holder values in this file with your own information. It is important that the cfngin_bucket_name value is globally unique for this example as it will be used to create a new S3 bucket.

    namespace: onica-dev
    customer: onica
    environment: dev
    region: us-east-1
    # The CFNgin bucket is used for CFN template uploads to AWS
    cfngin_bucket_name: cfngin-onica-us-east-1
    
  6. With the module ready to deploy, now we need to create our Runway config file. Do to this, use the init command to generate a sample file at the root of the project repo.

    $ ./runway init
    

    runway.yml contents

    ---
    # See full syntax at https://docs.onica.com/projects/runway/en/latest/
    deployments:
      - modules:
          - nameofmyfirstmodulefolder
          - nameofmysecondmodulefolder
          # - etc...
      regions:
        - us-east-1
    
  7. Now, we need to modify the runway.yml file that was just created to tell it where the module is located that we want it to deploy and what regions it will be deployed to. Each module type has their own configuration options which are described in more detail in the Module Configurations section but, for this example we are only concerned with the CloudFormation module configuration.

    The end result should like this:

    ---
    # See full syntax at https://docs.onica.com/projects/runway/en/latest/
    deployments:
      - modules:
          - sampleapp.cfn
      regions:
        - us-east-1
    
  8. Before we deploy, it is always a good idea to know how the module will impact the currently deployed infrastructure in your AWS account. This is less of a concern for net-new infrastructure as it is when making modifications. But, for this example, lets run the plan command to see what is about to happen.

    $ ./runway plan
    
  9. We are finally ready to deploy! Use the deploy command to deploy our module.

    $ ./runway deploy
    

We have only scratched the surface with what is possible in this example. Proceed below to find out how to delete the module we just deployed or, review the pages linked throughout this section to learn more about what we have done to this point before continuing.

Deleting Your First Module

From the root of the project directory we created in Deploying Your First Module we only need to run the destroy command to remove what we have deployed.

$ ./runway destroy

Execution Without A TTY (non-interactive)

Runway allows you to set an environment variable to allow execution without a TTY or if STDIN is closed. This allows users to execute Runway deployments in their CI/CD infrastructure as code deployment systems avoiding the EOF when reading a line error message. In order to execute runway without a TTY, set the CI environment variable before your runway [deploy|destroy] execution.

Important

Executing Runway in this way will cause Runway to perform updates in your environment without prompt. Use with caution.