98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
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...
|