convox_installer 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17cad3f4b73806ac2ed58a97ab6434e79dec6ef71ca6d569118fe5366e7ff195
-  data.tar.gz: 8ab6d4b135cc5716688ae59519ea85f3600736a9b30cc851ae21c62502f7fefb
+  metadata.gz: d892f211775c729520e50a17e48b4f086125d468e80928c702f82e9f933552a8
+  data.tar.gz: 90464c717b7ec52844b5f61a236a2b0b41c14f13c76907cb3773bde012d818bf
 SHA512:
-  metadata.gz: '08989fb82a81ab02b996852abdbd58319e5bf50f2ce4c44ea44824e4cd798e0b73b785739f445c7ea66b211e925edc5161e0c6bf98b637d58af6b5d4c19f2bf7'
-  data.tar.gz: a20b0ebcc13e2be8fad48940dc970181e9faa76af1b1e8832759cfb3c22b21a972ab6d4a4c4389a84f1c401b0876e4d6deb9a3232e0434615db076322295294e
+  metadata.gz: f713ae774ad544fb8e461108f0347086d81ac53f785d198fec22ac8dd90b8f809d67a4f53f9d40b9cdf2e085273c1ea96ccd036bd5df6b560dc46b2ba2cc2416
+  data.tar.gz: 70cc688ec5e59059663f879e024b72c69751519f430d1013d2a13361cca8b8ffb7e4471d55aa930f5aafa61a7205617fa7a6a10625b0cb78ef9bcdb835f38a6e

data/README.md

@@ -1,23 +1,290 @@
 # Convox Installer
 
