From 82c999d8049307e599f6a63343f2ddf48c918d8e Mon Sep 17 00:00:00 2001 From: Robert Date: Thu, 29 Apr 2021 08:30:41 -0700 Subject: [PATCH 1/4] Cleans up guides/configuration grammer and organization --- guides/configuration.md | 59 ++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/guides/configuration.md b/guides/configuration.md index 2c59e14..1f5c27a 100644 --- a/guides/configuration.md +++ b/guides/configuration.md @@ -1,42 +1,52 @@ # Configuration -Your Amber project has a `{project_name}/config` directory, this directory contains Amber configuration files. +Every Amber project has a `{project_name}/config` directory. This directory contains all the configuration files used by your Amber project. -## Default Environments +## Configuring Amber + +Within the `config` file for your Amber project, you will find: + +### Initializers -Your Amber project ships with three default environments: +You can use initializers to load configuration settings into various application components like mailers after all of the frameworks and shards are loaded. + +To add a new initializer simply create a file and save it under `config/initializers` to load at runtime. + +### Environments +Each Amber project ships with three default environments: * Development * Test * Production -The files for each of the environment is found in `{project_name}/config/environments`. +The files for each environment are found under `{project_name}/config/environments`. Each Amber environment is configured in separate YAML files under this directory. -## Getting the current environment - -To get the current amber environment just type `Amber.env.to_s`. You can also check against the current environment `Amber.env== :production` or `Amber.env.development?` `Amber.env.test?` `Amber.env.production?` - -## Setting the current environment +At runtime the framework will use the `AMBER_ENV` environment value to load the respective environment configuration into the application. For example `AMBER_ENV=staging` then this will expect a `config/environments/staging.yml` file to exist. -Amber sets the current environment based on the `AMBER_ENV` environment variable. The default environment is `development`. +## Getting the current environment -## Configuring Amber +To get the current Amber environment you can use the `Amber.env` method. -All amber project have a directory called `config/` in this directory you will find +```ruby +Amber.env +# returns => :production +``` -### Initializers +Alternatively, you can use built in environment helpers such as `Amber.env.development?`, `Amber.env.test?`, and `Amber.env.production?` to check the environment value. -You can use initializers to hold configuration settings that should be made after all of the frameworks and shards are loaded, such as options to configure settings for these parts. +## Setting the current environment -`config/initializers`place any initializer file here to load at runtime. +As mentioned previously, Amber sets the application environment based on the `AMBER_ENV` environment variable. By default, the environment is set to `development`. If you would like to set the environment to something else, you will need to configure the `AMBER_ENV` environment variable before running the server process. -### Environments +For example to run Amber in the production environment, we can set the `AMBER_ENV` to `production`. -`config/environments` all your environment YAML configuration files live here, these files get loaded based on the `AMBER_ENV` value. For example `AMBER_ENV=staging` then this will expect a `config/environments/staging.yml` file to exist. +```bash +AMBER_ENV=production amber watch +``` ### Application.cr -`config/application.cr` this is the main entry file for amber application files and it allows you to overwrite setting based on dynamic values, it makes it possible to use environment variables as your settings. +The main entry point for an Amber application is `config/application.cr`. This application file allows you to overwrite settings based on dynamic values. It also allows you to use environment variables available to the application process to configure your application. ```ruby Amber::Server.configure do |app| @@ -49,7 +59,7 @@ end ## Where do custom settings go? -You can include new settings in any of the environment YAML files by specifying them in the secrets section. +Amber makes it easy to manage custom settings in each of the environment YAML files. You can include new settings in any of the environment YAML file by specifying them in the secrets section. ```yaml database_url: postgres://postgres:@localhost:5432/test_development @@ -67,9 +77,13 @@ Amber.settings.secrets["custom"] # => "secret value here" ## Encrypted Environment Settings -With Amber you can encrypt your environment setting `amber encrypt {environment}`, this command will open your editor to allow make changes if needed and then encrypt the file `{environment}.enc`. +With Amber you can encrypt your environment setting using `amber encrypt {environment}`, this command will open your editor to allow make changes if needed and then encrypt the file `{environment}.enc`. -A `.encryption_key` file is provided. It contains a secret\_key\_base that is used to decrypt your encrypted environment settings. This file is added to `.gitignore` so it will not be committed to your repository. Without the encryption key, you won't be able to decrypt your environment settings. +A `.encryption_key` file is provided. It contains a `secret_key_base` that is used to decrypt your encrypted environment settings. This file is added to `.gitignore` to avoid inclusion in version control. + +{% hint style="danger" %} +Without the encryption key, you won't be able to decrypt your environment settings. +{% endhint %} {% hint style="danger" %} **Never commit the encryption key!** @@ -78,6 +92,3 @@ Setup your production machine and use the variable `AMBER_ENCRYPTION_KEY` See more on [encrypt section](../cli/encrypt.md) {% endhint %} - - - From 33f29cd576821e706ec371ab0c7e8a0871824f9f Mon Sep 17 00:00:00 2001 From: Robert Date: Thu, 29 Apr 2021 08:35:28 -0700 Subject: [PATCH 2/4] Moves environments above initializers in docs --- guides/configuration.md | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/guides/configuration.md b/guides/configuration.md index 1f5c27a..0aae257 100644 --- a/guides/configuration.md +++ b/guides/configuration.md @@ -4,13 +4,7 @@ Every Amber project has a `{project_name}/config` directory. This directory cont ## Configuring Amber -Within the `config` file for your Amber project, you will find: - -### Initializers - -You can use initializers to load configuration settings into various application components like mailers after all of the frameworks and shards are loaded. - -To add a new initializer simply create a file and save it under `config/initializers` to load at runtime. +Within the `config` directory of an Amber project, you will find several helpful configuration settings. ### Environments Each Amber project ships with three default environments: @@ -44,11 +38,38 @@ For example to run Amber in the production environment, we can set the `AMBER_EN AMBER_ENV=production amber watch ``` +### Initializers + +You can use initializers to load configuration settings into various application components like mailers after all of the frameworks and shards are loaded. + +To add a new initializer simply create a file and save it under `config/initializers` to load at runtime. + +For example, to initialize a `Quartz` mailer: + +```ruby +# config/initializers/mailer.cr + +require "quartz_mailer" + +Quartz.config do |c| + c.smtp_enabled = Amber.settings.smtp.enabled + + c.smtp_address = ENV["SMTP_ADDRESS"]? || Amber.settings.smtp.host + c.smtp_port = ENV["SMTP_PORT"]? || Amber.settings.smtp.port + c.username = ENV["SMTP_USERNAME"]? || Amber.settings.smtp.username + c.password = ENV["SMTP_PASSWORD"]? || Amber.settings.smtp.password + + c.use_authentication = !c.password.blank? +end +``` + ### Application.cr The main entry point for an Amber application is `config/application.cr`. This application file allows you to overwrite settings based on dynamic values. It also allows you to use environment variables available to the application process to configure your application. ```ruby +# config/application.cr + Amber::Server.configure do |app| app.name = ENV["APP_NAME"] if ENV["APP_NAME"]? app.host = ENV["HOSTNAME"] if ENV["HOSTNAME"]? @@ -62,6 +83,8 @@ end Amber makes it easy to manage custom settings in each of the environment YAML files. You can include new settings in any of the environment YAML file by specifying them in the secrets section. ```yaml +# config/environments/development.yml + database_url: postgres://postgres:@localhost:5432/test_development secrets: custom: secret value here From cac40ca7eb1f1aaee996d525f257a97c50c56c95 Mon Sep 17 00:00:00 2001 From: Robert Date: Thu, 29 Apr 2021 08:36:39 -0700 Subject: [PATCH 3/4] Fixes grammar about AMBER_ENV in initializers --- guides/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/configuration.md b/guides/configuration.md index 0aae257..430b914 100644 --- a/guides/configuration.md +++ b/guides/configuration.md @@ -15,7 +15,7 @@ Each Amber project ships with three default environments: The files for each environment are found under `{project_name}/config/environments`. Each Amber environment is configured in separate YAML files under this directory. -At runtime the framework will use the `AMBER_ENV` environment value to load the respective environment configuration into the application. For example `AMBER_ENV=staging` then this will expect a `config/environments/staging.yml` file to exist. +At runtime the framework will use the `AMBER_ENV` environment value to load the respective environment configuration into the application. For example if `AMBER_ENV=staging` the framework will expect a `config/environments/staging.yml` file to exist and attempt to load its configurations into the application. ## Getting the current environment From 7ccbc95fe626c2e72d560022472b1f3c56d2726c Mon Sep 17 00:00:00 2001 From: Robert Date: Thu, 29 Apr 2021 08:38:13 -0700 Subject: [PATCH 4/4] Nit picky verb usage --- guides/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/configuration.md b/guides/configuration.md index 430b914..2871f99 100644 --- a/guides/configuration.md +++ b/guides/configuration.md @@ -65,7 +65,7 @@ end ### Application.cr -The main entry point for an Amber application is `config/application.cr`. This application file allows you to overwrite settings based on dynamic values. It also allows you to use environment variables available to the application process to configure your application. +The main entry point for an Amber application is `config/application.cr`. This application file allows you to overwrite settings using dynamic values. It also allows you to use environment variables available to the application process to configure your application. ```ruby # config/application.cr