From 92a98f73aa8e6e7aff6cf31f8c8f237e4bd22475 Mon Sep 17 00:00:00 2001 From: Effy Elden Date: Sun, 22 Jan 2017 19:50:40 +1100 Subject: Add separate sections for Heroku and Vagrant deployments. Add guide for instance administration. Move 'Contribution guide' to 'Development guide'. --- docs/README.md | 2 +- docs/Running-Mastodon/Administration-guide.md | 28 ++++++++++++ docs/Running-Mastodon/Contribution-guide.md | 46 ------------------- docs/Running-Mastodon/Development-guide.md | 48 ++++++++++++++++++++ docs/Running-Mastodon/Heroku-guide.md | 13 ++++++ docs/Running-Mastodon/Vagrant-guide.md | 64 +++++++++++++++++++++++++++ 6 files changed, 154 insertions(+), 47 deletions(-) create mode 100644 docs/Running-Mastodon/Administration-guide.md delete mode 100644 docs/Running-Mastodon/Contribution-guide.md create mode 100644 docs/Running-Mastodon/Development-guide.md create mode 100644 docs/Running-Mastodon/Heroku-guide.md create mode 100644 docs/Running-Mastodon/Vagrant-guide.md diff --git a/docs/README.md b/docs/README.md index 7da680fab..000593761 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ Index ### Running Mastodon - [Production guide](Running-Mastodon/Production-guide.md) -- [Development guide](Running-Mastodon/Contribution-guide.md) +- [Development guide](Running-Mastodon/Development-guide.md) ### Contributing to Mastodon - [Sponsors](Contributing-to-Mastodon/Sponsors.md) diff --git a/docs/Running-Mastodon/Administration-guide.md b/docs/Running-Mastodon/Administration-guide.md new file mode 100644 index 000000000..1b9dc8630 --- /dev/null +++ b/docs/Running-Mastodon/Administration-guide.md @@ -0,0 +1,28 @@ +Administration guide +================= + +So, you have a working Mastodon instance... now what? + +## Administration web interface + +A user that is designated as `admin = TRUE` in the database is able to access a suite of administration tools: + +* View, edit, silence, or suspend users - https://yourmastodon.instance/admin/accounts +* View PubSubHubbub subscriptions - https://yourmastodon.instance/admin/pubsubhubbub +* View domain blocks - https://yourmastodon.instance/admin/domain_blocks +* Sidekiq dashboard - https://yourmastodon.instance/sidekiq +* PGHero dashboard for PostgreSQL - https://yourmastodon.instance/pghero +* Edit site settings - https://yourmastodon.instance/admin/settings + +## Site settings + +Your site settings are stored in the `settings` database table, and editable through the admin interface at https://yourmastodon.instance/admin/settings. + +You are able to set the following settings: + +- Contact username +- Contact email +- Site description +- Site extended description + +You may wish to use the extended description (shown at https://yourmastodon.instance/about/more ) to display content guidelines or a user agreement (see https://mastodon.social/about/more for an example). \ No newline at end of file diff --git a/docs/Running-Mastodon/Contribution-guide.md b/docs/Running-Mastodon/Contribution-guide.md deleted file mode 100644 index 60f418dec..000000000 --- a/docs/Running-Mastodon/Contribution-guide.md +++ /dev/null @@ -1,46 +0,0 @@ -Development guide -================= - -**Don't use Docker to do development**. It's a quick way to get Mastodon running in production, it's **really really inconvenient for development**. Normally in Rails development environment you get hot reloading of backend code and on-the-fly compilation of assets like JS and CSS, but you lose those benefits by compiling a Docker image. If you want to contribute to Mastodon, it is worth it to simply set up a proper development environment. - -In fact, all you need is described in the [production guide](Production-guide.md), **with the following exceptions**. You **don't** need: - -- Nginx -- SystemD -- An `.env.production` file. If you need to set any environment variables, you can use an `.env` file -- To prefix any commands with `RAILS_ENV=production` since the default environment is "development" anyway -- Any cronjobs - -The command to install project dependencies does not require any flags, i.e. simply - - bundle install - -By default the development environment wants to connect to a `mastodon_development` database on localhost using your user/ident to login to Postgres (i.e. not a md5 password) - -You can run Mastodon with: - - rails s - -And open `http://localhost:3000` in your browser. Background jobs run inline (aka synchronously) in the development environment, so you don't need to run a Sidekiq process. - -You can run tests with: - - rspec - -You can check localization status with: - - i18n-tasks health - -You can check code quality with: - - rubocop - -## Development tips - -You can use a localhost->world tunneling service like ngrok if you want to test federation, **however** that should not be your primary mode of operation. If you want to have a permanently federating server, set up a proper instance on a VPS with a domain name, and simply keep it up to date with your own fork of the project while doing development on localhost. - -Ngrok and similar services give you a random domain on each start up. This is good enough to test how the code you're working on handles real-world situations. But as soon as your domain changes, for everybody else concerned you're a different instance than before. - -Generally, federation bits are tricky to work on for exactly this reason - it's hard to test. And when you are testing with a disposable instance you are polluting the databases of the real servers you're testing against, usually not a big deal but can be annoying. The way I have handled this so far was thus: I have used ngrok for one session, and recorded the exchanges from its web interface to create fixtures and test suites. From then on I've been working with those rather than live servers. - -I advise to study the existing code and the RFCs before trying to implement any federation-related changes. It's not *that* difficult, but I think "here be dragons" applies because it's easy to break. diff --git a/docs/Running-Mastodon/Development-guide.md b/docs/Running-Mastodon/Development-guide.md new file mode 100644 index 000000000..80e6e2f94 --- /dev/null +++ b/docs/Running-Mastodon/Development-guide.md @@ -0,0 +1,48 @@ +Development guide +================= + +**Don't use Docker to do development**. It's a quick way to get Mastodon running in production, it's **really really inconvenient for development**. Normally in Rails development environment you get hot reloading of backend code and on-the-fly compilation of assets like JS and CSS, but you lose those benefits by compiling a Docker image. If you want to contribute to Mastodon, it is worth it to simply set up a proper development environment. + +In fact, all you need is described in the [production guide](Production-guide.md), **with the following exceptions**. You **don't** need: + +- Nginx +- SystemD +- An `.env.production` file. If you need to set any environment variables, you can use an `.env` file +- To prefix any commands with `RAILS_ENV=production` since the default environment is "development" anyway +- Any cronjobs + +The command to install project dependencies does not require any flags, i.e. simply + + bundle install + +By default the development environment wants to connect to a `mastodon_development` database on localhost using your user/ident to login to Postgres (i.e. not a md5 password) + +You can run Mastodon with: + + rails s + +And open `http://localhost:3000` in your browser. Background jobs run inline (aka synchronously) in the development environment, so you don't need to run a Sidekiq process. + +You can run tests with: + + rspec + +You can check localization status with: + + i18n-tasks health + +You can check code quality with: + + rubocop + +## Development tips + +You can use a localhost->world tunneling service like ngrok if you want to test federation, **however** that should not be your primary mode of operation. If you want to have a permanently federating server, set up a proper instance on a VPS with a domain name, and simply keep it up to date with your own fork of the project while doing development on localhost. + +Ngrok and similar services give you a random domain on each start up. This is good enough to test how the code you're working on handles real-world situations. But as soon as your domain changes, for everybody else concerned you're a different instance than before. + +Generally, federation bits are tricky to work on for exactly this reason - it's hard to test. And when you are testing with a disposable instance you are polluting the databases of the real servers you're testing against, usually not a big deal but can be annoying. The way I have handled this so far was thus: I have used ngrok for one session, and recorded the exchanges from its web interface to create fixtures and test suites. From then on I've been working with those rather than live servers. + +I advise to study the existing code and the RFCs before trying to implement any federation-related changes. It's not *that* difficult, but I think "here be dragons" applies because it's easy to break. + +If your development environment is running remotely (e.g. on a VPS or virtual machine), setting the `REMOTE_DEV` environment variable will swap your instance from using "letter opener" (which launches a local browser) to "letter opener web" (which collects emails and displays them at /letter_opener ). \ No newline at end of file diff --git a/docs/Running-Mastodon/Heroku-guide.md b/docs/Running-Mastodon/Heroku-guide.md new file mode 100644 index 000000000..6aa8be774 --- /dev/null +++ b/docs/Running-Mastodon/Heroku-guide.md @@ -0,0 +1,13 @@ +Heroku guide +============ + +[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy) + +Mastodon can theoretically run indefinitely on a free [Heroku](https://heroku.com) app. It should be noted this has limited testing and could have unpredictable results. + +1. Click the above button. +2. Fill in the options requested. + * You can use a .herokuapp.com domain, which will be simple to set up, or you can use a custom domain. If you want a custom domain and HTTPS, you will need to upgrade to a paid plan (to use Heroku's SSL features), or set up [CloudFlare](https://cloudflare.com) who offer free "Flexible SSL" (note: CloudFlare have some undefined limits on WebSockets. So far, no one has reported hitting concurrent connection limits). + * You will want Amazon S3 for file storage. The only exception is for development purposes, where you may not care if files are not saaved. Follow a guide online for creating a free Amazon S3 bucket and Access Key, then enter the details. + * If you want your Mastodon to be able to send emails, configure SMTP settings here (or later). Consider using [Mailgun](https://mailgun.com) or similar, who offer free plans that should suit your interests. +3. Deploy! The app should be set up, with a working web interface and database. You can change settings and manage versions from the Heroku dashboard. \ No newline at end of file diff --git a/docs/Running-Mastodon/Vagrant-guide.md b/docs/Running-Mastodon/Vagrant-guide.md new file mode 100644 index 000000000..a94478392 --- /dev/null +++ b/docs/Running-Mastodon/Vagrant-guide.md @@ -0,0 +1,64 @@ +Vagrant guide +============= + +A quick way to get a development environment up and running is with Vagrant. You will need recent versions of [Vagrant](https://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/) installed. + +## Basic setup + +Install the latest versions of Vagrant and VirtualBox for your operating systems, and then run: + + vagrant plugin install vagrant-hostsupdater + +This is optional, but will update your 'hosts' file when you start the virtual machine, allowing you to access the site at http://mastodon.dev (instead of http://localhost:3000). + +To create and provision a new virtual machine for Mastodon development: + + git clone git@github.com:tootsuite/mastodon.git + cd mastodon + vagrant up + +Running `vagrant up` for the first time will run provisioning, which will: + +- Download the Ubuntu 14.04 base image, if there isn't already a copy on your machine +- Create a new VirtualBox virtual machine from that image +- Run the provisioning script (located inside the Vagrantfile), which installs the system packages, Ruby gems, and JS modules required for Mastodon +- Run the startup script + +## Starting the server + +The Vagrant box will automatically start after provisioning. It can be started in future with `vagrant up` from the mastodon directory. + +Once the Ubuntu virtual machine has booted, it will run the startup script, which loads the environment variables from `.env.vagrant` and then runs `rails s -d -b 0.0.0.0`. This will start a Rails server. You can then access your development site at http://mastodon.dev (or at http://localhost:3000 if you haven't installed vagrants-hostupdater). + +To stop the server, simply run `vagrant halt`. + +## Using the server + +You should now have a working Mastodon instance, although it will not federate, as it is not publicly accessible. Should you need temporary federation for development and testing, see the Ngrok information in the [Development Guide](Development-guide.md). + +By default, your instance's ActionMailer will use "Letter Opener Web" for email. This means that any email that would normally be sent, will instead be stored, and accessible at http://mastodon.dev/letter_opener - you can use this to verify a registered user account. + +## Making changes/developing + +You are able to set environment variables, which are used for Mastodon configuration, by editing the `.env.vagrant` file. Any changes you make will take effect after a Vagrant restart. + +Vagrant has mounted your mastodon folder inside the virtual machine. This means that any change to the files in the folder(e.g. the Rails controllers or the React components in /app) should immediately take effect on the live server. This allows you to make and test changes, and create new commits, without ever needing to access the virtual machine. + +Should you need to access the virtual machine (for example, to manually restart the Rails process without restarting the box), run `vagrant ssh` from the mastodon folder. You will now be logged in as the `vagrant` user on the VirtualBox Ubuntu VM. You will want to `cd /vagrant` to see the app folder. + +## Debugging + +You can find the Rails server logs in in the `log` folder, which will often have the information you need. + +If your Mastodon instance or Vagrant box are really not behaving, you can re-run the provisioning process. Stop the box with `vagrant halt`, and then run `vagrant destroy` - this will delete the virtual machine. You may then run `vagrant up` to create a new box, and re-run provisioning. + +## Testing + +To run the `rspec` tests and `rubocop` style checker, you may either: + +* Install the relevant gems locally, or +* SSH into the virtual machine, `cd /vagrant`, and then run the commands + +## Support/help + +If you are confused, or having any issues with the above, the Mastodon IRC channel ( irc.freenode.net #mastodon ) is a good place to find assistance. \ No newline at end of file -- cgit