4 files changed, 121 insertions, 9 deletions
diff --git a/docs/Running-Mastodon/Administration-guide.md b/docs/Running-Mastodon/Administration-guide.md
index 1b9dc8630..dd69eb303 100644
--- a/docs/Running-Mastodon/Administration-guide.md
+++ b/docs/Running-Mastodon/Administration-guide.md
@@ -1,8 +1,16 @@
 Administration guide
-=================
+====================
 
 So, you have a working Mastodon instance... now what?
 
+## Turning into an admin
+
+The following rake task:
+
+    rake mastodon:make_admin USERNAME=alice
+
+Would turn the local user "alice" into an admin.
+
 ## Administration web interface
 
 A user that is designated as `admin = TRUE` in the database is able to access a suite of administration tools:
@@ -20,9 +28,10 @@ Your site settings are stored in the `settings` database table, and editable thr
 
 You are able to set the following settings:
 
+- Site title
 - 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
+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).
diff --git a/docs/Running-Mastodon/Heroku-guide.md b/docs/Running-Mastodon/Heroku-guide.md
index 6aa8be774..b66e56200 100644
--- a/docs/Running-Mastodon/Heroku-guide.md
+++ b/docs/Running-Mastodon/Heroku-guide.md
@@ -1,13 +1,13 @@
 Heroku guide
 ============
 