+A Ruby gem that makes it easier to build a Convox installation script. This is like Chef/Ansible/Terraform for your initial Convox setup.
+
+## NOTE: This software is an alpha version
+
+Please note that the code quality is not very good, and the test coverage needs to be improved. However, I've successfully set up a number of test and production deployments using this gem, and everything seems to work very well. The library also facilitates idempotency and crash-resistance, so you can easily re-run your installation script if something goes wrong.
+
+## Features
+
+* Idempotent. If this script crashes, you can restart it and it will pick up
+  where it left off. Every step looks up the existing state, and only makes a change
+  if things are not yet set up (or out of sync).
+* Ensures that the `convox` and `aws` CLI tools are installed
+* Wraps the `convox` CLI and parses JSON output from API calls
+* Add n Docker Repository (e.g. ECR registry)
+* Set up an S3 bucket with an optional CORS policy
+
+## Introduction
+
 [Convox](https://convox.com/) is an awesome open source PaaS, which is like Heroku for your own AWS account. [`convox/rack`](https://github.com/convox/rack) is completely open source and free to use, but you can also sign up for a free or paid account to use the hosted service on convox.com.
 
 `convox_installer` is a Ruby gem that makes it much easier to build an installation script for `convox/rack` (the open source PaaS). The Convox CLI is awesome, but it's missing a nice way to script a full deployment. I originally wrote a bash script that made API calls and used [`jq`](https://stedolan.github.io/jq/) and `sed`, but this was very error-prone and it did not have good cross-platform support.
 
 I've rewritten this installation script in Ruby, which provides very good cross-platform support, and also allows me to write tests.
 
-# Usage
+## Usage
+
+Create a new Ruby file (e.g. `install.rb`), and use `bundler/inline` to install and require the `convox_installer` gem. Your install script should start like this:
+
+```ruby
+#!/usr/bin/env ruby
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'convox_installer'
+end
+
+require "convox_installer"
+include ConvoxInstaller
+```
+
+Including the `include ConvoxInstaller` gives you some Ruby methods that you can call to construct an installation workflow. See the "`ConvoxInstaller` DSL" section below.
 
-You should create a new git repo for your own installation script, and then use the provided classes and methods to build your own installation workflow. You must also include a `convox.yml`.
+You should create a new git repo for your own installation script, and then use the provided classes and methods to build your own installation workflow. You must also include a `convox.yml` (or a `convox.example.yml`).
 
-You can see an example in [`examples/full_installation.rb`](./examples/full_installation.rb).
-(This Ruby file uses `bundler/inline`, so it will download and install the `convox_installer` gem before running the script.)
+You can see a complete example in [`examples/full_installation.rb`](./examples/full_installation.rb).
 
-# Config
+
+## Config
 
 Config is loaded from ENV vars, or from saved JSON data at
-`~/.convox/installer_config`.
+`~/.convox/installer_config`. The script will save all of the user's responses into `~/.convox/installer_config`.
+
+## Customize the Config Prompts
+
+You can set your own config prompts in your own installation script, by setting a `@prompts` instance variable. You can extend the default config prompts like this:
+
+```ruby
+@prompts = ConvoxInstaller::Config::DEFAULT_PROMPTS + [
+  {
+    section: "Docker Authentication",
+    info: "You should have received authentication details for the Docker Registry\n" \
+    "via email. If not, please contact support@example.com",
+  },
+  {
+    key: :docker_registry_url,
+    title: "Docker Registry URL",
+    value: "1234567890.dkr.ecr.us-east-1.amazonaws.com",
+  },
+  {
+    key: :docker_registry_username,
+    title: "Docker Registry Username",
+  },
+  {
+    key: :docker_registry_password,
+    title: "Docker Registry Password",
+  }
+]
+```
+
+## Prompt API:
+
+The `@prompts` variable must be an array of hashes. There are two kinds of hashes:
+
+#### Section Heading
+
+Shows a heading and optional details.
+
+```ruby
+{
+  section: "The heading for this config section",
+  info: "Description about this config section"
+}
+```
+
+#### Config Prompt
+
+* A config prompt with a default value:
+
+```ruby
+{
+  key: :config_key_name,
+  title: "Title to show in the user prompt / config summary",
+  prompt: "Question to show the user",
+  default: "default value",
+}
+```
+
+* Set a value from a `Proc`, and don't prompt the user:
+
+```ruby
+  {
+    key: :config_key_name,
+    title: "Title to show in the config summary",
+    value: -> () { "string-with-random-suffix-#{SecureRandom.hex(4)}" },
+  }
+```
+
+* Set a value, and hide this setting from the user (even in the summary):
+
+```ruby
+  {
+    key: :config_key_name,
+    value: "Config Value",
+    hidden: true,
+  },
+```
+
+
+## `ConvoxInstaller` DSL
+
+#### `ensure_requirements!`
+
+Makes sure that the `convox` and `aws` CLI tools are installed on this system. If not, shows installation instructions and exits.
+
+#### `prompt_for_config`
+
+Loads config from ENV vars, or from saved config at `~/.convox/installer_config`.
+If any config settings are missing, it prompts the user for input. Finally, it shows a summary of the config, and asks the user if they want to proceed with the installation. If the user enters `y` (or `yes`), the `prompt_for_config` method completes. If they enter `n` (or `no`), we loop over every setting and let them press "enter" to keep the current value, or provide a new value to correct any mistakes.
+
+#### `backup_convox_host_and_rack`
+
+If there are any existing files at `~/.convox/host` or `~/.convox/rack`, this method moves these to `~/.convox/host.bak` and `~/.convox/rack.bak`.
+
+#### `install_convox`
+
+* **Required Config:** `aws_region`, `aws_access_key_id`, `aws_secret_access_key`,
+  `stack_name`, `instance_type`
+
+Runs `convox rack install ...`. Has some validations to ensure that all required settings are present.
+
+#### `validate_convox_auth_and_set_host!`
+
+After running `install_convox`, call this method to ensure that the the `~/.convox/auth` file has been updated with the correct details (checks the rack name and AWS region.) Then it sets the rack host in `~/.convox/host` (if not already set.)
+
+#### `validate_convox_rack!`
+
+Calls `convox api get /system` to get the Rack details, then makes sure that everything is correct.
+
+#### `convox_rack_data`
+
+Returns a Ruby hash with all convox rack data.
+
+#### `create_convox_app!`
+
+* **Required Config:** `convox_app_name`
+
+Checks if the app already exists. If not, calls `convox apps create ... --wait` to create a new app. Then waits for the app to be ready. (Avoids an occasional race condition.)
+
+
+#### `set_default_app_for_directory!`
+
+Writes the app name into `./.convox/app` (in the current directory.) The `convox` CLI reads this file, so you don't need to specify the `--app` flag for future commands.
+
+
+#### `create_s3_bucket!`
+
+* **Required Config:** `s3_bucket_name`
+
+Creates an S3 bucket from the `:s3_bucket_name` config setting. This is not a default setting, so you can add something like this to your custom `@prompts`:
+
+```ruby
+  {
+    key: :s3_bucket_name,
+    title: "S3 Bucket for uploads",
+    value: -> () { "yourapp-uploads-#{SecureRandom.hex(4)}" },
+  }
+```
+
+The `:value` `Proc` will generate a bucket name with a random suffix. (Avoids conflicts when you are setting up multiple deployments for your app.)
+
+`create_s3_bucket!` will also call `set_s3_bucket_cors_policy` automatically, so you don't need to call this manually.
+
+#### `set_s3_bucket_cors_policy`
+
+* **Required Config:** `s3_bucket_name`
+
+Set up a CORS policy for your S3 bucket. (`:s3_bucket_name`)
+
+*Note: If the `:s3_bucket_cors_policy` setting is not provided, then this method does nothing.*
+
+You should set `:s3_bucket_cors_policy` to a JSON string. Here's how I set this up in my own `install.rb` script:
+
+```ruby
+S3_BUCKET_CORS_POLICY = <<-JSON
+{
+  "CORSRules": [
+    {
+      "AllowedOrigins": ["*"],
+      "AllowedHeaders": ["Authorization", "cache-control", "x-requested-with"],
+      "AllowedMethods": ["PUT", "POST", "GET"],
+      "MaxAgeSeconds": 3000
+    }
+  ]
+}
+JSON
+
+@prompts = [
+  {
+    key: :s3_bucket_cors_policy,
+    value: S3_BUCKET_CORS_POLICY,
+    hidden: true,
+  }
+]
+```
+
+
+#### `s3_bucket_details`
+
+* **Required Config:** `s3_bucket_name`
+
+Get the S3 bucket details for `s3_bucket_name`. Parses the URL and returns a hash:
+
+```ruby
+{
+  access_key_id: "AWS Access Key ID",
+  secret_access_key: "AWS Secret Access Key",
+  name: "Full S3 Bucket Name (includes the rack/app)",
+}
+```
+
+I use these S3 bucket details to set env variables for my app. (`convox env set ...`)
+
+
+#### `add_docker_registry!`
+
+* **Required Config:** `docker_registry_url`, `docker_registry_username`, `docker_registry_password`
+
+Checks the list of registries to see if `docker_registry_url` has already been added. If not, runs `convox registries add ...` to add a new Docker registry (e.g. Docker Hub, ECR).
+
+#### `default_service_domain_name`
+
+* **Required Config:** `convox_app_name`, `default_service`
+
+Parses the rack router ELB name and region, and returns the default `convox.site` domain for your default service. (You can visit this URL in the browser to access your app.)
+
+Example: `myapp-web.rackname-Route-ABCDFE123456-123456789.us-west-2.convox.site`
+
+Set a default service in your config prompts (e.g. `web`):
+
+```ruby
+@prompts = [
+  # ...
+  {
+    key: :default_service,
+    title: "Default Convox Service (for domain)",
+    value: "web",
+    hidden: true,
+  }
+]
+```
+
+> (This hidden setting isn't visible to the user.)
+
+#### `run_convox_command!(cmd)`
+
+Runs a `convox` CLI command, and shows all output in the terminal. Crashes the script with an error if the `convox` command has a non-zero exit code.
+
+If you want to run `convox env set MYVAR=value`, then you would call:
+
+```ruby
+run_convox_command! 'env set MYVAR=value'
+```
+
 
-### License
+## License
 
 [MIT](./LICENSE)

data/examples/full_installation.rb

@@ -35,7 +35,7 @@ JSON
 
 @prompts = ConvoxInstaller::Config::DEFAULT_PROMPTS + [
   {
-    section: "ECR Authentication",
+    section: "Docker Registry Authentication",
     info: "You should have received authentication details for the Docker Registry\n" \
     "via email. If not, please contact support@example.com",
   },
@@ -114,8 +114,8 @@ puts "=> Setting environment variables to configure the application..."
 env = {
   "HEALTH_CHECK_PATH" => MINIMAL_HEALTH_CHECK_PATH,
   "DOMAIN_NAME" => default_service_domain_name,
-  "AWS_ACCESS_KEY_ID" => config.fetch(:aws_access_key_id),
-  "AWS_ACCESS_KEY_SECRET" => config.fetch(:aws_secret_access_key),
+  "AWS_ACCESS_KEY_ID" => s3_bucket_details.fetch(:access_key_id),
+  "AWS_ACCESS_KEY_SECRET" => s3_bucket_details.fetch(:secret_access_key),
   "AWS_UPLOADS_S3_BUCKET" => s3_bucket_details.fetch(:name),
   "AWS_UPLOADS_S3_REGION" => config.fetch(:aws_region),
   "SECRET_KEY_BASE" => secret_key_base,

data/lib/convox/client.rb

@@ -390,7 +390,11 @@ module Convox
     def load_auth_from_file
       return {} unless File.exist?(AUTH_FILE)
 
-      JSON.parse(File.read(AUTH_FILE))
+      begin
+        JSON.parse(File.read(AUTH_FILE))
+      rescue
+        {}
+      end
     end
 
     def require_config(required_keys)

data/lib/convox_installer.rb

@@ -34,13 +34,13 @@ module ConvoxInstaller
     install_convox
     validate_convox_auth_and_set_host!
     validate_convox_rack!
+    convox_rack_data
     create_convox_app!
     set_default_app_for_directory!
     create_s3_bucket!
     set_s3_bucket_cors_policy
-    add_docker_registry!
     s3_bucket_details
-    convox_rack_data
+    add_docker_registry!
     default_service_domain_name
     run_convox_command!
   ].each do |method|

data/lib/convox_installer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConvoxInstaller
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/spec/lib/convox/client_spec.rb

@@ -39,8 +39,8 @@ RSpec.describe Convox::Client do
       client = described_class.new
       expect { client.install_convox }.to raise_error("aws_region is missing from the config!")
 
-      client = described_class.new(config: {aws_region: "asdf"})
-      expect { client.install_convox }.to raise_error("aws_access_key_id is missing from the config!")
+      client = described_class.new(config: {aws_region: "us-east-1"})
+      expect { client.install_convox }.to raise_error("stack_name is missing from the config!")
     end
 
     it "should run the correct convox CLI command" do

data/spec/lib/convox_installer/config_spec.rb

@@ -40,7 +40,21 @@ RSpec.describe ConvoxInstaller::Config do
     output = StringIO.new
     highline = HighLine.new(input, output)
 
-    input << "\nus-north-12\nasdf\nxkcd\n\nn\nconvox-test\n\nsdfg\n\n\ny\n"
+    input_details = [
+      [:stack_name, ""],
+      [:aws_region, ""],
+      [:instance_type, "c5.xlarge"],
+      [:aws_access_key_id, "asdf"],
+      [:aws_secret_access_key, "xkcd"],
+      [:confirm?, "n"],
+      [:stack_name, "convox-test"],
+      [:aws_region, "us-north-12"],
+      [:instance_type, "t3.medium"],
+      [:aws_access_key_id, "sdfg"],
+      [:aws_secret_access_key, ""],
+      [:confirm?, "y"],
+    ]
+    input << input_details.map(&:last).join("\n") << "\n"
     input.rewind
 
     config = described_class.new(highline: highline)
@@ -50,8 +64,8 @@ RSpec.describe ConvoxInstaller::Config do
     config.prompt_for_config
     expect(config.config).to eq(
       :stack_name => "convox-test",
-      :aws_access_key_id => "sdfg",
       :aws_region => "us-north-12",
+      :aws_access_key_id => "sdfg",
       :aws_secret_access_key => "xkcd",
       :instance_type => "t3.medium",
     )
@@ -59,20 +73,20 @@ RSpec.describe ConvoxInstaller::Config do
     stripped_output = output.read.lines.map(&:rstrip).join("\n")
     expected_output = <<-EOS
 Please enter a name for your Convox installation  |convox|
-Please enter your AWS Region: |us-east-1|
+Please enter your AWS Region: |us-east-1| Please enter your EC2 Instance Type: |t3.medium|
 Admin AWS Credentials
 ============================================
 
-Please enter your AWS Access Key ID: Please enter your AWS Secret Access Key: Please enter your EC2 Instance Type: |t3.medium|
+Please enter your AWS Access Key ID: Please enter your AWS Secret Access Key:
 ============================================
                  SUMMARY
 ============================================
 
     Convox Stack Name:       convox
-    AWS Region:              us-north-12
+    AWS Region:              us-east-1
+    EC2 Instance Type:       c5.xlarge
     AWS Access Key ID:       asdf
     AWS Secret Access Key:   xkcd
-    EC2 Instance Type:       t3.medium
 
 We've saved your configuration to: /Users/ndbroadbent/.convox/installer_config
 If anything goes wrong during the installation, you can restart the script to reload the config and continue.
@@ -81,20 +95,20 @@ Please double check all of these configuration details.
 Would you like to start the Convox installation? (press 'n' to correct any settings)
 
 Please enter a name for your Convox installation  |convox|
-Please enter your AWS Region: |us-north-12|
+Please enter your AWS Region: |us-east-1| Please enter your EC2 Instance Type: |c5.xlarge|
 Admin AWS Credentials
 ============================================
 
-Please enter your AWS Access Key ID: |asdf| Please enter your AWS Secret Access Key: |xkcd| Please enter your EC2 Instance Type: |t3.medium|
+Please enter your AWS Access Key ID: |asdf| Please enter your AWS Secret Access Key: |xkcd|
 ============================================
                  SUMMARY
 ============================================
 
     Convox Stack Name:       convox-test
     AWS Region:              us-north-12
+    EC2 Instance Type:       t3.medium
     AWS Access Key ID:       sdfg
     AWS Secret Access Key:   xkcd
-    EC2 Instance Type:       t3.medium
 
 We've saved your configuration to: /Users/ndbroadbent/.convox/installer_config
 If anything goes wrong during the installation, you can restart the script to reload the config and continue.
@@ -143,11 +157,22 @@ EOS
       },
     ]
 
-    input << "\n\nasdf\nxkcd\n\nsdfg\nqwer\n\ny\n"
+    input_details = [
+      [:stack_name, ""],
+      [:aws_region, ""],
+      [:instance_type, "c5.xlarge"],
+      [:aws_access_key_id, "asdf"],
+      [:aws_secret_access_key, "xkcd"],
+      [:docker_registry_username, "bob"],
+      [:docker_registry_password, "password1"],
+      [:admin_email, "admin@test.com"],
+      [:confirm?, "y"],
+    ]
+    input << input_details.map(&:last).join("\n") << "\n"
     input.rewind
 
     config = described_class.new(highline: highline, prompts: custom_prompts)
-    expect(config).to receive(:save_config_to_file).exactly(8).times
+    expect(config).to receive(:save_config_to_file).exactly(9).times
     expect(SecureRandom).to receive(:hex).with(8).and_return("99a6f67de0c7a117")
 
     expect(config.config).to eq({})
@@ -159,21 +184,21 @@ EOS
       :aws_region => "us-east-1",
       :aws_access_key_id => "asdf",
       :aws_secret_access_key => "xkcd",
-      :instance_type => "t3.medium",
-      :docker_registry_username => "sdfg",
-      :docker_registry_password => "qwer",
-      :admin_email => "admin@example.com",
+      :instance_type => "c5.xlarge",
+      :docker_registry_username => "bob",
+      :docker_registry_password => "password1",
+      :admin_email => "admin@test.com",
       :admin_password => "99a6f67de0c7a117",
     )
     output.rewind
     stripped_output = output.read.lines.map(&:rstrip).join("\n")
     expected_output = <<-EOS
 Please enter a name for your Convox installation  |convox|
