Setting up External Services

Pageflow uses three external Services to deal with the content for the presentations.

• Amazon S3 to host its Videos, Pictures and Audios.
• Zencoder to encode the content to fit the different formats needed.
• (In production environment) Amazon Cloudfront. A CDN to speed up access to the content.

Please create accounts for Amazon AWS and Zencoder.

Files that are uploaded to be used in Pageflow will be stored in an S3 bucket. Zencoder takes them from there, encodes the files and stores them in a second bucket. The website displays the content from this second bucket via Cloudfront.

Amazon S3

Thus, two Amazon S3 buckets are needed are needed for each environment.

• Main bucket for paperclip attachments and Zencoder to read from.
• Output bucket for Zencoder to write encoded files to.

For example:

• de-mycompany-pageflow-production
• de-mycompany-pageflow-production-out
• de-mycompany-pageflow-development
• de-mycompany-pageflow-development-out

You can add buckets for staging or other deployment environments. Multiple developers can share the same development buckets because files in this buckets are namespaced by the hostname of the developer's machine.

Hint: Its better to use dashes - than dots .. Dots can cause trouble when using https.

Bucket Configuration

• Add the permissions List for Everyone for both buckets.
  • Go to Properties -> Permission
  • Click "Add more permissions"
  • Select "Everyone" from drop-down and click "List"
  • Save
• Configure static website hosting for each bucket.
  • Go to Properties -> Static Website Hosting
  • Click "Enable Static Website Hosting".
  • Enter arbitrary string into the field "Index Document" (i.e. "foo", you can't save without this)
  • Click "Save"
• Grant Zencoder access to the buckets by adding the Zencoder Bucket Policies.
  • Go to Properties -> Permissions.
  • Click "Edit bucket policy".
  • Copy the correct JSON snippet from Zencoder Bucket Policies (Main or Output)
  • Replace the <main bucket> or <output bucket> placeholders with the full bucket name.
  • Click "Save"

Bandwidth Detection

Pageflow measures the download times of some static files to detect the bandwidth of the client.

The following files have to be placed in the Output ("-out") bucket:

• app/assets/images/pageflow/bandwidth_probe_large.png
• app/assets/images/pageflow/bandwidth_probe_small.png.

You will have to make these files publicly available. In the AWS Management Console, you can right-click them and choose 'Make Public'.

Configuring Paperclip

Pageflow uses the Paperclip gem, to upload files to S3. Edit the paperclip_s3_default_options settings in config/initializers/pageflow.rb:

  config.paperclip_s3_default_options.merge!(
    :s3_credentials => {
      :bucket => 'com-example-pageflow-development',
      :access_key_id => 'xxx',
      :secret_access_key => 'xxx',
      :s3_host_name => 's3-eu-west-1.amazonaws.com'
    },
    :s3_host_alias => 'com-example-pageflow.s3-website-eu-west-1.amazonaws.com',
    :s3_protocol => 'http'
  )

The required options are:

• bucket: The name of the main S3 bucket you chose above.
• access_key_id/secret_access_key: IAM credentials that grant write access to your main bucket.
• s3_host_name: The host name that shall be used on the server side to connect to the S3 REST API to upload files. The correct value depends on the region of your bucket. See the list of S3 AWS endpoints for more information. Important: Be sure NOT to enter an S3 Website endpoint (s3-website-*.amazonaws.com) here. Those enpoints can only be used for read access to files from your buckets.
• s3_host_alias: The host name that shall be used for image URLs in your published entries. This can be the hostname of some CDN you have configured to deliver files from your bucket. Even though use of a CDN is strongly recommended, you can also use an S3 Website endpoint here, as in the example above.
• s3_protocol: The protocol to use for public image URLs. Note that S3 Website endpoints only support http.

Refer to the Paperclip documentation for a full list of supported options.

Zencoder

Get your API Key from Zencoder and make sure it is used in the zencoder_options in config/initializers/pageflow.rb:

  config.zencoder_options.merge!(
    :api_key => 'xxx',
    :output_bucket => 'com-example-pageflow-out',
    :s3_host_alias => 'com-example-pageflow-out.s3-website-eu-west-1.amazonaws.com',
    :s3_protocol => 'http',
    :attachments_version => 'v1'
  )

Just like in the previous section, the s3_host_alias and s3_protocol settings are used to build video and audio URLs inside your published entries.

Note that Zencoder offers a special "Integration API Key" that can be used free of charge during development. Encoded files are cropped at five seconds.

Amazon Cloudfront

Create three distributions:

• one for each of the two S3 buckets
• one for which has the rails app itself as origin

Configure CNAMES and make sure they are used in config/initializers/pageflow.rb as s3_host_alias in production mode. Please see the inline docs and examples in config/initializers/pageflow.rb.