Merge branch '0.17.0-docs' of github.com:metabase/metabase into 0.17.0-docs

docs/operations-guide/running-metabase-on-docker.md

@@ -44,6 +44,15 @@ In this scenario all you need to do is make sure you launch Metabase with the co
 Keep in mind that Metabase will be connecting from within your docker container, so make sure that either you're using a fully qualified hostname or that you've set a proper entry in your container's `/etc/hosts file`.
 
 
+### Setting the JVM Timezone
+
+It's best to set your JVM timezone to match the timezone you'd like all your reports to come in.  You can do this by simply specifying the `JVM_TIMEZONE` environment variable which is picked up by the Metabase launch script.  For example:
+
+    docker run -d -p 3000:3000 \
+      -e "JVM_TIMEZONE=US/Pacific" \
+      --name metabase metabase/metabase
+
+
 ### Additional custom settings
 
 While running Metabase on docker you can use any of the custom settings from [Customizing the Metabase Jetty Webserver](./start.md#customizing-the-metabase-jetty-webserver) by setting environment variables on your docker run command.

docs/operations-guide/running-metabase-on-elastic-beanstalk.md

@@ -3,6 +3,7 @@
 > [Upgrading to new versions of Metabase](#deploying-new-versions-of-metabase)  
 > [Retaining Metabase logs on S3](#retaining-metabase-logs)  
 > [Running Metabase over HTTPS](#running-metabase-over-https)  
+> [Setting the Java timezone](#setting-the-jvm-timezone)  
 > [Using Papertrail for logging](#running-metabase-with-papertrail-on-aws)  
 > [Protecting invalid hostname access](#protecting-against-invalid-hostname-access)
 
@@ -16,7 +17,7 @@ The Metabase team runs a number of production installations on AWS using Elastic
 
 Metabase provides an Elastic Beanstalk pre-configured launch url to help new installations getting started.  If you are starting fresh we recommend you follow this link to begin creating the Elastic Beanstalk deployment with a few choices pre-filled.
 
-[Launch Metabase on Elastic Beanstalk](http://downloads.metabase.com/v0.16.1/launch-aws-eb.html)
+[Launch Metabase on Elastic Beanstalk](http://downloads.metabase.com/v0.17.0/launch-aws-eb.html)
 
 The rest of this guide will follow each phase of the Elastic Beanstalk setup step-by-step.
 
@@ -53,7 +54,7 @@ When your environment type settings look like the above then go ahead and click
 
 The application version describes the exact binary you wish to deploy to your Elastic Beanstalk application.  Metabase provides a pre-built AWS Elastic Beanstalk application version which can be linked to directly.  Simply enter the following url in the `S3 URL` textbox:
 
-https://s3.amazonaws.com/downloads.metabase.com/v0.16.1/metabase-aws-eb.zip
+https://s3.amazonaws.com/downloads.metabase.com/v0.17.0/metabase-aws-eb.zip
 
 Leave all the settings under Deployment Limits on their defaults.  These settings won't impact Metabase.
 
@@ -186,7 +187,7 @@ Here's each step:
 1. Go to Elastic Beanstalk and select your `Metabase` application
 * Click on `Application Versions` on the left nav (you can also choose `Application Versions` from the dropdown at the top of the page)
 * Download the latest Metabase Elastic Beanstalk deployment file
-  * https://s3.amazonaws.com/downloads.metabase.com/v0.16.1/metabase-aws-eb.zip
+  * https://s3.amazonaws.com/downloads.metabase.com/v0.17.0/metabase-aws-eb.zip
 * Upload a new Application Version
 	* Click the `Upload` button on the upper right side of the listing
 		* Give the new version a name, ideally including the Metabase version number (e.g. v0.13.0)
@@ -263,6 +264,18 @@ Once your application is working properly over HTTPS we recommend setting an add
 * Scroll to the bottom of the page and click `Apply` in the lower right, then wait for your application to update.
 
 
+
+# Setting the JVM Timezone
+
+It's best to set your JVM timezone to match the timezone you'd like all your reports to come in.  You can do this by adding the `JAVA_TIMEZONE` environment variable.
+
+1. Click on `Configuration` on the left hand sidebar
+* Scroll down to `Software Configuration` under the _Web Tier_ section and click the gear icon to edit those settings.
+* Under `Environment Properties` add the following
+   * `JAVA_TIMEZONE` with a value such as `US/Pacific`
+* Scroll to the bottom of the page and click `Apply` in the lower right, then wait for your application to update.
+
+
 # Using Papertrail for logging on AWS
 
 This provides a simple way to use the Papertrail logging service for collecting the logs for you Metabase instance in an easy to read location.

docs/operations-guide/running-metabase-on-heroku.md

 # Running Metabase on Heroku
 
-Metabase is currently offering beta support for Heroku deployments and planning to improve support for Heroku going forward.  Metabase will deploy and run fine on Heroku but there are a few limitations.
+Heroku is a great place to evaluate Metabase and take it for a quick spin with just a click of a button and a couple minutes of waiting time.  If you decide to keep your Metabase running long term we recommend some upgrades as noted below to avoid limitations of the Heroku free tier.
 
 
 ### Launching Metabase
@@ -14,10 +14,19 @@ If you've got a Heroku account then all there is to do is follow this one-click
 This will launch a Heroku deployment using a github repository that Metabase maintains.
 
 
-### Known Issues
+### Upgrading beyond the `Free` tier
+
+Heroku is very kind and offers a free tier to be used for very small/non-critical workloads which is great if you just want to evaluate Metabase and see what it looks like.  If you like what you see and decide to use Metabase as an ongoing part of your analytics workflow we recommend these upgrades which are quite affordable and will allow you to fully utilize all of Metabase's capabilities without running into annoying limitations.
+
+1. Upgrade your dyno to the `Hobby` tier or one of the professional `Standard` 1x/2x dynos.  The most important reason for this is that your dyno will never sleep and that allows Metabase to run all of its background work such as sending Pulses, syncing metadata, etc, in a reliable fashion.
+
+2. Upgrade your Postgres database to the `Basic` package or for more peace of mind go for the `Standard 0` package.  The primary reason for this upgrade is to get more than the minimum number of database rows offered in the free tier (10k), which we've had some users exhaust within a week.  You'll also get better overall performance along with backups, which we think is worth it.
+
+
+### Known Limitations
 
  * Heroku’s 30 second timeouts on all web requests can cause a few issues if you happen to have longer running database queries.  Most people don’t run into this but be aware that it’s possible.
- * If you don’t access the application for a while Heroku will sleep your Metabase environment.  This prevents things like Pulses and Metabase background tasks from running when scheduled and at times makes the app appear to be slow when really it's just Heroku reloading your app.
+ * When using the `free` tier, if you don’t access the application for a while Heroku will sleep your Metabase environment.  This prevents things like Pulses and Metabase background tasks from running when scheduled and at times makes the app appear to be slow when really it's just Heroku reloading your app.  You can resolve this by upgrading to the `hobby` tier or higher.
 
 Now that you’ve installed Metabase, it’s time to [set it up and connect it to your database](../setting-up-metabase.md).
 

docs/operations-guide/start.md

@@ -7,8 +7,8 @@
 > [Running database migrations manually](#running-metabase-database-migrations-manually)  
 > [Backing up Metabase Application Data](#backing-up-metabase-application-data)  
 > [Customizing the Metabase Jetty Webserver](#customizing-the-metabase-jetty-webserver)  
-> [Changing password complexity](#changing-metabase-password-complexity)
-
+> [Changing password complexity](#changing-metabase-password-complexity)  
+> [Handling Timezones](#handling-timezones-in-metabase)
 
 # Installing and Running Metabase
 
@@ -231,3 +231,26 @@ The settings above can be used independently, so it's fine to use only one or th
 * `weak` = no character constraints
 * `normal` = at least 1 digit
 * `strong` = minimum 8 characters w/ 2 lowercase, 2 uppercase, 1 digit, and 1 special character
+
+
+# Handling timezones in Metabase
+
+Metabase does its best to ensure proper and accurate reporting in whatever timezone you desire, but timezones are a complicated beast so it's important to abide by some recommendations listed below to ensure your reports come out as intended.
+
+The following places where timezones are set can all impact the data you see:
+
+* `Database` - includes global database timezone settings, specific column type settings, and even individual data values.
+* `OS & JVM` - on whatever system is running Metabase the timezone settings of the Operating System as well as the Java Virtual Machine can impact your reports.
+* `Metabase` - inside Metabase the reporting timezone setting (if set) will influence how your data is reported.
+
+To ensure proper reporting it's important that timezones be set consistently in all places.  Metabase recommends the following settings:
+
+* Make sure all of your database columns are properly setup to include timezone awareness.
+* Unless you have a special need it's best to set your database reporting timezone to UTC and store all of your date/time related values in UTC.
+* Configure your JVM to use the same timezone you want to use for reporting, which ideally should also match the timezone of your database.
+* Set the Metabase `Report Timezone` to match the timezone you want to see your reports in, again, this should match the rest of the timezone settings you've made.
+
+
+Common Pitfalls:
+1. Your database is using date/time columns without any timezone information.  Typically when this happens your database will assume all the data is from whatever timezone the database is configured in or possible just default to UTC (check your database vendor to be sure).
+2. Your JVM timezone is not the same as your Metabase `Report Timezone` choice.  This is a very common issue and can be corrected by launching java with the `-Duser.timezone=<timezone>` option properly set to match your Metabase report timezone.