{"id":20563792,"url":"https://github.com/azohra/ptolemy","last_synced_at":"2025-04-14T14:52:13.850Z","repository":{"id":45060617,"uuid":"162159362","full_name":"azohra/ptolemy","owner":"azohra","description":"Elixir Application Environment Variable Management","archived":false,"fork":false,"pushed_at":"2022-01-11T21:29:36.000Z","size":179,"stargazers_count":14,"open_issues_count":3,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T03:41:33.266Z","etag":null,"topics":["elixir","env","vault"],"latest_commit_sha":null,"homepage":"","language":"Elixir","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/azohra.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}},"created_at":"2018-12-17T16:27:28.000Z","updated_at":"2024-06-10T12:10:02.000Z","dependencies_parsed_at":"2022-09-07T17:35:01.480Z","dependency_job_id":null,"html_url":"https://github.com/azohra/ptolemy","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fptolemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fptolemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fptolemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fptolemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azohra","download_url":"https://codeload.github.com/azohra/ptolemy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809029,"owners_count":21164895,"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":["elixir","env","vault"],"created_at":"2024-11-16T04:21:00.084Z","updated_at":"2025-04-14T14:52:13.812Z","avatar_url":"https://github.com/azohra.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e \n  \u003cimg src=\"./assets/logo.svg\" height=\"100%\" width=\"100%\"/\u003e\n  \u003ca href= \"https://travis-ci.org/azohra/ptolemy\"\u003e\u003cimg src=\"https://travis-ci.org/azohra/ptolemy.svg?branch=master\"\u003e\u003c/a\u003e\n  \u003ca href= \"https://hex.pm/packages/ptolemy\"\u003e\u003cimg src=\"https://img.shields.io/hexpm/v/ptolemy.svg\"/\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/hexpm/l/ptolemy.svg\"/\u003e\n\u003c/p\u003e\n\n---\nPtolemy is an application environment manager for your Elixir projects. It provides a simple interface to authenticate and interact (via CRUD operations) with a remote backend that stores secrets and sensitive information. As well as providing these functionality Ptolemy also features a dynamic application environment variable loader that loads secrets from a remote backend such as Hashicorp's Vault and handle its lifecycle by refreshing the secret when they are about to expire.\n\n## Features\n- [Application environment management](https://hexdocs.pm/ptolemy/0.2.0/Ptolemy.Loader.html#content). \n- Authentication through Google's [Cloud IAP](https://cloud.google.com/iap/)\n- [Hashicorp Vault](https://github.com/hashicorp/vault) integration (tested against Vault v0.11.5 but will support v0.10.4 and later):\n  - Supported authentication methods:\n    - GCP\n    - Approle\n  - Supported secret engines:\n    - Key-Value Version 2 (KV2) \n    - Public Key Infrastructure (PKI)\n    - Google Cloud Platform (GCP)\n\n## Installation\nPtolemy is available on hex you can install it by following these steps:\n\n1. Add ptolemy to your `deps`\n```elixir\ndef deps do\n  [\n    {:ptolemy, \"~\u003e 0.2.0\"}\n  ]\nend\n```\n2. Run `mix deps.get \u0026\u0026 mix deps.compile`\n\n## Example Usage\n### Intergrating Ptolemy With Your Project\nWithin `examples/` we provide an example repository called Simple app. The configuration file in the project shall be served as an example for key values and PKI engine. More configuration specifications can be found in the *Configuration* section below.\n\nFollow the `README.md` found in `examples/` instructions to get started.\n\n### Example CLI usage\nYou will need to configure the application to point to remote backend. Edit the `config.exs` to point to remote backend.\n\nStart iex with Ptolemy's modules loaded by entering:\n```bash\nbash-3.2$ cd ptolemy/ \u0026\u0026 iex -S mix\nErlang/OTP 21 [erts-10.1.2] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe] [dtrace]\n\nInteractive Elixir (1.7.4) - press Ctrl+C to exit (type h() ENTER for help)\niex(1)\u003e {:ok, server} = Ptolemy.start(:server1, :production)\niex(2)\u003e Ptolemy.read(server, :kv_engine1, [:ptolemy, true])\n{:ok, %{\"test\" =\u003e \"foo\"}}\n```\n\n## Configuration\nThere are two configuration blocks that exist in ptolemy as of version `0.2`. Both are independent of one another and do not have to be used at the same time.\n\n1. `:vaults` configuration is responsible for holding the Vault server configurations\n2. `:loader` configuration manages the dynamic loading of secrets from providers, e.g. Vault, System Environment\n\nIn order to get the most of the library, we recommend to configrure both blocks. Example configuration files can be found in `config/test.exs`, `examples/config/config.exs`.\n\n### Configuring `:vaults`\nThe `:vaults` key configures ptolemy various backend providers (Hashicorp vault is the only backend currently supported). Each key within the `:vaults` block represents a specific server in which ptolemy can query to retrieve values such as application secrets currently stored in vault.\n\n```elixir\nconfig :ptolemy, vaults: [\n  server2: %{\n    vault_url: \"https://test-vault.com\",\n    engines: [\n      kv_engine1: %{\n        engine_type: :KV,\n        engine_path: \"secret/\",\n        secrets: %{\n          test_secret: \"/test_secret\"\n        }\n      },\n      gcp_engine1: %{\n        engine_type: :GCP,\n        engine_path: \"gcp/\"\n      },\n      pki_engine1: %{\n        engine_type: :PKI,\n        engine_path: \"pki/\",\n        roles: %{\n            test_role1: \"/role1\"\n          }\n      }\n    ],\n    auth: %{\n      method: :Approle,\n      credentials: %{\n        role_id: \"test\",\n        secret_id: \"test\"\n      },\n      auto_renew: true,\n      opts: []\n    }\n  }\n]\n```\nAdditional details about usage within the `:vaults` configuration block can be found in `Ptolemy`'s module docs.\n\n### Configuring `:loader`\nIf `Ptolemy.Loader` is being used to dynamically manage application environment variables, then an extra configuration block should also be added:\n\nSpecifying this block will allow `Ptolemy.Loader` to populate the application specific env vars at runtime.\n\n```elixir\n  config :ptolemy, loader: [\n    env: [\n      {{:app_name, :secret_key}, {Ptolemy.Providers.SystemEnv, \"PATH\"}},\n      {{:app_name, :another_secret_key}, {Ptolemy.Providers.Vault, [:engine_name, [opt1, opt2], [key1, key2]]}},\n      # ...\n    ]\n  ]\n```\nAdditional details about usage the keys within the `:loader` configuration block can be found in `Ptolemy.Loader`'s module doc.\n\n## Development\nRunning a local dev environment of ptolemy requires:\n- JQ\n- Docker and docker-compose\n\nBefore developing you must issue these commands:\n1. Start up the dockerized version of vault via docker-compose\n```bash\n$ docker-compose up\n```\n2. In a different terminal issue:\n```bash\n$ . ./vault_init.sh\n```\n\nThis will setup a local vault server accessible at `http://localhost:8200` along with setting up a the docker-composed vault server with a testing approle, the credentials for the role will be exported to your environment variable of the current shell used `SECRET_ID` and `ROLE_ID`.\n\n## Troubleshooting\n\nWhat do I do if I get `Authentication Failed` with error `role requires that JWTs must expire within X seconds` for GCP authentication?\n\n\u003e There is something wrong with your system time, please make sure that you are using a reputable Network Time Protocol (NTP) server as your time provider or force an update for you system type.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazohra%2Fptolemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazohra%2Fptolemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazohra%2Fptolemy/lists"}