Merge branch 'mastodon:main' into main

content/en/admin/config.md

@@ -468,6 +468,13 @@ If set, all StatsD keys will be prefixed with this. Defaults to `Mastodon.produc
 
 If set to `true`, Mastodon will log some Sidekiq metrics into StatsD. Defaults to `false`.
 
+#### `ES_CA_FILE`
+
+Override Certificate Authority bundle file to use. Useful when using self-signed certificates.
+
+**Version history:**\
+4.3.0 - added
+
 ### SMTP email delivery {#smtp}
 
 #### `SMTP_SERVER`

content/en/admin/install.md

@@ -43,7 +43,7 @@ echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.o
 apt update
 apt install -y \
   imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \
-  g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \
+  g++ libprotobuf-dev protobuf-compiler pkg-config gcc autoconf \
   bison build-essential libssl-dev libyaml-dev libreadline6-dev \
   zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \
   nginx nodejs redis-server redis-tools postgresql postgresql-contrib \

content/en/admin/migrating.md

@@ -15,20 +15,28 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
 
 ## Basic steps {#basic-steps}
 
-1. Set up a new Mastodon server using the [Production Guide]({{< relref "install" >}}) (however, don’t run `mastodon:setup`).
+1. Set up a new Mastodon server using the [Production Guide]({{< relref "install" >}}) (however, don’t run `mastodon:setup` and only leave the PostgreSQL service running).
 2. Stop Mastodon on the old server (e.g. `systemctl stop 'mastodon-*.service'`).
 3. Dump and load the PostgreSQL database using the instructions below.
 4. Copy the `system/` files using the instructions below. (Note: if you’re using S3, you can skip this step.)
 5. Copy the `.env.production` file.
-6. Run `RAILS_ENV=production bundle exec rails assets:precompile` to compile Mastodon
-7. Run `RAILS_ENV=production ./bin/tootctl feeds build` to rebuild the home timelines for each user.
-8. Start Mastodon on the new server.
-9. Update your DNS settings to point to the new server.
-10. Update or copy your Nginx configuration, and re-run LetsEncrypt as necessary.
-11. Enjoy your new server!
+6. Save the Redis database, stop the Redis service, and copy the Redis database from `/var/lib/redis/` to the new server.
+7. Run `RAILS_ENV=production bundle exec rails assets:precompile` to compile Mastodon
+8. Start Mastodon and Redis on the new server.
+9. Run `RAILS_ENV=production ./bin/tootctl feeds build` to rebuild the home timelines for each user.
+10. Run `RAILS_ENV=production ./bin/tootctl search deploy` to rebuild your Elasticsearch indices (Note: if you are not using Elasticsearch, you can skip this step.)
+11. Update your DNS settings to point to the new server.
+12. Update or copy your Nginx configuration, and re-run LetsEncrypt as necessary.
+13. Enjoy your new server!
 
 ## Detailed steps {#detailed-steps}
 
+### Stop the Mastodon services  
+
+```bash
+systemctl stop 'mastodon-*.service'
+```
+
 ### What data needs to be migrated {#what-data-needs-to-be-migrated}
 
 At a high level, you’ll need to copy over the following:
@@ -36,16 +44,26 @@ At a high level, you’ll need to copy over the following:
 * The `~/live/public/system` directory, which contains user-uploaded images and videos (if using S3, you don’t need this)
 * The PostgreSQL database (using [pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html))
 * The `~/live/.env.production` file, which contains server config and secrets
+* The Redis database in the `/var/lib/redis/` directory, which contains unproccessed Sidekiq jobs.
 
 Less crucially, you’ll probably also want to copy the following for convenience:
 
 * The nginx config (under `/etc/nginx/sites-available/mastodon`)
+* The SSL certificates for your domain (under `/etc/letsencrypt/live/` if using LetsEncrypt)
 * The systemd config files (`/etc/systemd/system/mastodon-*.service`), which may contain your server tweaks and customizations
 * The PgBouncer configuration under `/etc/pgbouncer` (if you’re using it)
 
 ### Dump and load PostgreSQL {#dump-and-load-postgresql}
 
-Instead of running `mastodon:setup`, we’re going to create an empty PostgreSQL database using the `template0` database (which is useful when restoring a PostgreSQL dump, [as described in the pg_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)).
+Instead of running `mastodon:setup`, we’re going to create an empty PostgreSQL database using the `template0` database (which is useful when restoring a PostgreSQL dump, [as described in the pg_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)).  
+
+If you are using a password for your PostgreSQL user, you may want to configure the `mastodon` user on your new system to use the same password as your old system for convenience:
+
+```bash
+sudo -u postgres psql  
+ALTER USER mastodon WITH PASSWORD 'YOUR_PASSWORD';  
+\q
+```
 
 Run this as the `mastodon` user on your old system:
 
@@ -59,10 +77,10 @@ Copy the `backup.dump` file over, using `rsync` or `scp`. Then on the new system
 createdb -T template0 mastodon_production
 ```
 
