{"id":19383902,"url":"https://github.com/docspring/convox_installer","last_synced_at":"2026-06-11T22:31:13.919Z","repository":{"id":42507044,"uuid":"185372963","full_name":"DocSpring/convox_installer","owner":"DocSpring","description":"A Ruby library that makes it easy to install Convox and set up AWS resources","archived":false,"fork":false,"pushed_at":"2023-06-13T05:01:32.000Z","size":127,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-03-15T00:22:52.817Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DocSpring.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-07T09:48:22.000Z","updated_at":"2021-11-12T05:23:00.000Z","dependencies_parsed_at":"2024-11-10T09:28:24.777Z","dependency_job_id":"d4e6aa6f-1fe5-4caf-a34f-0fd1315d1f6e","html_url":"https://github.com/DocSpring/convox_installer","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocSpring%2Fconvox_installer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocSpring%2Fconvox_installer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocSpring%2Fconvox_installer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocSpring%2Fconvox_installer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DocSpring","download_url":"https://codeload.github.com/DocSpring/convox_installer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240521037,"owners_count":19814694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T09:28:19.696Z","updated_at":"2026-06-11T22:31:13.891Z","avatar_url":"https://github.com/DocSpring.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Convox Installer\n\nA 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.\n\nThis 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.\n\n## Requirements\n\n- MacOS\n- Convox v3 CLI\n\n_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._\n\n### Requires Convox \u003e= 3\n\nThis 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/\n\n_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](https://github.com/DocSpring/convox_installer/tree/convox2).)_\n\n## USE AT YOUR OWN RISK! THIS CODE IS PROVIDED WITHOUT ANY WARRANTIES OR GUARANTEES\n\nWe 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.**\n\n## Features\n\n- Idempotent. If this script crashes, you can restart it and it will pick up\n  where it left off. Every step looks up the existing state, and only makes a change\n  if things are not yet set up (or out of sync).\n- Ensures that the `convox` and `terraform` CLI tools are installed\n- Wraps the `convox` CLI and parses JSON output from API calls\n- Add a Docker Repository (e.g. ECR registry)\n- Set up an S3 bucket with an optional CORS policy\n- Set up an RDS database (Postgres)\n- Set up an Elasticache cluster (Redis)\n\n## Introduction\n\n[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.\n\n`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.\n\nI've written this installation script in Ruby, which provides very good cross-platform support, and also allows me to write tests.\n\n## Usage\n\nCreate 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:\n\n```ruby\n#!/usr/bin/env ruby\nrequire 'bundler/inline'\n\ngemfile do\n  source 'https://rubygems.org'\n  gem 'convox_installer', '3.0.0'\nend\n\nrequire \"convox_installer\"\ninclude ConvoxInstaller\n```\n\nIncluding the `include ConvoxInstaller` gives you some Ruby methods that you can call to construct an installation workflow. See the \"`ConvoxInstaller` DSL\" section below.\n\nYou 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`).\n\nYou can see a complete example in [`examples/full_installation.rb`](./examples/full_installation.rb).\n\n## Config\n\nConfig is loaded from ENV vars, or from saved JSON data at\n`./.installer_config.json`. The script will save all of the user's responses into `./.installer_config.json` (in the current directory).\n\n## Customize the Config Prompts\n\nYou 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:\n\n```ruby\n@prompts = ConvoxInstaller::Config::DEFAULT_PROMPTS + [\n  {\n    section: \"Docker Authentication\",\n    info: \"You should have received authentication details for the Docker Registry\\n\" \\\n    \"via email. If not, please contact support@example.com\",\n  },\n  {\n    key: :docker_registry_url,\n    title: \"Docker Registry URL\",\n    value: \"1234567890.dkr.ecr.us-east-1.amazonaws.com\",\n  },\n  {\n    key: :docker_registry_username,\n    title: \"Docker Registry Username\",\n  },\n  {\n    key: :docker_registry_password,\n    title: \"Docker Registry Password\",\n  }\n]\n```\n\n## Prompt API:\n\nThe `@prompts` variable must be an array of hashes. There are two kinds of hashes:\n\n#### Section Heading\n\nShows a heading and optional details.\n\n```ruby\n{\n  section: \"The heading for this config section\",\n  info: \"Description about this config section\"\n}\n```\n\n#### Config Prompt\n\n- A config prompt with a default value:\n\n```ruby\n{\n  key: :config_key_name,\n  title: \"Title to show in the user prompt / config summary\",\n  prompt: \"Question to show the user\",\n  default: \"default value\",\n}\n```\n\n- Set a value from a `Proc`, and don't prompt the user:\n\n```ruby\n  {\n    key: :config_key_name,\n    title: \"Title to show in the config summary\",\n    value: -\u003e () { \"string-with-random-suffix-#{SecureRandom.hex(4)}\" },\n  }\n```\n\n- Set a value, and hide this setting from the user (even in the summary):\n\n```ruby\n  {\n    key: :config_key_name,\n    value: \"Config Value\",\n    hidden: true,\n  },\n```\n\n## `ConvoxInstaller` DSL\n\n#### `ensure_requirements!`\n\nMakes sure that the `convox` and `terraform` CLI tools are installed on this system. If not, shows installation instructions and exits.\n\n#### `prompt_for_config`\n\nLoads config from ENV vars, or from saved config at `./.installer_config.json`.\nIf 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.\n\n#### `install_convox`\n\n- **Required Config:** `aws_region`, `aws_access_key_id`, `aws_secret_access_key`,\n  `stack_name`, `instance_type`\n\nRuns `convox rack install ...`. Has some validations to ensure that all required settings are present.\n\n#### `validate_convox_rack_and_write_current!`\n\nEnsures that the local machine contains a directory for the rack's terraform config, and sets the current rack for Convox CLI commands.\n\n#### `validate_convox_rack_api!`\n\nMakes an API request (`convox api get /system`) to get the rack details, and makes sure that everything is correct.\n\n#### `convox_rack_data`\n\nReturns a Ruby hash with all convox rack data.\n\n#### `create_convox_app!`\n\n- **Required Config:** `convox_app_name`\n\nChecks 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.)\n\n#### `set_default_app_for_directory!`\n\nWrites 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.\n\n#### `add_s3_bucket`\n\nAdds an S3 bucket to your Terraform config.\n\n- **Required Config:** `s3_bucket_name`\n\nNOTE: This method just writes a new Terraform configuration file. You must run `apply_terraform_update!` to apply the changes and create the S3 bucket.\n\nCreates 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`:\n\n```ruby\n  {\n    key: :s3_bucket_name,\n    title: \"S3 Bucket for uploads\",\n    value: -\u003e () { \"yourapp-uploads-#{SecureRandom.hex(4)}\" },\n  }\n```\n\nThe `:value` `Proc` will generate a bucket name with a random suffix. (Avoids conflicts when you are setting up multiple deployments for your app.)\n\nYou can also set a CORS policy for your S3 bucket. (`:s3_bucket_name`)\nWe set the `cors_rule` option for the `aws_s3_bucket` resource in the Terraform configuration. Example:\n\n```\n   cors_rule {\n    allowed_headers = [\"*\"]\n    allowed_methods = [\"PUT\", \"POST\"]\n    allowed_origins = [\"https://s3-website-test.hashicorp.com\"]\n    expose_headers  = [\"ETag\"]\n    max_age_seconds = 3000\n  }\n```\n\nSee: https://registry.terraform.io/providers/hashicorp/aws/3.33.0/docs/resources/s3_bucket#using-cors\n\n_Note: If the `:s3_bucket_cors_rule` setting is not provided, then it is skipped._\n\nHere's how we set up a CORS policy in our own `install.rb` script:\n\n```ruby\nxxxxc = \u003c\u003c-TERRAFORM\n  cors_rule {\n    allowed_headers = [\"Authorization\", \"cache-control\", \"x-requested-with\"]\n    allowed_methods = [\"PUT\", \"POST\", \"GET\"]\n    allowed_origins = [\"*\"]\n    expose_headers  = []\n    max_age_seconds = 3000\n  }\nTERRAFORM\n\n@prompts = [\n  {\n    key: :s3_bucket_cors_rule,\n    value: S3_BUCKET_CORS_RULE,\n    hidden: true,\n  }\n]\n```\n\n#### `add_rds_database`\n\nAdds an RDS database to your Terraform config.\n\n- **Required Config:**\n  - `database_username`\n  - `database_password`\n- **Optional Config:**\n  - `database_allocated_storage` _(default: 30)_\n  - `database_engine` _(default: 'postgres')_\n  - `database_engine_version` _(default: '15.7')_\n  - `database_instance_class` _(default: 'db.t3.small')_\n  - `database_multi_az` _(default: true)_\n\n#### `add_elasticache_cluster`\n\nAdds an Elasticache cluster to your Terraform config.\n\n- **Optional Config:**\n  - `engine` _(default: 'redis')_\n  - `engine_version` _(default: '7.1')_\n  - `node_type` _(default: 'cache.t3.medium')_\n  - `num_cache_nodes` _(default: 1)_\n  - `port` _(default: 6379)_\n\n#### `apply_terraform_update!`\n\nRuns `terraform apply -auto-approve` to apply any changes to your Terraform configuration (add new resources, etc.)\n\n#### `rds_details`\n\nReturns information about the created RDS database resource.\n\n```ruby\n{\n  postgres_url: \"Full URL for the RDS database (including auth)\",\n}\n```\n\n#### `elasticache_details`\n\nReturns information about the created RDS database resource.\n\n```ruby\n{\n  redis_url: \"Full URL for the Redis cluster\",\n}\n```\n\n#### `s3_bucket_details`\n\n- **Required Config:** `s3_bucket_name`\n\nGet the S3 bucket details for `s3_bucket_name`. Parses the URL and returns a hash:\n\n```ruby\n{\n  access_key_id: \"AWS Access Key ID\",\n  secret_access_key: \"AWS Secret Access Key\",\n  name: \"Full S3 Bucket Name (includes the rack/app)\",\n}\n```\n\nI use these S3 bucket details to set env variables for my app. (`convox env set ...`)\n\n#### `add_docker_registry!`\n\n- **Required Config:** `docker_registry_url`, `docker_registry_username`, `docker_registry_password`\n\nChecks 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).\n\n#### `default_service_domain_name`\n\n- **Required Config:** `convox_app_name`\n- **Optional Config:** `default_service`\n\nFinds the default `*.convox.cloud` URL for the web service. (You can visit this URL in the browser to access your app.)\n\nExample: `web.docspring.dc6bae48c2e36366.convox.cloud`\n\nYou can override the default service name in your config (e.g. `web`):\n\n```ruby\n@prompts = [\n  # ...\n  {\n    key: :default_service,\n    title: \"Default Convox Service (for domain)\",\n    value: \"web\",\n    hidden: true,\n  }\n]\n```\n\n\u003e (This hidden setting isn't visible to the user.)\n\n#### `run_convox_command!(cmd)`\n\nRuns 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.\n\nIf you want to run `convox env set MYVAR=value`, then you would call:\n\n```ruby\nrun_convox_command! 'env set MYVAR=value'\n```\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocspring%2Fconvox_installer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocspring%2Fconvox_installer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocspring%2Fconvox_installer/lists"}