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¶
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.
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
Deploying Your First Module¶
Create a directory for our project and change directory into the new directory.
# macOS example $ mkdir sample-project $ cd sample-project
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
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
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
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
$ ./runway new
--- # See full syntax at https://docs.onica.com/projects/runway/en/latest/ 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.
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
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
$ ./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¶
$ ./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.