{"id":13483616,"url":"https://github.com/eval/envied","last_synced_at":"2025-05-16T05:04:16.483Z","repository":{"id":14830438,"uuid":"17553221","full_name":"eval/envied","owner":"eval","description":"Ensures presence and type of your app's ENV-variables (mirror)","archived":false,"fork":false,"pushed_at":"2025-02-04T16:58:37.000Z","size":250,"stargazers_count":330,"open_issues_count":8,"forks_count":42,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-16T05:04:12.665Z","etag":null,"topics":["environment-variables","heroku","rails","ruby"],"latest_commit_sha":null,"homepage":"https://gitlab.com/envied/envied/tree/master#envied","language":"Ruby","has_issues":false,"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/eval.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2014-03-08T23:13:11.000Z","updated_at":"2025-02-04T16:58:40.000Z","dependencies_parsed_at":"2025-02-28T16:12:02.527Z","dependency_job_id":"364d9f97-8bc4-431c-b080-745c09452990","html_url":"https://github.com/eval/envied","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eval%2Fenvied","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eval%2Fenvied/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eval%2Fenvied/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eval%2Fenvied/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eval","download_url":"https://codeload.github.com/eval/envied/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471061,"owners_count":22076585,"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":["environment-variables","heroku","rails","ruby"],"created_at":"2024-07-31T17:01:13.348Z","updated_at":"2025-05-16T05:04:16.453Z","avatar_url":"https://github.com/eval.png","language":"Ruby","readme":"# ENVied\n\n## -- THIS PROJECT IS NO LONGER MAINTAINED --\nSee https://github.com/eval/nero for a modern replacement.\n\n\n### TL;DR ensure presence and type of your app's ENV-variables.\n\nFor the rationale behind this project, see this [blogpost](https://www.gertgoet.com/2014/10/14/envied-or-how-i-stopped-worrying-about-ruby-s-env.html).\n\n## Features\n\n* check for presence and correctness of ENV-variables\n* access to typed ENV-variables (integers, booleans etc. instead of just strings)\n* check the presence and correctness of a Heroku config\n\n## Non-features\n\n* provide or load ENV-values\n\n## Contents\n\n* [Quickstart](#quickstart)\n* [Installation](#installation)\n* [Configuration](#configuration)\n  * [Types](#types)\n  * [Key alias](#key-alias-unreleased)\n    * [env-type](#env-type-unreleased)\n  * [Groups](#groups)\n* [Command-line interface](#command-line-interface)\n* [Best Practices](#best-practices)\n* [FAQ](#faq)\n* [Testing](#testing)\n* [Development](#development)\n* [Contributing](#contributing)\n\n## Quickstart\n\n### 1) Configure\n\nAfter [successful installation](#installation), define some variables in `Envfile`:\n\n```ruby\n# file: Envfile\nvariable :FORCE_SSL, :boolean\nvariable :PORT, :integer\n```\n\n### 2) Check for presence and coercibility\n\n```ruby\n# during initialization\nENVied.require\n```\n\nThis will throw an error if:\n* one of `ENV['FORCE_SSL']`, `ENV['PORT']` is absent.\n* or: their values *cannot* be coerced (resp. to boolean and integer).\n\n### 3) Use coerced variables\n\nVariables accessed via ENVied are of the correct type:\n\n```ruby\nENVied.PORT # =\u003e 3001\nENVied.FORCE_SSL # =\u003e false\n```\n\n\u003c!--\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'envied'\n\n...then bundle:\n\n    $ bundle\n\n...then for Rails applications:\n\n    $ bundle exec envied init:rails\n\n...or for non-Rails applications:\n\n    $ bundle exec envied init\n\n    --\u003e\n\n## Configuration\n\n### Types\n\nThe following types are supported:\n\n* `:array` (e.g. 'tag1,tag2' becomes `['tag1', 'tag2']`)\n* `:boolean` (e.g. '0'/'1', 'f'/'t', 'false'/'true', 'off'/'on', 'no'/'yes' for resp. false and true)\n* `:date` (e.g. '2014-3-26')\n* `:env` (similar to `:string`, but accessible via ENV - see [Key alias](#key-alias-unreleased) for details)\n* `:float`\n* `:hash` (e.g. 'a=1\u0026b=2' becomes `{'a' =\u003e '1', 'b' =\u003e '2'}`)\n* `:integer`\n* `:string` (implied)\n* `:symbol`\n* `:time` (e.g. '14:00')\n* `:uri` (e.g. 'http://www.google.com' becomes result of `URI.parse('http://www.google.com')`)\n\n\n### Key alias (unreleased)\n\nBy default the value for variable `FOO` should be provided by `ENV['FOO']`. Sometimes though it's convenient to let a different key provide the value, based on some runtime condition. A key-alias will let you do this.  \n\nConsider for example local development where `REDIS_URL` differs between the development and test environment. Normally you'd prepare different shells with different values for `REDIS_URL`: one shell you can run tests in, and other shells where you'd run the console/server etc. This is cumbersome and easy to get wrong.\n\nWith a key alias that's calculated at runtime (e.g. `Rails.env`) you'd set values for both `REDIS_URL_TEST` and `REDIS_URL_DEVELOPMENT` and the right value will be used for test and development.\n\nFull example:\n```\n# file: Envfile\nkey_alias! { Rails.env }\n\nvariable :REDIS_URL, :uri\n```\n\nSource the following in your environment:\n```\n# file: .envrc\nexport REDIS_URL_DEVELOPMENT=redis://localhost:6379/0\nexport REDIS_URL_TEST=redis://localhost:6379/1\n```\nNow commands like `rails console` and `rails test` automatically point to the right redis database.\n\nNote that `ENV['REDIS_URL']` is still considered but `REDIS_URL_\u003ckey_alias\u003e` takes precedence.  \nAlso: any truthy value provided as key_alias is converted to an upcased string.  \nFinally: this setting is optional.\n\n\n#### env-type (unreleased)\n\nVariables of type `:env` take the key alias into account when accessing `ENV['FOO']`.\n\nSay, your application uses `ENV['DATABASE_URL']` (wich you can't change to `ENVied.DATABASE_URL`). Normally this would mean that the key alias has no effect. For env-type variables however, the key alias is taken into account:\n\n```\n# file: Envfile\n\nkey_alias! { Rails.env }\n\nvariable :DATABASE_URL, :env\n```\n\nThe following now works:\n```shell\n$ DATABASE_URL_DEVELOPMENT=postgres://localhost/blog_development rails runner \"p ENV['DATABASE_URL']\"\n\"postgres://localhost/blog_development\"\n```\n\nNote: this also works for `ENV.fetch('FOO')`.  \nAlso: no coercion is done (like you would expect when accessing ENV-values directly).  \n\nThis means that for Rails applications when you set values for `DATABASE_URL_DEVELOPMENT` and `DATABASE_URL_TEST`, you no longer need a `config/database.yml`.\n\n\n### Groups\n\nGroups give you more flexibility to define when variables are needed.\nIt's similar to groups in a Gemfile:\n\n```ruby\n# file: Envfile\nvariable :FORCE_SSL, :boolean\n\ngroup :production do\n  variable :SECRET_KEY_BASE\nend\n\ngroup :development, :staging do\n  variable :DEV_KEY\nend\n```\n\n```ruby\n# For local development you would typically do:\nENVied.require(:default) #=\u003e Only ENV['FORCE_SSL'] is required\n# On the production server:\nENVied.require(:default, :production) #=\u003e ...also ENV['SECRET_KEY_BASE'] is required\n\n# You can also pass it a string with the groups separated by comma's:\nENVied.require('default, production')\n\n# This allows for easily requiring groups using the ENV:\nENVied.require(ENV['ENVIED_GROUPS'])\n# ...then from the prompt:\n$ ENVIED_GROUPS='default,production' bin/rails server\n\n# BTW the following are equivalent:\nENVied.require\nENVied.require(:default)\nENVied.require('default')\nENVied.require(nil)\n```\n\n## Command-line interface\n\nFor help on a specific command, use `envied help \u003ccommand\u003e`.\n\n```bash\n$ envied help\nCommands:\n  envied check                   # Checks whether you environment contains required variables\n  envied check:heroku            # Checks whether a Heroku config contains required variables\n  envied check:heroku:binstub    # Generates a shell script for the check:heroku-task\n  envied extract                 # Grep code to find ENV-variables\n  envied help [COMMAND]          # Describe available commands or one specific command\n  envied init                    # Generates a default Envfile in the current working directory\n  envied init:rails              # Generate all files needed for a Rails project\n  envied version, --version, -v  # Shows version number\n```\n\n## Best Practices\n\nSome best practices when using ENVied or working with env-configurable applications in general.\n\n### include a .envrc.sample\n\nWhile ENVied will warn you when you start an application that is 'under-configured', it won't tell users what good default values are. To solve this add a file to the root of your project that contains sane defaults and instructions:\n```\n# file: .envrc.sample\n# copy this file to .envrc and adjust values if needed\n# then do `source .envrc` to load\n\nexport DATABASE_URL=postgres://localhost/blog_development\n# export FORCE_SSL=true # only needed for production\n\n# you can find this token on the Heroku-dashboard\nexport DEPLOY_TOKEN=1234-ABC-5678\n```\n\n### let [direnv](https://direnv.net/) manage your environment\n\n[direnv](https://direnv.net/) will auto-(un)load values from `.envrc` when you switch folders.  \n\nAs a bonus it has some powerful commands in it's [stdlib](https://direnv.net/#man/direnv-stdlib.1).  \nFor example:\n```\n# this adds the project's bin-folder to $PATH\nPATH_add bin\n# so instead of `./bin/rails -h` you can do `rails -h` from anywhere (deep) in the project\n\n# the following will use the .envrc.sample as a basis\n# when new variables are introduced upstream, you'll automatically use these defaults\nif [ -f .envrc.sample ]; then\n  source_env .envrc.sample\nfi\n...your overrides\n\n# a variant of this is source_up\n# an .envrc in a subfolder can load the .envrc from the root of the project and override specific values\n# this would allow e.g. for a specific test-environment in the subfolder:\n# in my-project/test/.envrc\nsource_up .envrc\nexport DATABASE_URL=the-test-db-url\n```\n\n\n## FAQ\n\n### How to find all ENV-variables my app is currently using?\n\n```\n$ bundle exec envied extract\n```\n\nThis comes in handy when you're not using ENVied yet. It will find all `ENV['KEY']` and `ENV.fetch('KEY')` statements in your project.\n\nIt assumes a standard project layout (see the default value for the globs-option).\n\n### How to check the config of a Heroku app?\n\nThe easiest/quickest is to run:\n\n```\n$ heroku config --json | bundle exec envied check:heroku\n```\n\nThis is equivalent to having the heroku config as your local environment and running `envied check:heroku --groups default production`.\n\nYou want to run this right before a deploy to Heroku. This prevents that your app will crash during bootup because ENV-variables are missing from heroku config.\n\nYou can turn the above into a handy binstub like so:\n```\n$ bundle exec envied check:heroku:binstub\n# created bin/heroku-env-check\n```\n\nThis way you can do stuff like:\n```\n$ ./bin/heroku-env-check \u0026\u0026 git push live master\n```\n\n### What happened to default values??\n\nThe short version: simplicity, i.e. the best tool for the job.  \n\nIn the early days of ENVied it was possible to provide default values for a variable.  \nWhile convenient, it had several drawbacks:\n- it would introduce a value for ENVied.FOO, while ENV['FOO'] was nil: confusing and a potential source of bugs.\n- it hides the fact that an application can actually be configged via the environment.\n- it creates an in-process environment which is hard to inspect (as opposed to doing `printenv FOO` in a shell, after or before starting the application).\n- there are better ways: e.g. a sample file in a project with a bunch of exports (ie `export FOO=sane-default # and even some documentation`) that someone can source in their shell (see [Best Practices](#best-practices)).\n- made the code quite complex.\n\nAs an alternative include a file `.envrc.sample` in the root of your project containing default values (ie `export FOO=bar`) that users can source in their shell. See also [Best Practices](#best-practices).\n\n\n## Development\n\n```bash\n$ ./bin/setup\n\n# run tests\n$ ./bin/rspec\n\n# hack with pry\n$ ./bin/console\n\n# run CLI:\n$ ./bin/envied\n```\n\nThere's a `.envrc.sample` included that can be used in combination with [direnv](http://direnv.net/).\n\n## Contributing\n\nTo suggest a new feature, [open an Issue](https://gitlab.com/envied/envied/issues/new) before opening a PR.\n\n1. Fork it: https://gitlab.com/envied/envied/-/forks/new\n2. Create your feature branch: `git checkout -b my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. Create a new pull request for your feature branch\n","funding_links":[],"categories":["Ruby","Configuration"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feval%2Fenvied","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feval%2Fenvied","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feval%2Fenvied/lists"}