Convox Installer

A Ruby gem that makes it easier to build a Convox installation script. The main purpose of this gem is to make it easier to set up on-premise installations of your app for enterprise users.

This gem provides a DSL so that you can write a script that walks your users through setting up Convox and getting your app and running, setting up S3 buckets, etc.

• MacOS
• Convox v3 CLI

Please let us know if you need to run this script on Linux. Linux support should not be too difficult to implement, but unfortunately we probably won't be able to support Windows.

This version of convox_installer is only designed to work with Convox 3 and later. You can run convox version to check your version. Please install the Convox v3 CLI by following the instructions here: https://docs.convox.com/getting-started/introduction/

If you want to set up a Convox v2 rack (deprecated), the last version of convox_installer that supports the v2 CLI is 1.0.9. (Take a look at the convox2 branch.)

We have successfully set up a number of test and production deployments using this gem. 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. However, if anything goes wrong, then you can end up with a large AWS bill if you're not careful. If anything crashes then make sure you double-check everything in your AWS account and shut down any leftover resources. USE THIS SOFTWARE AT YOUR OWN RISK.

• 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 terraform CLI tools are installed
• Wraps the convox CLI and parses JSON output from API calls
• Add a Docker Repository (e.g. ECR registry)
• Set up an S3 bucket with an optional CORS policy
• Set up an RDS database (Postgres)
• Set up an Elasticache cluster (Redis)

Convox is an awesome open source PaaS, which is like Heroku for your own AWS account. 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 and sed, but this was very error-prone and it did not have good cross-platform support.

I've written this installation script in Ruby, which provides very good cross-platform support, and also allows me to write tests.

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:

#!/usr/bin/env ruby
require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'convox_installer', '3.0.0'
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 (or a convox.example.yml).

You can see a complete example in examples/full_installation.rb.

Config is loaded from ENV vars, or from saved JSON data at ./.installer_config.json. The script will save all of the user's responses into ./.installer_config.json (in the current directory).

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:

@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",
  }
]

The @prompts variable must be an array of hashes. There are two kinds of hashes:

Shows a heading and optional details.

{
  section: "The heading for this config section",
  info: "Description about this config section"
}

• A config prompt with a default value:

{
  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:

  {
    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):

  {
    key: :config_key_name,
    value: "Config Value",
    hidden: true,
  },

Makes sure that the convox and terraform CLI tools are installed on this system. If not, shows installation instructions and exits.

Loads config from ENV vars, or from saved config at ./.installer_config.json. 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.

• 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.

Ensures that the local machine contains a directory for the rack's terraform config, and sets the current rack for Convox CLI commands.

Makes an API request (convox api get /system) to get the rack details, and makes sure that everything is correct.

Returns a Ruby hash with all convox rack data.

• 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.)

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.

Adds an S3 bucket to your Terraform config.

• Required Config: s3_bucket_name

NOTE: This method just writes a new Terraform configuration file. You must run apply_terraform_update! to apply the changes and create the S3 bucket.

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:

  {
    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.)

You can also set a CORS policy for your S3 bucket. (:s3_bucket_name) We set the cors_rule option for the aws_s3_bucket resource in the Terraform configuration. Example:

   cors_rule {
    allowed_headers = ["*"]
    allowed_methods = ["PUT", "POST"]
    allowed_origins = ["https://s3-website-test.hashicorp.com"]
    expose_headers  = ["ETag"]
    max_age_seconds = 3000
  }

See: https://registry.terraform.io/providers/hashicorp/aws/3.33.0/docs/resources/s3_bucket#using-cors

Note: If the :s3_bucket_cors_rule setting is not provided, then it is skipped.

Here's how we set up a CORS policy in our own install.rb script:

xxxxc = <<-TERRAFORM
  cors_rule {
    allowed_headers = ["Authorization", "cache-control", "x-requested-with"]
    allowed_methods = ["PUT", "POST", "GET"]
    allowed_origins = ["*"]
    expose_headers  = []
    max_age_seconds = 3000
  }
TERRAFORM

@prompts = [
  {
    key: :s3_bucket_cors_rule,
    value: S3_BUCKET_CORS_RULE,
    hidden: true,
  }
]

Adds an RDS database to your Terraform config.

• Required Config:
  • database_username
  • database_password
• Optional Config:
  • database_allocated_storage (default: 30)
  • database_engine (default: 'postgres')
  • database_engine_version (default: '15.7')
  • database_instance_class (default: 'db.t3.small')
  • database_multi_az (default: true)

Adds an Elasticache cluster to your Terraform config.

• Optional Config:
  • engine (default: 'redis')
  • engine_version (default: '7.1')
  • node_type (default: 'cache.t3.medium')
  • num_cache_nodes (default: 1)
  • port (default: 6379)

Runs terraform apply -auto-approve to apply any changes to your Terraform configuration (add new resources, etc.)

Returns information about the created RDS database resource.

{
  postgres_url: "Full URL for the RDS database (including auth)",
}

Returns information about the created RDS database resource.

{
  redis_url: "Full URL for the Redis cluster",
}

• Required Config: s3_bucket_name

Get the S3 bucket details for s3_bucket_name. Parses the URL and returns a hash:

{
  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 ...)

• 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).

• Required Config: convox_app_name
• Optional Config: default_service

Finds the default *.convox.cloud URL for the web service. (You can visit this URL in the browser to access your app.)

Example: web.docspring.dc6bae48c2e36366.convox.cloud

You can override the default service name in your config (e.g. web):

@prompts = [
  # ...
  {
    key: :default_service,
    title: "Default Convox Service (for domain)",
    value: "web",
    hidden: true,
  }
]

(This hidden setting isn't visible to the user.)

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:

run_convox_command! 'env set MYVAR=value'

MIT