-[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://dashboard.heroku.com/new?button-url=https://github.com/tootsuite/mastodon&template=https://github.com/tootsuite/mastodon)
 
 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.
+  * You will want Amazon S3 for file storage. The only exception is for development purposes, where you may not care if files are not saved. 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
+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.
diff --git a/docs/Running-Mastodon/Production-guide.md b/docs/Running-Mastodon/Production-guide.md
index a6c776f09..a70f174d4 100644
--- a/docs/Running-Mastodon/Production-guide.md
+++ b/docs/Running-Mastodon/Production-guide.md
@@ -76,7 +76,7 @@ It is recommended to create a special user for mastodon on the server (you could
 ## General dependencies
 
     curl -sL https://deb.nodesource.com/setup_4.x | sudo bash -
-    sudo apt-get install imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev nodejs
+    sudo apt-get install imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev nodejs file
     sudo npm install -g yarn
 
 ## Redis
@@ -95,7 +95,6 @@ Setup a user and database for Mastodon:
 In the prompt:
 
     CREATE USER mastodon CREATEDB;
-    CREATE DATABASE mastodon_production OWNER mastodon;
     \q
 
 ## Rbenv
@@ -181,7 +180,7 @@ User=mastodon
 WorkingDirectory=/home/mastodon/live
 Environment="RAILS_ENV=production"
 Environment="DB_POOL=5"
-ExecStart=/home/mastodon/.rbenv/shims/bundle exec sidekiq -c 5 -q default -q mailers -q push
+ExecStart=/home/mastodon/.rbenv/shims/bundle exec sidekiq -c 5 -q default -q mailers -q pull -q push
 TimeoutSec=15
 Restart=always
 
@@ -210,7 +209,7 @@ Restart=always
 WantedBy=multi-user.target
 ```
 
-This allows you to `sudo systemctl enable mastodon-*.service` and `sudo systemctl start mastodon-*.service` to get things going.
+This allows you to `sudo systemctl enable /etc/systemd/system/mastodon-*.service` and `sudo systemctl start mastodon-web.service mastodon-sidekiq.service mastodon-streaming.service` to get things going.
 
 ## Cronjobs
 
diff --git a/docs/Running-Mastodon/Tuning.md b/docs/Running-Mastodon/Tuning.md
new file mode 100644
index 000000000..c4acb9927
--- /dev/null
+++ b/docs/Running-Mastodon/Tuning.md
@@ -0,0 +1,104 @@
+Tuning Mastodon
+===============
+
+Mastodon has three types of processes:
+
+- web
+- streaming API
+- background processing
+
+By default, the web type spawns two worker processes with 5 threads each, the streaming API is a single thread/process with 10 database pool connections, and background processing spawns one process with 5 threads.
+
+### Web
+
+The web process serves short-lived HTTP requests for most of the application. The following environment variables control it:
+
+- `WEB_CONCURRENCY` controls the number of worker processes
+- `MAX_THREADS` controls the number of threads per process
+
+The default is 2 workers with 5 threads each. Threads share the memory of their parent process. Different processes allocate their own memory each. Threads in Ruby are not native threads, so it's more or less: threads equal concurrency, processes equal parallelism. A larger number of threads maxes out your CPU first, a larger number of processes maxes out your RAM first.
+
+These values affect how many HTTP requests can be served at the same time. When not enough threads are available, requests are queued until they can be answered.
+
+For a single-user instance, 1 process with 5 threads should be more than enough.
+
+### Streaming API
+
+The streaming API handles long-lived HTTP and WebSockets connections, through which clients receive real-time updates. It is a single-threaded process. By default it has a database connection pool of 10, which means 10 different database queries can run *at the same time*. The database is not heavily used in the streaming API, only for initial authentication of the request, and for some special receiver-specific filter queries when receiving new messages. At the time of writing this value cannot be reconfigured, but mostly doesn't need to.
+
+If you need to scale up the streaming API, spawn more separate processes on different ports (e.g. 4000, 4001, 4003, etc) and load-balance between them with nginx.
+
+### Background processing
+
+Many tasks in Mastodon are delegated to background processing to ensure the HTTP requests are fast, and to prevent HTTP request aborts from affecting the execution of those tasks. Sidekiq is a single process, with a configurable numbero of threads. By default, it is 5. That means, 5 different jobs can be executed at the same time. Others will be queued until they can be processed.
+
+While the amount of threads in the web process affects the responsiveness of the Mastodon instance to the end-user, the amount of threads allocated to background processing affects how quickly posts can be delivered from the author to anyone else, how soon e-mails are sent out, etc.
+
+The amount of threads is not controlled by an environment variable in this case, but a command line argument in the invocation of Sidekiq:
+
+    bundle exec sidekiq -c 15 -q default -q mailers -q push
+
+Would start the sidekiq process with 15 threads. Please mind that each threads needs to be able to connect to the database, which means that the database pool needs to be large enough to support all the threads. The database pool size is controlled with the `DB_POOL` environment variable, and defaults to the value of `MAX_THREADS` (therefore, is 5 by default).
+
+You might notice that the above command specifies three queues to be processed:
+
+- "default" contains most tasks such as delivering messages to followers and processing incoming notifications from other instances
+- "mailers" contains tasks that send e-mails
+- "push" contains tasks that deliver messages to other instances
+
+If you wish, you could start three different processes for each queue, to ensure that even when there is a lot of tasks of one type, important tasks of other types still get executed in a timely manner.
+
+___
+
+### How to set environment variables
+#### With systemd
+
+In the `.service` file:
+
+```systemd
+...
+Environment="WEB_CONCURRENCY=1"
+Environment="MAX_THREADS=5"
+ExecStart="..."
+...
+```
+
+Don't forget to `sudo systemctl daemon-reload` before restarting the services so that the changes would take effect!
+
+#### With docker-compose
+
+Edit `docker-compose.yml`:
+
+```yml
+...
+  web:
+    restart: always
+    build: .
+    env_file: .env.production
+    environment:
+      - WEB_CONCURRENCY=1
+      - MAX_THREADS=5
+...
+```
+
+Re-create the containers with `docker-compose up -d` for the changes to take effect.
+
+You can also scale the number of containers per "service" (where service is "web", "sidekiq" and "streaming"):
+
+    docker-compose scale web=1 sidekiq=2 streaming=3
+
+Realistically the `docker-compose.yml` file needs to be modified a bit further for the above to work, because by default it wants to bind the web container to host port 3000 and streaming container to host port 4000, of either of which there is only one on the host system. However, if you change:
+
+```yml
+ports:
+  - "3000:3000"
+```
+
+to simply:
+
+```yml
+ports:
+  - "3000"
+```
+
+for each service respectively, Docker will allocate random host ports of the services, allowing multiple containers to run alongside each other. But it will be on you to look up which host ports those are (e.g. with `docker ps`), and they will be different on each container restart.