Skip to content
Permalink
Browse files

Upgrade guides for v1.0.0.beta1

  • Loading branch information...
jodosha committed Feb 11, 2017
1 parent cb6761c commit bdb2e4c719530c28ae2c96ae8d5bebe6a344cb32
Showing with 144 additions and 81 deletions.
  1. +2 −0 data/guides.yml
  2. +29 −19 source/guides/mailers/delivery.md
  3. +31 −62 source/guides/projects/logging.md
  4. +82 −0 source/guides/upgrade-notes/v100beta1.md
@@ -115,3 +115,5 @@ categories:
title: v0.8.0
- path: v090
title: v0.9.0
- path: v100beta1
title: v1.0.0.beta1
@@ -59,23 +59,28 @@ It defaults to SMTP (`:smtp`) for production environment, while `:test` is autom
The second optional argument is a set of arbitrary configurations that we want to pass to the configuration:

```ruby
# lib/bookshelf.rb
# config/environment.rb
# ...
Hanami::Mailer.configure do
Hanami.configure do
# ...
delivery do
development :test
test :test
production :smtp,
address: "smtp.gmail.com",
port: 587,
domain: "bookshelf.org",
user_name: ENV['SMTP_USERNAME'],
password: ENV['SMTP_PASSWORD'],
authentication: "plain",
enable_starttls_auto: true
mailer do
root Hanami.root.join("lib", "kaba", "mailers")
# See http://hanamirb.org/guides/mailers/delivery
delivery :test
end
end.load!
# ...
environment :production do
# ...
mailer do
delivery :smtp, address: ENV['SMTP_HOST'], port: ENV['SMTP_PORT']
end
end
end
```

For advanced configurations, please have a look at `mail` [gem](https://github.com/mikel/mail) by Mikel Lindsaar.
@@ -91,16 +96,21 @@ If we need to a custom delivery workflow, we can pass a class to the configurati
Here's an example on how to use [Mandrill API](https://mandrillapp.com/api/docs/) to deliver emails.

```ruby
# lib/bookshelf.rb
# config/environment.rb
# ...
require 'lib/mailers/mandrill_delivery_method'
Hanami::Mailer.configure do
Hanami.configure do
# ...
delivery do
production MandrillDeliveryMethod, api_key: ENV['MANDRILL_API_KEY']
environment :production do
# ...
mailer do
production MandrillDeliveryMethod, api_key: ENV['MANDRILL_API_KEY']
end
end
end.load!
end
```

The object MUST respond to `#initialize(options = {})` and to `#deliver!(mail)`, where `mail` is an instance of [`Mail::Message`](https://github.com/mikel/mail/blob/master/lib/mail/mail.rb).
@@ -4,78 +4,47 @@ title: Guides - Logging

# Logging

Within a project, each application has its own logger
A project has a global logger available at `Hanami.logger` that can be used like this: `Hanami.logger.debug "Hello"`

<p class="convention">
For a given application named <code>Web</code>, logger is accessible at <code>Web.logger</code>.
</p>

Using the per-environment application settings we can define the behavior of the logger: the destination `stream`, `format`, and `level`.
For instance, the default destination stream is standard output, but we can use a file instead.
It can be configured in `config/environment.rb`

```ruby
# apps/web/application.rb
module Web
class Application < Hanami::Application
# ...
# config/environment.rb
# ...
Hanami.configure do
# ...
environment :development do
logger level: :info
end
environment :production do
logger level: :info, formatter: :json
configure :development do
# ...
# Logger
# See: http://hanamirb.org/guides/projects/logging
#
# Logger stream. It defaults to STDOUT.
# logger.stream "log/development.log"
#
# Logger level. It defaults to DEBUG
# logger.level :debug
#
# Logger format. It defaults to DEFAULT
# logger.format :default
end
##
# TEST
#
configure :test do
# ...
# Logger
# See: http://hanamirb.org/guides/projects/logging
#
# Logger level. It defaults to ERROR
logger.level :error
end
##
# PRODUCTION
#
configure :production do
# ...
# Logger
# See: http://hanamirb.org/guides/projects/logging
#
# Logger stream. It defaults to STDOUT.
# logger.stream "log/production.log"
#
# Logger level. It defaults to INFO
logger.level :info
# Logger format.
logger.format :json
end
# ...
end
end
```

Using standard output is a [best practice](http://12factor.net/logs) that most hosting SaaS companies [suggest using](https://devcenter.heroku.com/articles/rails4#logging-and-assets).
By default it uses stardard output because it's a [best practice](http://12factor.net/logs) that most hosting SaaS companies [suggest using](https://devcenter.heroku.com/articles/rails4#logging-and-assets).

If you want to use a file, pass `stream: 'path/to/file.log'` as an option.

## Automatic Logging

Because of its parseability, JSON is the default format for production environment, where you may want aggregate information about the project usage.
All the HTTP requests, SQL queries, and database operations are automatically logged.

The logger is very similar to Ruby's `Logger`; you can use it like this:
When a project is used in development mode, the logging format is human readable:

```ruby
Web.logger.debug "Hello"
[bookshelf] [INFO] [2017-02-11 15:42:48 +0100] HTTP/1.1 GET 200 127.0.0.1 /books/1 451 0.018576
[bookshelf] [INFO] [2017-02-11 15:42:48 +0100] (0.000381s) SELECT "id", "title", "created_at", "updated_at" FROM "books" WHERE ("book"."id" = '1') ORDER BY "books"."id"
```

For production environment, the default format is JSON.
JSON is parseable and more machine oriented. It works great with log aggregators or SaaS logging products.

```json
{"app":"bookshelf","severity":"INFO","time":"2017-02-10T22:31:51Z","http":"HTTP/1.1","verb":"GET","status":"200","ip":"127.0.0.1","path":"/books/1","query":"","length":"451","elapsed":0.000391478}
```
@@ -0,0 +1,82 @@
---
title: Guides - Upgrade Notes for v1.0.0.beta1
---

## Upgrade Notes for v1.0.0.beta1

* Edit `Gemfile`, by changing Hanami version: `gem 'hanami', '1.0.0.beta1'`

* Edit `Gemfile`, by changing Hanami Model version: `gem 'hanami-model', '1.0.0.beta1'`

* Edit `Gemfile`, by removing Bundler: `gem 'bundler'` can be deleted

* Add `config/boot.rb` as shown below

* Edit `config/environment.rb` as shown below

* Edit `lib/bookshelf.rb` as shown below

* Edit all the applications to remove the `logger` settings. Eg. `apps/web/application.rb`

* Edit the project using `Hanami.logger` instead of application level loggers. Eg. `Web.logger`


### `config/boot.rb`

```ruby
require_relative './environment'
Hanami.boot
```

This file can be used to boot your project from external commands. For instance to use it with Sidekiq.

### `config/environment.rb`

```ruby
require 'bundler/setup'
require 'hanami/setup'
require 'hanami/model'
require_relative '../lib/bookshelf'
require_relative '../apps/web/application'
Hanami.configure do
mount Web::Application, at: '/'
model do
adapter :sql, ENV['DATABASE_URL']
migrations 'db/migrations'
schema 'db/schema.sql'
end
mailer do
root Hanami.root.join("lib", "bookshelf", "mailers")
# This has changed. It used to be a block, now it's a setting
delivery :test
end
  # These two blocks are new.
# They MUST be after the general settings like `mount`, `model`, `mailer`.
environment :development do
# See: http://hanamirb.org/guides/projects/logging
logger level: :info
end
environment :production do
logger level: :info, formatter: :json
mailer do
delivery :smtp, address: ENV['SMTP_HOST'], port: ENV['SMTP_PORT']
end
end
end
```

### `lib/bookshelf.rb`

```ruby
# This file was intentionally left blank ;)
```

**If you have any problem, don't hesitate to look for help in [chat](http://chat.hanamirb.org).**

0 comments on commit bdb2e4c

Please sign in to comment.
You can’t perform that action at this time.