documentation/Running-Mastodon/Nanobox-Guide.md

Nanobox Guide

Nanobox 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, 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 (which requires a free Nanobox.io 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...