documentation/Running-Mastodon/Nanobox-Guide.md

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). Once Nanobox is
installed, the process is simple - clone the Mastodon 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 _free_
[Nanobox.io](https://dashboard.nanobox.io/users/register) account), clone the
Mastodon 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`. It will take a while to build
everything for deployment the first time, but the process handles itself.

Updating
--------

To update in production, simply grab the latest tagged version with `git fetch &&
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)`, then
re-run `nanobox deploy` - Nanobox automatically handles the rest. Updates should
be much faster than the initial deploy, since the build should be cached on your
own computer, and only changes are sent to the server itself. Either way, you
shouldn't see any downtime while the update process runs.

For development, grab the latest tagged version using the instructions above,
then use a `nanobox run` console to perform all the upgrade steps in the Release
Notes (except for installing dependencies - the `boxfile.yml` is updated as
needed to pull those in automatically).

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

-   `VAPID_PUBLIC_KEY` - generated by running `nanobox run bundle exec rake
    mastodon:webpush:generate_vapid_key`

-   `VAPID_PRIVATE_KEY` - generated at the same time as `VAPID_PUBLIC_KEY`

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...