From b0590334db2ec1e3b46c16e2aa175f2341a0dd7d Mon Sep 17 00:00:00 2001 From: humblerookie <1428864+humblerookie@users.noreply.github.com> Date: Fri, 7 Jun 2024 15:42:56 +0530 Subject: [PATCH 1/2] simplify usage documentation --- README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 64 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index c373ee5..0e24936 100644 --- a/README.md +++ b/README.md @@ -123,24 +123,79 @@ Alternatively, you can install it in your entire system instead (not recommended gem install arkana ``` -# Usage +# Basic Usage -Arkana requires the declaration of a YAML config file. Although you can name it whatever, the convention is to name it `.arkana.yml`. See [template.yml](/template.yml) for practical examples. +Arkana requires the declaration of a YAML config file. Although you can name it whatever, the convention is to name it `.arkana.yml`. See [template.yml](/template.yml) for complete options. -Once you have create your config file, you can run Arkana: +Once you have created your config file, you can run Arkana: ```sh Usage: arkana [options] -c /path/to/your/.arkana.yml, Path to your config file. Defaults to '.arkana.yml' - --config-filepath -e /path/to/your/.env, Path to your dotenv file. Defaults to '.env' if one exists. - --dotenv-filepath - -f, --flavor FrostedFlakes Flavors are useful, for instance, when generating secrets for white-label projects. See the README for more information - -i debug,release, Optionally pass the environments that you want Arkana to generate secrets for. Useful if you only want to build a certain environment, e.g. just Debug in local machines, while only building Staging and Release in CI. Separate the keys using a comma, without spaces. When omitted, Arkana generate secrets for all environments. - --include-environments - -l, --lang kotlin Language to produce keys for, e.g. kotlin, swift. Defaults to 'swift'. See the README for more information + -l kotlin Language to produce keys for, e.g. kotlin, swift. Defaults to 'swift'. ``` + +> [!NOTE] +> For complete set of args look at the [options](#options) section. + + +### Config File + +The `arkana.yml` would typically contain 3 important sections + - **Environments** : This is typically where you specify `debug`, `release` or other environments which you wish to create + - **Environment Secrets**: This is where you declare the keys which will be ultimately exposed to your app like `apiKey` + - **Global Secrets** : Here you'd declare keys which are the same across all environments. + +### Environment File + +The environment(.env) file contains the actual secrets for each environment. While config file declares the keys, they are assigned encrypted values from this file. + +#### Sample + +A config file as shown below +```yaml +environments: + - Release + - Debug +environment_secrets: + - apiKey +global_secrets: + - clientId +``` + +coupled with an env file + +```properties +apiKeyDebug=de_#192A3532 +apiKeyRelease=rel_#2Asdas3322 +clientId=134122 +``` + +would generate the following accessors: + +```swift +//Swift +public extension ArkanaKeys { + struct Global: ArkanaKeysGlobalProtocol { + public let clientId: String = {} + } +} +public extension ArkanaKeys { + struct Release: ArkanaKeysEnvironmentProtocol { + public let apiKey: String = {} + } +} +public extension ArkanaKeys { + struct Debug: ArkanaKeysEnvironmentProtocol { + public let apiKey: String = {} + } +} +``` + + + Note that you have to prepend `bundle exec` before `arkana` if you manage your dependencies via bundler, as recommended. Arkana only has one command, which parses your config file and env vars, generating all the code needed. Arkana should always be run before attempting to build your project, to make sure the files exist _and_ are up-to-date (according to the current config file). This means you might need to add the Arkana run command in your CI/CD scripts, _fastlane_, Xcode Build Phases, or something similar. From 296594b0c82ff8f53457f2564fb75851e0d36448 Mon Sep 17 00:00:00 2001 From: Roger Oba Date: Sat, 8 Jun 2024 16:33:26 -0300 Subject: [PATCH 2/2] Lint, apply minor styling changes, and clarify `.env` usage. --- README.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 0e24936..9f63bd8 100644 --- a/README.md +++ b/README.md @@ -136,57 +136,59 @@ Usage: arkana [options] -l kotlin Language to produce keys for, e.g. kotlin, swift. Defaults to 'swift'. ``` - > [!NOTE] -> For complete set of args look at the [options](#options) section. - +> For the complete set of args, look at the [options](#options) section. ### Config File -The `arkana.yml` would typically contain 3 important sections - - **Environments** : This is typically where you specify `debug`, `release` or other environments which you wish to create - - **Environment Secrets**: This is where you declare the keys which will be ultimately exposed to your app like `apiKey` - - **Global Secrets** : Here you'd declare keys which are the same across all environments. +The `arkana.yml` would typically contain 3 important sections: + +- **Environments**: This is typically where you specify `debug`, `release` or other environments which you wish to create. +- **Environment Secrets**: This is where you declare the keys which will be ultimately exposed to your app, like `apiKey`. +- **Global Secrets**: Here you'd declare keys which are the same across all environments. ### Environment File -The environment(.env) file contains the actual secrets for each environment. While config file declares the keys, they are assigned encrypted values from this file. +The environment (`.env`) file contains the actual secrets for each environment. While config file declares the keys, they are assigned encrypted values from this file. + +This file is optional, but quite handy in local development. `.env` files shouldn't be committed as they contain your secrets. Instead, they should be stored in a secure location, like your CI/CD server as environment variables (all CI/CD servers have a way to store secrets securely). See [Continuous Integration](#continuous-integration) for more information. #### Sample -A config file as shown below -```yaml +A config file as shown below: + +```yaml environments: - Release - Debug environment_secrets: - - apiKey + - apiKey global_secrets: - - clientId + - clientId ``` -coupled with an env file +Coupled with an env file: ```properties -apiKeyDebug=de_#192A3532 -apiKeyRelease=rel_#2Asdas3322 -clientId=134122 +apiKeyDebug = "your_debug_api_key" +apiKeyRelease = "your_release_api_key" +clientId = "your_client_id" ``` -would generate the following accessors: +Would generate the following accessors: ```swift -//Swift +// Swift public extension ArkanaKeys { struct Global: ArkanaKeysGlobalProtocol { public let clientId: String = {} } -} +} public extension ArkanaKeys { struct Release: ArkanaKeysEnvironmentProtocol { public let apiKey: String = {} } -} +} public extension ArkanaKeys { struct Debug: ArkanaKeysEnvironmentProtocol { public let apiKey: String = {} @@ -194,8 +196,6 @@ public extension ArkanaKeys { } ``` - - Note that you have to prepend `bundle exec` before `arkana` if you manage your dependencies via bundler, as recommended. Arkana only has one command, which parses your config file and env vars, generating all the code needed. Arkana should always be run before attempting to build your project, to make sure the files exist _and_ are up-to-date (according to the current config file). This means you might need to add the Arkana run command in your CI/CD scripts, _fastlane_, Xcode Build Phases, or something similar.