-Please enter your AWS Region: |us-east-1|
+Please enter your AWS Region: |us-east-1| Please enter your EC2 Instance Type: |t3.medium|
 Admin AWS Credentials
 ============================================
 
-Please enter your AWS Access Key ID: Please enter your AWS Secret Access Key: Please enter your EC2 Instance Type: |t3.medium|
+Please enter your AWS Access Key ID: Please enter your AWS Secret Access Key:
 ECR Authentication
 ============================================
 
@@ -185,12 +210,12 @@ Please enter your Docker Registry Access Key ID: Please enter your Docker Regist
 
     Convox Stack Name:                   convox
     AWS Region:                          us-east-1
+    EC2 Instance Type:                   c5.xlarge
     AWS Access Key ID:                   asdf
     AWS Secret Access Key:               xkcd
-    EC2 Instance Type:                   t3.medium
-    Docker Registry Access Key ID:       sdfg
-    Docker Registry Secret Access Key:   qwer
-    Admin Email:                         admin@example.com
+    Docker Registry Access Key ID:       bob
+    Docker Registry Secret Access Key:   password1
+    Admin Email:                         admin@test.com
     Admin Password:                      99a6f67de0c7a117
 
 We've saved your configuration to: /Users/ndbroadbent/.convox/installer_config

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: convox_installer
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Form Applications Inc.
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-05-08 00:00:00.000000000 Z
+date: 2021-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -113,7 +113,7 @@ homepage: https://github.com/FormAPI/convox_installer
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -128,9 +128,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.8
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: Build a Convox installation workflow
 test_files: