Merge lp:~hatch/charms/precise/ghost/trunk into lp:charms/ghost

[Jeff Pihach]

Committing revno dce85f67e3 from https://github.com/hatched/ghost-charm

[Review Queue (review-queue)]

This items has failed automated testing! Results available here http://reports.vapour.ws/charm-tests/charm-bundle-test-10463-results

review: Needs Fixing (automated testing)

[José Antonio Rey (jose)]

Hey Jeff!

I just ran the tests on this MP, and it looks good to me. +1!

Thanks for improving the charm!

review: Approve

=== modified file 'README.md'
--- README.md	2014-06-22 22:53:50 +0000
+++ README.md	2014-11-27 14:38:00 +0000
@@ -7,23 +7,28 @@
 
 This Ghost charm allows you to trivially deploy a horizontally scalable, load
 balanced, instance of the Ghost blogging platform locally or on a cloud
-provider of choice.
+provider of choice using Juju.
 
-To deploy this charm you will need a cloud environment, a working juju
+To deploy this charm you will need a cloud environment, a working Juju
 installation and a successful bootstrap. If you don't have Juju installed and an
-environment set up see [Getting Started With Juju](https://juju.ubuntu.com/docs/getting-started.html).
+environment set up see
+[Getting Started With Juju](https://jujucharms.com/docs/getting-started).
 
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+- [Using A Load Balancer](#using-a-load-balancer)
+- [Setting Up Email Service](#setting-up-email-service)
 - [Connecting To Mysql](#connecting-to-mysql)
 - [Horizontal Scaling](#horizontal-scaling)
-- [Load Balancing](#load-balancing)
-- [Wrap Up](#wrap-up)
+- [Colocating On A Single Machine](#colocating-on-a-single-machine)
+- [Deploying And Using The GUI](#deploying-and-using-the-gui)
 - [Contributing](#contributing)
 - [Bug Reports](#bug-reports)
 
 # Quick Start
 
+After you have a Juju cloud environment running:
+
     $ juju deploy ghost
     $ juju expose ghost
 
@@ -32,25 +37,37 @@
     $ juju status ghost
 
 Visit `<your URL>:2368/ghost/signup/` to create your username and password.
-Continue setting up Ghost by following the [usage documentation](http://docs.ghost.org/usage/).
+Continue setting up Ghost by following the
+[usage documentation](http://docs.ghost.org/usage/).
 
 You will want to change the URL that Ghost uses to generate links internally to
 the URL you will be using for your blog.
 
     $ juju set ghost url=<your url>
 
-If you will only be running a single instance of Ghost without any load
-balancing or reverse proxy then you will also want to set the listening port.
+The ghost charm is designed to not run as a user which has access to reserved
+ports. This means that if you want to run your blog on port 80 or 443 you will
+need to deploy and relate this charm to Apache. This has the added benefit of
+being able to load balance between any additional Ghost units and do url
+redirection if necessary. See
+[Using A Load Balancer](#using-a-load-balancer) for more information.
 
-    $juju set ghost port=80
+In order to allow Ghost to send emails for things like new user validation and
+password resets you will want to set up the email service. See
+[Setting Up Email Service](#setting-up-email-service) for more information.
 
 It's also recommended, although not required, that you use a MySQL database
-instead of the internal SQLite database. See [Connecting To MySQL](#connecting-to-mysql)
-for more information.
+instead of the internal SQLite database. See
+[Connecting To MySQL](#connecting-to-mysql) for more information.
+
+All of the instructions in this readme are provided using Juju's CLI interface.
+Juju also has an amazing GUI which is highly recommended for beginners to Juju.
+For information on how to deploy the GUI and use it with this charm see
+[Deploying And Using The GUI](#deploying-and-using-the-gui)
 
 # Configuration
 
-To view the configuration options for this charm:
+To view the configuration options for this charm open the `config.yaml` file or:
 
     $ juju get ghost
 
@@ -58,17 +75,72 @@
 
     $ juju set ghost <key>=<value>
 
-To set the URL which ghost uses when generating links:
-
-    $ juju set ghost url=http://my-ghost-blog.com
-
-To set the host to be passed to node's net.Server listen():
-
-    $ juju set ghost host=0.0.0.0
-
-To set the port to be passed to node's net.Server listen():
-
-    $ juju set ghost port=2368
+See the `config.yaml` file in the charm for a detailed list of all of the charms
+configuration options.
+
+
+# Using A Load Balancer
+
+In order to run multiple instances of the Ghost web server and to be able to
+serve your blog on a reserved port this charm supports being load balanced and
+reverse proxied by [haproxy](https://jujucharms.com/haproxy/trusty).
+
+In order to reverse proxy and load balance this service you will need to deploy
+haproxy:
+
+    $ juju deploy haproxy
+    $ juju expose haproxy
+
+You will then need to unexpose the Ghost service:
+
+    $ juju unexpose ghost
+
+You now need to let your haproxy instance know about Ghost so that it can
+make the appropriate adjustments.
+
+    $ juju add-relation ghost haproxy
+
+After a few moments of configuration your Ghost blog will now be reachable on
+port 80 and you will be able to horizontally scale the server and have it
+automatically load balanced. See [Horizontal Scaling](#horizontal-scaling) for
+more information.
+
+
+# Setting Up Email Service
+
+Ghost needs the ability to send emails to users for things like new user
+validation and password resets. To accomplish this Ghost supports using a
+third party email service which it can communicate with to send these emails.
+Ghost, and this charm, supports sending emails using Mailgun, Amazon SES, and
+Gmail. Additional information about why Ghost needs this service and it's
+supported platforms see [Mail configuration](http://support.ghost.org/mail/).
+
+To specify a supported email service to use you simply need to set the
+configuration values in the charm and they will be generated for your Ghost
+instance.
+
+#### Mailgun & Gmail
+
+    $ juju set ghost mailserver_username=<your username>
+    $ juju set ghost mailserver_password=<your password>
+    Then
+    $ juju set ghost mail_service=Mailgun
+    -or-
+    $ juju set ghost mail_service=Gmail
+
+#### Amazon SES
+
+    $ juju set ghost mailserver_username=<your username>
+    $ juju set ghost mailserver_password=<your password>
+    $ juju set ghost amazon_ses_host=<your ses host>
+    Then
+    $ juju set ghost mail_service=SES
+
+After this has been completed your Ghost server will restart and Ghost will
+now be able to send emails using that provider. It's recommended to test this
+before you need it by creating a new user and pointing it to an email you
+control and ensure that you get the validation email.
+
 
 # Connecting To MySQL
 
@@ -84,14 +156,15 @@
     $ juju deploy mysql
 
 Additional details about the MySQL charm and configuration can be found in the
-[MySQL charm details](http://manage.jujucharms.com/charms/precise/mysql) page.
+[MySQL charm details](https://jujucharms.com/mysql/precise/) page.
 
 You'll then need to relate the Ghost blog service to the MySQL service.
 
     $ juju add-relation ghost mysql
 
-The charm will handle all settings necessary to use the MySQL database instead
-of the internal SQLite database.
+The charm will then handle setting up all configuration options necessary to use
+the MySQL database instead of the internal SQLite database.
+
 
 # Horizontal Scaling
 
@@ -101,36 +174,52 @@
 
     $ juju add-unit -n 1 ghost
 
-Now that you have more than one unit you will need to load balance between
-them. See [Load Balancing](#load-balancing) for more information.
-
-# Load Balancing
-
-This charm supports being load balanced and reverse proxied by [haproxy](http://manage.jujucharms.com/charms/precise/haproxy)
-or [apache2](http://manage.jujucharms.com/charms/precise/apache2).
-
-In order to load balance this service you will need to deploy one of the
-aforementioned charms:
-
-    $ juju deploy haproxy
-
-You will then need to unexpose the Ghost service:
-
-    $ juju unexpose ghost
-
-And change the port at which it listens from 80:
-
-    $ juju set ghost port=2368
-
-You now need to let your haproxy instance know about Ghost so that it can
-make the appropriate adjustments.
-
-    $ juju add-relation ghost haproxy
+Now that you have more than one unit you will need to ensure your posts are not
+stored locally on a single unit and you will need to be able to load balance
+between the multiple instances. See
+[Using A Load Balancer](#using-a-load-balancer) and
+[Connecting To MySQL](#connecting-to-mysql) for more information.
+
+
+# Colocating On A Single Machine
+
+By default, every time you deploy a service or create a new unit Juju will
+create a new instance on your cloud provider. This may be undesired due to
+hardware availability or budgeting. Juju also provides you an easy to use method
+to deploy all of these services to a smaller number of machines using the
+following syntax:
+
+    $ juju deploy --to=<machine number> <service name>
+
+    ex)
+
+    $ juju deploy --to=1 ghost
+
+Colocating can have unintended consequences if the multiple service were not
+designed to be deployed to the same machine. To get around this you're able to
+create LXC and KVM containers to deploy to. This gets into advanced Juju usage
+and more information can be found in the Juju documentation on
+[Deploying Charms](https://jujucharms.com/docs/charms-deploying#deploying-to-specific-machines-and-containers)
+
+# Deploying And Using The GUI
+
+Juju has a powerful graphical user interface which you can use to interact with
+your environment without having to use the CLI. In order to use the GUI in
+your environment you will need to deploy it:
+
+    $ juju deploy juju-gui
+
+Every command in this readme can be done using the GUI instead of the CLI. See
+[Juju GUI](https://jujucharms.com/juju-gui/trusty) for detailed information on
+the Juju GUI charm and how to use the GUI.
+
 
 # Contributing
 
 This charm wouldn't be where it is today without great contributions from
-others. Pull requests are accepted in the [ghost-charm repository](https://github.com/hatched/ghost-charm)
+others. Pull requests are accepted in the
+[ghost-charm repository](https://github.com/hatched/ghost-charm)
+
 
 # Bug Reports
 
@@ -141,6 +230,6 @@
 If you have found a bug with the ghost-charm itself they can be filed in the
 [ghost-charm repository](https://github.com/hatched/ghost-charm). Please include
 exact steps to reproduce the issue and be as detailed as possible, including
-what version of Ubuntu you're running, the version of this charm you have
+what version of Ubuntu you're running on, the version of this charm you have
 deployed, the cloud your environment is running on, any other charms deployed to
 the environment.
 
=== removed file 'assets/Ghost-0.4.2.zip'
 Binary files assets/Ghost-0.4.2.zip	2014-06-22 22:53:50 +0000 and assets/Ghost-0.4.2.zip	1970-01-01 00:00:00 +0000 differ
=== added file 'assets/Ghost-0.5.5.zip'
 Binary files assets/Ghost-0.5.5.zip	1970-01-01 00:00:00 +0000 and assets/Ghost-0.5.5.zip	2014-11-27 14:38:00 +0000 differ
=== modified file 'assets/config.js.template'
--- assets/config.js.template	2014-06-22 22:53:50 +0000
+++ assets/config.js.template	2014-11-27 14:38:00 +0000
@@ -7,6 +7,19 @@
     server: {
       host: '{{host}}',
       port: '{{port}}'
+    },
+    mail: {
+      {{from_address}}
+      {{amazon_ses_host}}
+      transport: 'SMTP',
+      options: {
+        service: '{{mail_service}}',
+        {{amazon_ses_port}}
+        auth: {
+          user: '{{mailserver_username}}',
+          pass: '{{mailserver_password}}'
+        }
+      }
     }
   }
 };
 
=== modified file 'assets/ghost.conf'
--- assets/ghost.conf	2014-06-22 22:53:50 +0000
+++ assets/ghost.conf	2014-11-27 14:38:00 +0000
@@ -1,6 +1,6 @@
 #/etc/init/ghost.conf
 description "Ghost Blog"
-author "Jeff Pihach <[e-mail]>"
+author "Jeff Pihach <[e-mail]>"
 
 setuid ubuntu
 
 
=== modified file 'config.yaml'
--- config.yaml	2014-05-22 05:51:19 +0000
+++ config.yaml	2014-11-27 14:38:00 +0000
@@ -11,3 +11,40 @@
     description: Port to be passed to node's net.Server listen().
     type: int
     default: 2368
+  mail_service:
+    description: |
+        Pick one of the supported email services to allow Ghost to send emails
+        for things like password recovery and new user acceptance. Valid options
+        will require the corresponding username and password fields filled out
+        below. The supported values are 'Mailgun', 'SES', and 'Gmail'.
+        An empty value will remove the configuration from Ghost.
+    type: string
+    default: ''
+  mailserver_username:
+    description: |
+        Username for the mail service chosen above. Information on where to find
+        these credentials can be found here: http://support.ghost.org/mail/ .
+    type: string
+    default: ''
+  mailserver_password:
+    description: |
+        Password for the mail service chosen above. Information on where to find
+        these credentials can be found here: http://support.ghost.org/mail/ .
+    type: string
+    default: ''
+  amazon_ses_host:
+    description: |
+        The host value for your Amazon SES account. This is only necessary if
+        you chose this option in the mail_service field above.
+    type: string
+    default: ''
+  from_address:
+    description: |
+        By default the ‘from’ address for mail sent from Ghost will be set to
+        "Blog Title <[e-mail]>" where 'Blog Title' is the title
+        you have set in settings, and 'your-ghost-blog.com' is the value from
+        the host configuration value above. You can override this value here.
+        Supported formats are '[e-mail]' or
+        'Custom Name <[e-mail]'.
+    type: string
+    default: ''
 
=== modified file 'hooks/config-changed'
--- hooks/config-changed	2014-06-22 22:53:50 +0000
+++ hooks/config-changed	2014-11-27 14:38:00 +0000
@@ -16,7 +16,7 @@
 function updateConfig(error, config) {
   try {
     exec('juju-log "Closing old port..."');
-    oldConfig = require('/var/www/ghost/config.js');
+    var oldConfig = require('/var/www/ghost/config.js');
     exec('close-port ' + oldConfig.production.server.port + '/TCP',
         function() {
           exec('juju-log "Old port closed."');
@@ -26,6 +26,7 @@
     exec('juju-log "config.js does not exist yet; port not closed"');
   }
   config = JSON.parse(config);
+  config = buildEmailConfig(config);
   utils.renderTemplate(
     config, 'config.js.template', '/var/www/ghost/config.js');
   exec('chown -R ubuntu:ubuntu /var/www/ghost');
@@ -38,4 +39,44 @@
     dbutils.configureSqlite();
 }
 
+/*
+  Generates the appropriate configuration object for the email provider.
+
+  @method buildEmailConfig
+  @param {Object} config The configuration field values.
+  @return {Object} A modified configuration object containing the correct email
+    configuration options.
+*/
+function buildEmailConfig(config) {
+  // Setting this here to nothing because it'll be set as the real value later
+  // on if needed.
+  config.amazon_ses_port = '';
+  // If we don't have a valid service name or it's an empty value then return
+  // with the currently modified values.
+  var valid_services = ['Mailgun', 'SES', 'Gmail'];
+  if (config.mail_service === '' ||
+      valid_services.indexOf(config.mail_service) < 0) {
+    // If the mail_service field is empty or unset then we want to disable
+    // the email server by leaving the provider field in the config blank.
+    exec(
+        'juju-log "The provided value `' + config.mail_service + '`' +
+        ' is not a valid configuration option for the `mail_service`.' +
+        ' See the configuration details for more information. Skipping' +
+        ' email provider');
+    config.mail_service = '';
+    return config;
+  }
+  // The remaining options require the entire key/value pair to be written
+  // into the template.
+  if (config.from_address !== '') {
+    config.from_address = 'from: ' + config.from_address + ',';
+  }
+  if (config.mail_service === 'SES') {
+    config.amazon_ses_host = 'host: ' + config.amazon_ses_host + ',';
+    config.amazon_ses_port = 'port: 465,';
+  }
+
+  return config;
+}
+
 exec('config-get --all --format=json', updateConfig);
 
=== modified file 'hooks/install'
--- hooks/install	2014-06-22 22:53:50 +0000
+++ hooks/install	2014-11-27 14:38:00 +0000
@@ -17,7 +17,7 @@
 chmod 644 /etc/init/ghost.conf
 # Unzip and move to it's proper location
 mkdir -p /var/www/ghost
-unzip -uo assets/Ghost-0.4.2.zip -d /var/www/ghost
+unzip -uo assets/Ghost-0.5.5.zip -d /var/www/ghost
 
 cd /var/www/ghost
 npm install --production
 
=== modified file 'revision'
--- revision	2014-06-22 22:53:50 +0000
+++ revision	2014-11-27 14:38:00 +0000
@@ -1,1 +1,1 @@
-5
+7
 
=== modified file 'utils/utils.js'
--- utils/utils.js	2013-11-26 03:43:17 +0000
+++ utils/utils.js	2014-11-27 14:38:00 +0000
@@ -7,7 +7,7 @@
   @method renderTemplateData
   @param {Object} data Config data
   @param {String} template The template filename
-    @param {String} filepath Path to render the template out to 
+  @param {String} filepath Path to render the template out to
 */
 function renderTemplate(data, template, filepath) {
   var fileData = fs.readFileSync(path.join('assets', template), 'utf8');