README.md in convox_installer-1.0.3 vs README.md in convox_installer-1.0.4

- old
+ new

@@ -6,17 +6,17 @@ 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 +- 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 +- 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. @@ -45,15 +45,14 @@ 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 a complete example in [`examples/full_installation.rb`](./examples/full_installation.rb). - ## Config Config is loaded from ENV vars, or from saved JSON data at -`~/.convox/installer_config`. The script will save all of the user's responses into `~/.convox/installer_config`. +`./.installer_config`. The script will save all of the user's responses into `./.installer_config` (in the current directory). ## 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: @@ -95,60 +94,59 @@ } ``` #### Config Prompt -* A config prompt with a default value: +- 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: +- 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): +- 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`. +Loads config from ENV vars, or from saved config at `./.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`, +- **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!` @@ -163,23 +161,21 @@ Returns a Ruby hash with all convox rack data. #### `create_convox_app!` -* **Required Config:** `convox_app_name` +- **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` +- **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 { @@ -193,15 +189,15 @@ `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` +- **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.* +_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 @@ -224,14 +220,13 @@ hidden: true, } ] ``` - #### `s3_bucket_details` -* **Required Config:** `s3_bucket_name` +- **Required Config:** `s3_bucket_name` Get the S3 bucket details for `s3_bucket_name`. Parses the URL and returns a hash: ```ruby { @@ -241,20 +236,19 @@ } ``` 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` +- **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` +- **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` @@ -281,10 +275,9 @@ If you want to run `convox env set MYVAR=value`, then you would call: ```ruby run_convox_command! 'env set MYVAR=value' ``` - ## License [MIT](./LICENSE)