7 files changed, 191 insertions, 36 deletions
diff --git a/docs/Contributing-to-Mastodon/Sponsors.md b/docs/Contributing-to-Mastodon/Sponsors.md
index 3fee6e1e0..475791684 100644
--- a/docs/Contributing-to-Mastodon/Sponsors.md
+++ b/docs/Contributing-to-Mastodon/Sponsors.md
@@ -6,23 +6,16 @@ These people make the development of Mastodon possible through [Patreon](https:/
 **Extra special Patrons**
 
 - [World'sTallestLadder](https://mastodon.social/users/carcinoGeneticist)
-- [glocal](https://mastodon.social/users/glocal)
 - [Jimmy Tidey](https://mastodon.social/users/jimmytidey)
 - [Kurtis Rainbolt-Greene](https://mastodon.social/users/krainboltgreene)
 - [Kit Redgrave](https://socially.constructed.space/users/KitRedgrave)
-- [Zeiphner](https://mastodon.social/users/Zeipher)
+- [Zeipher](https://mastodon.social/users/Zeipher)
 - [Effy Elden](https://toot.zone/users/effy)
 - [Zoë Quinn](https://mastodon.social/users/zoequinn)
 
 **Thank you to the following people**
 
-- [Sophia Park](https://mastodon.social/users/sophia)
-- [WelshPixie](https://mastodon.social/users/WelshPixie)
-- [John Parker](https://mastodon.social/users/Middaparka)
-- [Christina Hendricks](https://mastodon.social/users/clhendricksbc)
-- [Jelle](http://jelv.nl)
 - [Harris Bomberguy](https://mastodon.social/users/Hbomberguy)
-- [Martin Tithonium](https://mastodon.social/users/tithonium)
 - [Edward Saperia](https://nwspk.com)
 - [Yoz Grahame](http://yoz.com/)
 - [Jenn Kaplan](https://gay.crime.team/users/jkap)
@@ -33,5 +26,21 @@ These people make the development of Mastodon possible through [Patreon](https:/
 - [Niels Roesen Abildgaard](http://hypesystem.dk/)
 - [Zatnosk](https://github.com/Zatnosk)
 - [Spex Bluefox](https://mastodon.social/users/Spex)
-- [Sam Waldie](https://mastodon.social/users/denjin)
 - [J. C. Holder](http://jcholder.com/)
+- [glocal](https://mastodon.social/users/glocal)
+- [jk](https://mastodon.social/users/jk)
+- [C418](https://mastodon.social/users/C418)
+- [halcy](https://icosahedron.website/users/halcy)
+- [Extropic](https://gnusocial.no/extropic)
+- [Pat Monaghan](http://iwrite.software/)
+- TBD
+- TBD
+- TBD
+- TBD
+- TBD
+- TBD
+- TBD
+- TBD
+- TBD
+- TBD
+- TBD
diff --git a/docs/README.md b/docs/README.md
index eb32e528c..abf6fcc4b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,6 +23,7 @@ Index
 - [Development guide](Running-Mastodon/Development-guide.md)
 - [Alternative: Development with Vagrant](Running-Mastodon/Vagrant-guide.md)
 - [Administration guide](Running-Mastodon/Administration-guide.md)
+- [Tuning Mastodon](Running-Mastodon/Tuning.md)
 
 ### Contributing to Mastodon
 - [Sponsors](Contributing-to-Mastodon/Sponsors.md)
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.
diff --git a/docs/Using-Mastodon/Apps.md b/docs/Using-Mastodon/Apps.md
index e350e5f95..67b14dc26 100644
--- a/docs/Using-Mastodon/Apps.md
+++ b/docs/Using-Mastodon/Apps.md
@@ -5,11 +5,13 @@ Some people have started working on apps for the Mastodon API. Here is a list of
 
 |App|Platform|Link|Developer(s)|
 |---|--------|----|------------|
-|Matodor|iOS/Android|<https://github.com/jeroensmeets/mastodon-app>|[@jeroensmeets@mastodon.social](https://mastodon.social/users/jeroensmeets)|
-|Tusky|Android|<https://github.com/Vavassor/Tusky>|[@Vavassor@mastodon.social](https://mastodon.social/users/Vavassor)|
-|Albatross|iOS||[@goldie_ice@mastodon.social](https://mastodon.social/users/goldie_ice)|
-|tootstream|command-line|<https://github.com/magicalraccoon/tootstream>|[@Raccoon@mastodon.social](https://mastodon.social/users/Raccoon)|
-|mastodroid|Android|<https://github.com/alin-rautoiu/mastodroid>||
-|Tooter|Chrome extension|<https://github.com/ineffyble/tooter>|[@effy@mastodon.social](https://mastodon.social/users/effy)|
+|[Tusky](https://play.google.com/store/apps/details?id=com.keylesspalace.tusky)|Android|<https://github.com/Vavassor/Tusky>|[@Vavassor@mastodon.social](https://mastodon.social/users/Vavassor)|
+|mastodroid|Android|<https://github.com/alin-rautoiu/mastodroid>|[@charlag@mastodon.social](https://mastodon.social/users/charlag)|
 |TootyFruity|Android|<https://play.google.com/store/apps/details?id=ch.kevinegli.tootyfruity221258>|[@eggplant@mastodon.social](https://mastodon.social/users/eggplant)|
+|11t|iOS/Android|<https://github.com/jeroensmeets/mastodon-app>|[@jeroensmeets@mastodon.social](https://mastodon.social/users/jeroensmeets)|
+|[Amaroq](https://itunes.apple.com/us/app/amarok-for-mastodon/id1214116200?ls=1&mt=8)|iOS|<https://itunes.apple.com/us/app/amarok-for-mastodon/id1214116200?ls=1&mt=8>|[@eurasierboy@mastodon.social](https://mastodon.social/users/eurasierboy)|
+|Albatross|iOS||[@goldie_ice@mastodon.social](https://mastodon.social/users/goldie_ice)|
+|Tooter|Chrome|<https://github.com/ineffyble/tooter>|[@effy@mastodon.social](https://mastodon.social/users/effy)|
+|tootstream|CLI|<https://github.com/magicalraccoon/tootstream>|[@Raccoon@mastodon.social](https://mastodon.social/users/Raccoon)|
+
 If you have a project like this, let me know so I can add it to the list!
diff --git a/docs/Using-Mastodon/List-of-Mastodon-instances.md b/docs/Using-Mastodon/List-of-Mastodon-instances.md
index ed3c74294..2f307b8a0 100644
--- a/docs/Using-Mastodon/List-of-Mastodon-instances.md
+++ b/docs/Using-Mastodon/List-of-Mastodon-instances.md
@@ -1,18 +1,24 @@
 List of Known Mastodon instances
 ==========================
 
-| Name | Theme/Notes, if applicable | Open Registrations |
-| -------------|-------------|---|
-| [mastodon.social](https://mastodon.social) |Flagship, quick updates|Yes|
-| [awoo.space](https://awoo.space) |Intentionally moderated, only federates with mastodon.social|Yes|
-| [social.tchncs.de](https://social.tchncs.de)|N/A|Yes|
-| [animalliberation.social](https://animalliberation.social) |Animal Rights|Yes|
-| [socially.constructed.space](https://socially.constructed.space) |Single user|No|
-| [epiktistes.com](https://epiktistes.com) |N/A|Yes|
-| [on.vu](https://on.vu) | Appears defunct|No|
-| [gay.crime.team](https://gay.crime.team) |N/A|Yes(?)|
-| [gnusocial.me](https://gnusocial.me) |Yes, it's a mastodon instance now|Yes|
-| [icosahedron.website](https://icosahedron.website/) |Icosahedron-themed (well, visually), open registration.|Yes|
-| [memetastic.space](https://memetastic.space) |Memes|Yes|
+There is also a list at [instances.mastodon.xyz](https://instances.mastodon.xyz) showing realtime information about instances.
+
+| Name | Theme/Notes, if applicable | Open Registrations | IPv6 |
+| -------------|-------------|---|---|
+| [mastodon.social](https://mastodon.social) |Flagship, quick updates|Yes|No|
+| [awoo.space](https://awoo.space) |Intentionally moderated, only federates with mastodon.social|Yes|No|
+| [social.tchncs.de](https://social.tchncs.de)|N/A|Yes|No|
+| [animalliberation.social](https://animalliberation.social) |Animal Rights|Yes|No|
+| [socially.constructed.space](https://socially.constructed.space) |Single user|No|No|
+| [epiktistes.com](https://epiktistes.com) |N/A|Yes|No|
+| [gay.crime.team](https://gay.crime.team) |the place for doin' gay crime online (please don't actually do crime here)|Yes|No|
+| [icosahedron.website](https://icosahedron.website/) |Icosahedron-themed (well, visually), open registration.|Yes|No|
+| [memetastic.space](https://memetastic.space) |Memes|Yes|No|
+| [social.diskseven.com](https://social.diskseven.com) |Single user|No|No (DNS entry but no response)|
+| [social.gestaltzerfall.net](https://social.gestaltzerfall.net) |Single user|No|No|
+| [mastodon.xyz](https://mastodon.xyz) |N/A|Yes|Yes|
+| [social.targaryen.house](https://social.targaryen.house) |N/A|Yes|No|
+| [social.mashek.net](https://social.mashek.net) |Themed and customised for Mashekstein Labs community. Selectively federates.|Yes|No|
+| [masto.themimitoof.fr](https://masto.themimitoof.fr) |N/A|Yes|Yes|
 
 Let me know if you start running one so I can add it to the list! (Alternatively, add it yourself as a pull request).
diff --git a/docs/Using-the-API/API.md b/docs/Using-the-API/API.md
index 07c1b25a9..54de0c0c0 100644
--- a/docs/Using-the-API/API.md
+++ b/docs/Using-the-API/API.md
@@ -19,6 +19,7 @@ API overview
   - Who reblogged/favourited a status
   - Following/unfollowing accounts
   - Blocking/unblocking accounts
+  - Getting instance information
   - Creating OAuth apps
 - [Entities](#entities)
   - Status
@@ -64,8 +65,8 @@ Returns a media object with an ID that can be attached when creating a status (s
 
 ### Retrieving a timeline
 
-**GET /api/v1/timelines/home**
-**GET /api/v1/timelines/public**
+**GET /api/v1/timelines/home**  
+**GET /api/v1/timelines/public**  
 **GET /api/v1/timelines/tag/:hashtag**
 
 Returns statuses, most recent ones first. Home timeline is statuses from people you follow, mentions timeline is all statuses that mention you. Public timeline is "whole known network", and the last is the hashtag timeline.
@@ -75,6 +76,10 @@ Query parameters:
 - `max_id` (optional): Skip statuses younger than ID (e.g. navigate backwards in time)
 - `since_id` (optional): Skip statuses older than ID (e.g. check for updates)
 
+Query parameters for public and tag timelines only:
+
+- `local` (optional): Only return statuses originating from this instance
+
 ### Notifications
 
 **GET /api/v1/notifications**
@@ -115,7 +120,14 @@ Returns authenticated user's account.
 
 **GET /api/v1/accounts/:id/statuses**
 
-Returns statuses by user. Same options as timeline are permitted.
+Returns statuses by user.
+
+Query parameters:
+
+- `max_id` (optional): Skip statuses younger than ID (e.g. navigate backwards in time)
+- `since_id` (optional): Skip statuses older than ID (e.g. check for updates)
+- `only_media` (optional): Only return statuses that have media attachments
+- `exclude_replies` (optional): Skip statuses that reply to other statuses
 
 **GET /api/v1/accounts/:id/following**
 
@@ -127,7 +139,7 @@ Returns users the given user is followed by.
 
 **GET /api/v1/accounts/relationships**
 
-Returns relationships (`following`, `followed_by`, `blocking`) of the current user to a list of given accounts.
+Returns relationships (`following`, `followed_by`, `blocking`, `muting`, `requested`) of the current user to a list of given accounts.
 
 Query parameters:
 
@@ -146,6 +158,14 @@ Query parameters:
 
 Returns accounts blocked by authenticated user.
 
+**GET /api/v1/mutes**
+
+Returns accounts muted by authenticated user.
+
+**GET /api/v1/follow_requests**
+
+Returns accounts that want to follow the authenticated user but are waiting for approval.
+
 **GET /api/v1/favourites**
 
 Returns statuses favourited by authenticated user.
@@ -188,25 +208,38 @@ Returns `ancestors` and `descendants` of the status.
 
 ### Who reblogged/favourited a status
 
-**GET /api/v1/statuses/:id/reblogged_by**
+**GET /api/v1/statuses/:id/reblogged_by**  
 **GET /api/v1/statuses/:id/favourited_by**
 
 Returns list of accounts.
 
 ### Following and unfollowing users
 
-**POST /api/v1/accounts/:id/follow**
+**POST /api/v1/accounts/:id/follow**  
 **POST /api/v1/accounts/:id/unfollow**
 
 Returns the updated relationship to the user.
 
 ### Blocking and unblocking users
 
-**POST /api/v1/accounts/:id/block**
+**POST /api/v1/accounts/:id/block**  
 **POST /api/v1/accounts/:id/unblock**
 
 Returns the updated relationship to the user.
 
+### Getting instance information
+
+**GET /api/v1/instance**
+
+Returns an object containing the `title`, `description`, `email` and `uri` of the instance. Does not require authentication.
+
+# Muting and unmuting users
+
+**POST /api/v1/accounts/:id/mute**  
+**POST /api/v1/accounts/:id/unmute**
+
+Returns the updated relationship to the user.
+
 ### OAuth apps
 
 **POST /api/v1/apps**
diff --git a/docs/Using-the-API/Push-notifications.md b/docs/Using-the-API/Push-notifications.md
index d98c8833a..fc373e723 100644
--- a/docs/Using-the-API/Push-notifications.md
+++ b/docs/Using-the-API/Push-notifications.md
@@ -1,4 +1,4 @@
 Push notifications
 ==================
 
-**Note: This push notification design turned out to not be fully operational on the side of Firebase. A different approach is in consideration**
+See <https://github.com/Gargron/tusky-api> for an example of how to create push notifications for a mobile app. It involves using the Mastodon streaming API on behalf of the app's users, as a sort of proxy.