Skip to content

Latest commit

 

History

History
121 lines (78 loc) · 4.97 KB

advanced_use.md

File metadata and controls

121 lines (78 loc) · 4.97 KB

Advanced use

The following document provides a guide to the advanced features provided by capsule.

Your website configuration

Capsule supports a number of command line parameters to allow you to configure your web site.

In addition to this, you can use a JSON configuration file as generated by the init command, containing these values.

When loading configuration options, the JSON config is loaded first, if specified. Following this any command line parameters are then loaded. Command line parameters will override any parameters specified in the JSON file.

An example can be seen here:

./bin/capsule.js create --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom  --config ~/.aws/config.json --site_config='{"WebsiteCode":"./build"}' --site_config_file=./my_config/capsule.json ci

In this example the value of the --site_config flag will overwrite the the key value pair specified in the --site_config_file JSON file. Thus if WebsiteCode is defined in capsule.json it's value will be overridden with ./build.

You can always check what command line parameters are available by running the capsule -h command.

Advanced CLI use

The capsule cli is a NodeJS cli app with the intention to simplify the generation of the hosting infrastructure and ci infrastructure. For nested stacks, it requires the generation of a base s3 bucket. This can be generated in the following way:

$ ./capsule create --project-name <project-name> s3

Once this bucket is in place, the web infrastructure can then be created using the web command line option.

For example:

  $ ./capsule create --project-name <project-name> web

Having setup the infrastructure, you can then add in the CI pipeline as follows:

  $ ./capsule create --project-name <project-name> ci

Not all the examples above, have assumed a capsule.js file is present, and that the ProjectName value has been overwritten by the --project-name parameter.

In addition to the create command, Capsule also supports an update and delete command.

For getting the complete list of options and how they are used, just enter --help:

$ ./bin/capsule.js --help

  Usage: capsule [options] [command]

  Options:

    -V, --version            output the version number
    -v, --verbose            verbose output
    -h, --help               output usage information

  Commands:

    init                     Define the project parameters
    deploy                   Builds out the web hosting infrastructure in one go
    remove [options]         Removes the whole of the web hosting infrastructure, including files in S3 buckets
    create [options] <type>  Initializes the s3 bucket required to store nested stack templates takes: s3, ci or web
    update [options] <type>  Updates the templates into the s3 bucket and runs the nested stack takes: s3, ci or web
    delete [options] <type>  Deletes the s3 bucket contents takes: s3, ci or web

Advanced CI use

The ci tool can be executed from the command line in order to setup the CodeBuild process. Located in this repository are two CodeBuild files:

  1. codebuild_capsule.cf - this contains the CodeBuild CF templates for this project
  2. codebuild_project.cf - which provides a template for the Capsule user to use for their own project

In addition to the ci tool the CodeBuild cf templates can also be executed from the aws cli.

From the CLI it can be used like this:

aws cloudformation create-stack \
    --stack-name <your-stack-name> \
    --template-body file://<path-to-repo>/ci/<codebuild_template>.cf \
    --parameters ParameterKey=CodeBuildProjectCodeName,ParameterValue=<project-name> \
                 ParameterKey=RepositoryURL,ParameterValue=<https-clone-url> \
                 ParameterKey=BuildSpecLocation,ParameterValue=<path-to-buildspec>

Example:

aws cloudformation create-stack \
    --stack-name moduscreate-labs \
    --template-body file://<path-to-repo>/ci/codebuild_project.cf \
    --parameters ParameterKey=CodeBuildProjectCodeName,ParameterValue=labs \
                 ParameterKey=RepositoryURL,ParameterValue=https://github.com/ModusCreateOrg/labs.git

Supported parameters:

  • CodeBuildProjectCodeName: CodeBuild Project codename.
  • RepositoryURL: HTTPS URL for the Git repository. This should be a valid repository HTTPS URL.
  • RepositoryType: CODECOMMIT|CODEPIPELINE|GITHUB|GITHUB_ENTERPRISE|BITBUCKET|S3. Default: GITHUB.
  • EnvironmentImage: Image to use for running a container where the build will execute. Needs to respect the format <repository>/<image>:<tag>. Default: aws/codebuild/ubuntu-base:14.04
  • ComputeType: BUILD_GENERAL1_SMALL (Small 3 GB memory, 2 vCPU) | BUILD_GENERAL1_MEDIUM (Medium 7 GB memory, 4 vCPU) | BUILD_GENERAL1_LARGE (large 15 GB memory, 8 vCPU). Default: BUILD_GENERAL1_SMALL.
  • BuildSpecLocation: Path of the file buildspec.yml to use (Defaults to <repo-root>/buildspec.yml