Getting Started Guide
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.
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 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 (
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.envfile 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_namevalue 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
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
--- # 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.ymlfile 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.
--- # 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
runway [deploy|destroy] execution.
Executing Runway in this way will cause Runway to perform updates in your environment without prompt. Use with caution.