Merge pull request #129 from danhunsaker/feature/nanobox

Document Nanobox Usage

README.md

@@ -27,6 +27,7 @@
 - [Alternative: Running on Heroku](Running-Mastodon/Heroku-guide.md)
 - [Development guide](Running-Mastodon/Development-guide.md)
 - [Alternative: Development with Vagrant](Running-Mastodon/Vagrant-guide.md)
+- [Alternative: Development _and_ Production with Nanobox](Running-Mastodon/Nanobox-Guide.md)
 - [Administration guide](Running-Mastodon/Administration-guide.md)
 - [Maintenance Tasks](Running-Mastodon/Maintenance-Tasks.md)
 - [Tuning Mastodon](Running-Mastodon/Tuning.md)

Running-Mastodon/Nanobox-Guide.md

@@ -0,0 +1,82 @@
+Nanobox Guide
+=============
+
+[Nanobox](https://nanobox.io/) lets you develop apps in an environment identical
+to (or at least nearly so) the environment it will deploy to. It supports
+deploying to [multiple cloud providers](https://github.com/nanobox-io/nanobox-provider-integrations),
+so you have lots of choices about where your instance will run.
+
+Development
+-----------
+
+You will need Nanobox installed, along with Docker if you're on Linux (Windows
+and macOS can use Docker Native, but the bundled VirtualBox is more performant
+while the Docker team works out some filesystem speed issues). The process is
+simple - clone the repo, set a few variables with `nanobox evar add local
+{VARIABLE}={value}` (see below on which ones need to be set), and run `nanobox
+run` to get to a console. It will take some time to build your local dev
+environment, but once it's done, simply set up the DB using `bundle exec rake
+db:setup` as normal, and you're off.
+
+Production
+----------
+
+To deploy, you'll need to create an application in [your Nanobox dashboard](https://dashboard.nanobox.io/apps)
+(which requires a [Nanobox.io](https://dashboard.nanobox.io/users/register)
+account), clone the repo (if you haven't already set up the local development
+environment), set the new app as your deploy target with `nanobox remote add
+{app-name}`, set up the variables below using either `nanobox evar add
+{VARIABLE}={value}` or the app's dashboard, and then run `nanobox deploy`.
+
+Updating
+--------
+
+To update, simply grab the latest tagged version with `git fetch && git checkout
+$(git tag | tail -n 1)`, then re-run `nanobox deploy` - Nanobox automatically
+handles the rest.
+
+Environment Variables
+---------------------
+
+Mastodon will not run under Nanobox without first setting a handful of required
+variables:
+
+-   `RAILS_ENV` - set this to `production`, unless you're in development (this
+    value is treated as `development` if it isn't set)
+
+-   `NODE_ENV` - same as `RAILS_ENV`
+
+-   `PAPERCLIP_SECRET` - set to a random string of characters; you can use
+    `nanobox run bundle exec rake secret` to generate one
+
+-   `SECRET_KEY_BASE` - set to a random string of characters; you can use
+    `nanobox run bundle exec rake secret` to generate one
+
+-   `OTP_SECRET` - set to a random string of characters; you can use `nanobox
+    run bundle exec rake secret` to generate one
+
+You can also set some optional values, which should override the defaults in
+`.env.nanobox`:
+
+-   `LOCAL_DOMAIN` - set to whatever domain you want to use as your instance
+    name; defaults to `{app-name}.nanoapp.io`, which is provided by Nanobox for
+    use as a CNAME target
+
+-   `SINGLE_USER_MODE` - set this to `true` if you want to run a single-user
+    instance; default is unset
+
+And really any other setting you'd normally put into `.env.production`, such as:
+
+-   `SMTP_SERVER` - your SMTP server's address; default is blank
+
+-   `SMTP_PORT` - your SMTP server's port number; defaults to 587, which is
+    almost always correct
+
+-   `SMTP_LOGIN` - your SMTP username; default is blank
+
+-   `SMTP_PASSWORD` - your SMTP password; default is blank
+
+-   `SMTP_FROM_ADDRESS` - this instance's emails will come from this address;
+    defaults to `notifications@{app-name}.nanoapp.io`
+
+-   etc...