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