-Then import it:
+Then import it (replace # in -j# with the number of CPUs in your system to improve restore performance):
 
 ```bash
-pg_restore -Fc -U mastodon -n public --no-owner --role=mastodon \
+pg_restore -Fc -j# -U mastodon -n public --no-owner --role=mastodon \
   -d mastodon_production backup.dump
 ```
 
@@ -76,10 +94,20 @@ This will probably take some time, and you’ll want to avoid re-copying unneces
 rsync -avz ~/live/public/system/ mastodon@example.com:~/live/public/system/
 ```
 
-You’ll want to re-run this if any of the files on the old server change.
+You’ll want to re-run this if any of the files on the old server change.  
 
 You should also copy over the `.env.production` file, which contains secrets.
 
+Now copy your Redis database over (adjust the location of your Redis database as needed). On your old machine, as the `root` user, run:
+
+```bash
+redis-cli
+SAVE
+EXIT
+systemctl stop redis-server.service
+rsync -avz /var/lib/redis/ root@example.com:/var/lib/redis
+```
+
 Optionally, you may copy over the nginx, systemd, and PgBouncer config files, or rewrite them from scratch.
 
 ### During migration {#during-migration}
@@ -90,5 +118,32 @@ You’ll probably also want to set the DNS TTL to something small (30-60 minutes
 
 ### After migrating {#after-migrating}
 
+Run the following commands as your mastodon user:  
+
+```bash
+RAILS_ENV=production bundle exec rails assets:precompile  
+```
+
+Now run the following commands as your root user:
+
+```bash
+systemctl daemon-reload
+systemctl start redis-server  
+systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming  
+systemctl restart nginx
+```
+
+Once your server is back online, you can rebuild the home feeds for users (this can take a long time depending on the number of users.)
+
+```bash
+RAILS_ENV=production ./bin/tootctl feeds build
+```
+
+If you use Elasticsearch, run the following command to rebuild the indices (this can take a long time depending on the number of statuses you have.)
+
+```bash
+RAILS_ENV=production ./bin/tootctl search deploy
+```
+
 You can check [whatsmydns.net](https://whatsmydns.net/) to see the progress of DNS propagation. To jumpstart the process, you can always edit your own `/etc/hosts` file to point to your new server so you can start playing around with it early.
 

content/en/admin/optional/captcha.md

@@ -14,7 +14,7 @@ With CAPTCHA enabled, new registrations will be required to complete a challenge
 
 {{< hint style="danger" >}}
 For some people, the use of a central CAPTCHA service may be a security and privacy concern.
-In addition, CAPTCHA can make the registration process significantly less accessible to some people.
+In addition, CAPTCHA can make the registration process significantly less accessible, particularly for individuals with visual impairments, such as those who are blind or have low vision.
 {{</ hint >}}
 
 Currently, hCaptcha is the only available provider supported by Mastodon.

content/en/client/intro.md

@@ -79,7 +79,7 @@ curl -X POST \
 
 ### Multiple values (Array) {#array}
 
-An array parameter must encoded using bracket notation, e.g. `array[]=foo&array[]=bar` would be translated into the following:
+An array parameter must be encoded using bracket notation. For example, `array[]=foo&array[]=bar` would be translated into the following:
 
 ```ruby
 array = [
@@ -120,7 +120,7 @@ As JSON, hashes are formatted like so:
 
 ### True-or-false (Booleans) {#boolean}
 
-A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values. When using JSON data, use the literals `true`, `false`, and `null` instead.
+A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`; considered to not be provided for empty strings; and considered to be true for all other values. When using JSON data, use the literals `true`, `false`, and `null` instead.
 
 ### Files {#file}
 
@@ -132,7 +132,7 @@ This can be combined with arrays as well.
 
 The Mastodon REST API will return JSON as the response text. It also returns HTTP headers which may be useful in handling the response, as well as an HTTP status code which should let you know how the server handled the request. The following HTTP status codes may be expected:
 
-* 200 = OK. The request was handled successfully.
-* 4xx = Client error. Your request was not correct. Most commonly, you may see 401 Unauthorized, 404 Not Found, 410 Gone, or 422 Unprocessed.
-* 5xx = Server error. Something went wrong while handling the request. Most commonly, you may see 503 Unavailable.
+- 200 = OK. The request was handled successfully.
+- 4xx = Client error. Your request was not correct. Most commonly, you may see 401 Unauthorized, 404 Not Found, 410 Gone, or 422 Unprocessed.
+- 5xx = Server error. Something went wrong while handling the request. Most commonly, you may see 503 Unavailable.
 

content/en/methods/reports.md

@@ -30,7 +30,8 @@ POST /api/v1/reports HTTP/1.1
 1.1 - added\
 2.3.0 - add `forward` parameter\
 3.5.0 - add `category` and `rule_ids` parameters\
-4.0.0 - `category` is now optional if `rule_ids` is provided
+4.0.0 - `category` is now optional if `rule_ids` is provided\
+4.2.0 - add `legal` category
 
 #### Request
 ##### Headers
@@ -53,7 +54,7 @@ forward
 : Boolean. If the account is remote, should the report be forwarded to the remote admin? Defaults to false.
 
 category
-: String. Specify if the report is due to `spam`, `violation` of enumerated instance rules, or some `other` reason. Defaults to `other`. Will be set to `violation` if `rule_ids[]` is provided (regardless of any category value you provide).
+: String. Specify if the report is due to `spam`, `legal` (illegal content), `violation` of enumerated instance rules, or some `other` reason. Defaults to `other`. Will be set to `violation` if `rule_ids[]` is provided (regardless of any category value you provide).
 
 rule_ids[]
 : Array of Integer. For `violation` category reports, specify the ID of the exact rules broken. Rules and their IDs are available via [GET /api/v1/instance/rules]({{< relref "methods/instance#rules" >}}) and [GET /api/v1/instance]({{< relref "methods/instance#get" >}}).