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)