Getting Started Guide 

Contents

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.

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.

Deploy Environment 

Deploy environments are used for selecting the options/variables/parameters to be used with each modules <module>. 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 

Create a directory for our project and change directory into the new directory.
```
$ mkdir sample-project && cd sample-project
```
Initialize the the new directory as a git repository and checkout branch ENV-dev. This will give us an environment of dev.
```
$ git init && git checkout -b ENV-dev
```

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.

$ curl -L https://oni.ca/runway/latest/linux -o runway
$ chmod +x runway

$ curl -L https://oni.ca/runway/latest/osx -o runway
$ chmod +x runway

Invoke-WebRequest -Uri "https://oni.ca/runway/latest/windows" -OutFile runway

Use Runway to generate a sample module using the gen-sample command. This will give us a preformatted module<runway-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
```
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.
dev-us-east-1.env
```
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
```

With the module ready to deploy, now we need to create our Runway config file. To do this, use the new command to generate a sample file at the root of the project repo.

$ ./runway new

runway.yml

---
# See full syntax at https://docs.onica.com/projects/runway
deployments:
  - modules:
      - nameofmyfirstmodulefolder
      - nameofmysecondmodulefolder
      # - etc...
  regions:
    - us-east-1

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.
runway.yml
```
---
# See full syntax at https://docs.onica.com/projects/runway
deployments:
  - modules:
      - sampleapp.cfn
  regions:
    - us-east-1
```
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
```
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.