Merge branch 'develop' into webhooks
This commit is contained in:
lain
commit
133fc64472
432 changed files with 13238 additions and 3502 deletions
|
|
@ -169,4 +169,18 @@ This forcibly removes any enabled MRF that does not exist and will fix the abili
|
|||
=== "From Source"
|
||||
```sh
|
||||
mix pleroma.config fix_mrf_policies
|
||||
```
|
||||
```
|
||||
|
||||
## Remove non-whitelisted configs from the database
|
||||
|
||||
This removes any configuration value that is not explicitly whitelisted by `:pleroma, :database_config_whitelist`. Might be useful after updating the whitelist.
|
||||
|
||||
=== "OTP"
|
||||
```sh
|
||||
./bin/pleroma_ctl config filter_whitelisted
|
||||
```
|
||||
|
||||
=== "From Source"
|
||||
```sh
|
||||
mix pleroma.config filter_whitelisted
|
||||
```
|
||||
|
|
|
|||
47
docs/administration/dashboards.md
Normal file
47
docs/administration/dashboards.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# Dashboards
|
||||
|
||||
Pleroma comes with two types of backend dashboards viewable to instance administrators:
|
||||
|
||||
* [Phoenix LiveDashboard](https://hexdocs.pm/phoenix_live_dashboard/Phoenix.LiveDashboard.html) - A general system oriented dashboard for viewing statistics about Pleroma resource consumption, Pleroma's database and Pleroma's job processor (Oban).
|
||||
* [Oban Web](https://hexdocs.pm/oban_web/overview.html) - A dashboard specific to Oban for viewing Oban statistics, managing jobs and job queues.
|
||||
|
||||
!!! note
|
||||
Both dashboards require working Websockets.
|
||||
If your browser or web server don't support Websockets, both dashboards either won't update or will not display all information.
|
||||
|
||||
## Phoenix LiveDashboard
|
||||
|
||||
Instance administrators can access this dashboard at `/pleroma/live_dashboard`, giving a simple overview of software versions including Erlang and Elixir versions, instance uptime and resource consumption.
|
||||
|
||||
This dashboard gives insights into the current state of the BEAM VM running Pleroma code and database statistics including basic diagnostics.
|
||||
It can be useful for troubleshooting of some issues namely regarding database performance.
|
||||
|
||||
### Relevant dashboard tabs
|
||||
|
||||
* Home - A general overview of system information including software versions, uptime and memory BEAM memory consumption.
|
||||
* OS Data - Information about the OS and system such as CPU load, memory usage and disk usage.
|
||||
* Ecto Stats - Information about the Pleroma database.
|
||||
- Diagnose - Basic database diagnostics, including a `bloat` warning when an index or a table have excessive bloat, which can lead to bad database performance.
|
||||
- Bloat - A table showing size of "bloat" (unused wasted space) in database tables and indexes. Very high bloat size in the `activities` and `objects` tables can lead to bad performance especially on slower disks such as on most VPS providers.
|
||||
- Db settings - A small list of PostgreSQL settings mostly relevant to database performance.
|
||||
- Total table size - Shows sizes of all database tables including indexes sorted by size, useful for quickly checking overall database size.
|
||||
- Long running queries - A list of of slow database queries and their duration. Multiple entries with duration in multiple seconds indicate a slowly performing database.
|
||||
* Oban - Shows a list of all Oban jobs.
|
||||
|
||||
!!! note
|
||||
The DB bloat warning for `index 'oban_jobs::oban_jobs_args_index'` in Ecto Stats can be safely ignored.
|
||||
|
||||
## Oban Web
|
||||
|
||||
An advanced dashboard and management console viewable to instance administrators specifically for Oban, Pleroma's job processor.
|
||||
It allows managing jobs, including force retrying failed jobs and job deletion.
|
||||
It can be accessed at `/pleroma/oban`.
|
||||
|
||||
!!! danger
|
||||
This dashboard is very powerful! If you are unsure what a certain feature does, don't use it.
|
||||
Changing individual queue state/settings in the "Queues" view is heavily discouraged.
|
||||
|
||||
* Shows a real time chart of either a number of executed jobs, or job execution/wait time per a given time frame and the state/queue/worker.
|
||||
* Shows a list of jobs in each state, their argument, number of attempts and execution/scheduled time.
|
||||
* Selecting one or multiple jobs in the list allows performing actions like canceling/deleting and retrying.
|
||||
* Clicking on a job shows a detailed view including the full argument, when it was inserted, information about its attempts, and performing actions on it.
|
||||
|
|
@ -904,21 +904,31 @@ config :logger, :console,
|
|||
|
||||
### RUM indexing for full text search
|
||||
|
||||
!!! warning
|
||||
It is recommended to use PostgreSQL v11 or newer. We have seen some minor issues with lower PostgreSQL versions.
|
||||
|
||||
* `rum_enabled`: If RUM indexes should be used. Defaults to `false`.
|
||||
|
||||
RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. While they may eventually be mainlined, for now they have to be installed as a PostgreSQL extension from https://github.com/postgrespro/rum.
|
||||
RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. While they may eventually be mainlined, for now they have to be installed as a PostgreSQL extension from [https://github.com/postgrespro/rum](https://github.com/postgrespro/rum).
|
||||
|
||||
Their advantage over the standard GIN indexes is that they allow efficient ordering of search results by timestamp, which makes search queries a lot faster on larger servers, by one or two orders of magnitude. They take up around 3 times as much space as GIN indexes.
|
||||
Their advantage over the standard GIN indexes is that they allow efficient ordering of search results by timestamp, which makes search queries a lot faster on larger servers, by one or two orders of magnitude. They take up around 3-4 times as much space as GIN indexes.
|
||||
|
||||
To enable them, both the `rum_enabled` flag has to be set and the following special migration has to be run:
|
||||
|
||||
`mix ecto.migrate --migrations-path priv/repo/optional_migrations/rum_indexing/`
|
||||
* Source install:
|
||||
- Stop Pleroma
|
||||
- `mix ecto.migrate --migrations-path priv/repo/optional_migrations/rum_indexing/`
|
||||
* OTP install:
|
||||
- Stop Pleroma
|
||||
- `pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/`
|
||||
|
||||
This will probably take a long time.
|
||||
|
||||
!!! note
|
||||
It is recommended to `VACUUM FULL` the objects table after the migration has completed, to do that run:
|
||||
```
|
||||
# sudo -Hu postgres vacuumdb --full --analyze -t objects <pleroma DB name>
|
||||
```
|
||||
|
||||
Now you can start Pleroma back up.
|
||||
|
||||
## Alternative client protocols
|
||||
|
||||
### BBS / SSH access
|
||||
|
|
@ -1122,8 +1132,9 @@ Boolean, enables/disables in-database configuration. Read [Transferring the conf
|
|||
|
||||
List of valid configuration sections which are allowed to be configured from the
|
||||
database. Settings stored in the database before the whitelist is configured are
|
||||
still applied, so it is suggested to only use the whitelist on instances that
|
||||
have not migrated the config to the database.
|
||||
still applied. Consider running the `mix pleroma.config filter_whitelisted` task
|
||||
after updating the whitelist. Read [Remove non-whitelisted configs from the database](../administration/CLI_tasks/config.md#remove-non-whitelisted-configs-from-the-database)
|
||||
for more information.
|
||||
|
||||
Example:
|
||||
```elixir
|
||||
|
|
|
|||
|
|
@ -16,7 +16,9 @@ location /proxy {
|
|||
```
|
||||
Also add the following on top of the configuration, outside of the `server` block:
|
||||
```
|
||||
proxy_cache_path /tmp/pleroma-media-cache levels=1:2 keys_zone=pleroma_media_cache:10m max_size=10g inactive=720m use_temp_path=off;
|
||||
# Note: The cache directory must exist and be writable by nginx.
|
||||
# If nginx runs in a chroot, create it inside the chroot.
|
||||
proxy_cache_path /var/tmp/pleroma-media-cache levels=1:2 keys_zone=pleroma_media_cache:10m max_size=10g inactive=720m use_temp_path=off;
|
||||
```
|
||||
If you came here from one of the installation guides, take a look at the example configuration `/installation/pleroma.nginx`, where this part is already included.
|
||||
|
||||
|
|
|
|||
|
|
@ -665,6 +665,7 @@ Status: 404
|
|||
- *optional* `limit`: **integer** the number of records to retrieve
|
||||
- *optional* `page`: **integer** page number
|
||||
- *optional* `page_size`: **integer** number of log entries per page (default is `50`)
|
||||
- *optional* `assigned_account`: **string** assigned account ID
|
||||
- Response:
|
||||
- On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
|
||||
- On success: JSON, returns a list of reports, where:
|
||||
|
|
@ -749,6 +750,7 @@ Status: 404
|
|||
"url": "https://pleroma.example.org/users/lain",
|
||||
"username": "lain"
|
||||
},
|
||||
"assigned_account": null,
|
||||
"content": "Please delete it",
|
||||
"created_at": "2019-04-29T19:48:15.000Z",
|
||||
"id": "9iJGOv1j8hxuw19bcm",
|
||||
|
|
@ -868,6 +870,37 @@ Status: 404
|
|||
]
|
||||
```
|
||||
|
||||
- Response:
|
||||
- On failure:
|
||||
- 400 Bad Request, JSON:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
`id`, // report id
|
||||
`error` // error message
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
- On success: `204`, empty response
|
||||
|
||||
## `POST /api/v1/pleroma/admin/reports/assign_account`
|
||||
|
||||
### Assign account to one or multiple reports
|
||||
|
||||
- Params:
|
||||
|
||||
```json
|
||||
`reports`: [
|
||||
{
|
||||
`id`, // required, report id
|
||||
`nickname` // account nickname, use null to unassign account
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
- Response:
|
||||
- On failure:
|
||||
- 400 Bad Request, JSON:
|
||||
|
|
|
|||
|
|
@ -66,9 +66,9 @@ Returned data:
|
|||
"username": "somenick",
|
||||
...
|
||||
},
|
||||
"id" : "1",
|
||||
"unread" : 2,
|
||||
"last_message" : {...}, // The last message in that chat
|
||||
"id": "1",
|
||||
"unread": 2,
|
||||
"last_message": {...}, // The last message in that chat
|
||||
"updated_at": "2020-04-21T15:11:46.000Z"
|
||||
}
|
||||
```
|
||||
|
|
@ -93,8 +93,8 @@ Returned data:
|
|||
"username": "somenick",
|
||||
...
|
||||
},
|
||||
"id" : "1",
|
||||
"unread" : 0,
|
||||
"id": "1",
|
||||
"unread": 0,
|
||||
"updated_at": "2020-04-21T15:11:46.000Z"
|
||||
}
|
||||
```
|
||||
|
|
@ -111,7 +111,7 @@ The modified chat message
|
|||
|
||||
### Getting a list of Chats
|
||||
|
||||
`GET /api/v1/pleroma/chats`
|
||||
`GET /api/v2/pleroma/chats`
|
||||
|
||||
This will return a list of chats that you have been involved in, sorted by their
|
||||
last update (so new chats will be at the top).
|
||||
|
|
@ -119,6 +119,7 @@ last update (so new chats will be at the top).
|
|||
Parameters:
|
||||
|
||||
- with_muted: Include chats from muted users (boolean).
|
||||
- pinned: Include only pinned chats (boolean).
|
||||
|
||||
Returned data:
|
||||
|
||||
|
|
@ -130,16 +131,16 @@ Returned data:
|
|||
"username": "somenick",
|
||||
...
|
||||
},
|
||||
"id" : "1",
|
||||
"unread" : 2,
|
||||
"last_message" : {...}, // The last message in that chat
|
||||
"id": "1",
|
||||
"unread": 2,
|
||||
"last_message": {...}, // The last message in that chat
|
||||
"updated_at": "2020-04-21T15:11:46.000Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
The recipient of messages that are sent to this chat is given by their AP ID.
|
||||
No pagination is implemented for now.
|
||||
The usual pagination options are implemented.
|
||||
|
||||
### Getting the messages for a Chat
|
||||
|
||||
|
|
@ -226,6 +227,32 @@ Deleting a chat message for given Chat id works like this:
|
|||
|
||||
Returned data is the deleted message.
|
||||
|
||||
### Pinning a chat
|
||||
|
||||
Pinning a chat works like this:
|
||||
|
||||
`POST /api/v1/pleroma/chats/:id/pin`
|
||||
|
||||
Returned data:
|
||||
|
||||
```json
|
||||
{
|
||||
"account": {
|
||||
"id": "someflakeid",
|
||||
"username": "somenick",
|
||||
...
|
||||
},
|
||||
"id": "1",
|
||||
"unread": 0,
|
||||
"updated_at": "2020-04-21T15:11:46.000Z",
|
||||
"pinned": true,
|
||||
}
|
||||
```
|
||||
|
||||
To unpin a pinned chat, use:
|
||||
|
||||
`POST /api/v1/pleroma/chats/:id/unpin`
|
||||
|
||||
### Notifications
|
||||
|
||||
There's a new `pleroma:chat_mention` notification, which has this form. It is not given out in the notifications endpoint by default, you need to explicitly request it with `include_types[]=pleroma:chat_mention`:
|
||||
|
|
|
|||
|
|
@ -39,11 +39,13 @@ Has these additional fields under the `pleroma` object:
|
|||
- `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint.
|
||||
- `parent_visible`: If the parent of this post is visible to the user or not.
|
||||
- `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise.
|
||||
- `quotes_count`: the count of status quotes.
|
||||
- `non_anonymous`: true if the source post specifies the poll results are not anonymous. Currently only implemented by Smithereen.
|
||||
- `bookmark_folder`: the ID of the folder bookmark is stored within (if any).
|
||||
- `list_id`: the ID of the list the post is addressed to (if any, only returned to author).
|
||||
|
||||
Has these additional fields under the `poll.pleroma` object:
|
||||
|
||||
- `non_anonymous`: true if the source post specifies the poll results are not anonymous. Currently only implemented by Smithereen.
|
||||
|
||||
The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes:
|
||||
|
||||
- `content_type`: The content type of the status source.
|
||||
|
|
@ -72,7 +74,7 @@ Pleroma does not process remote images and therefore cannot include fields such
|
|||
|
||||
The `GET /api/v1/bookmarks` endpoint accepts optional parameter `folder_id` for bookmark folder ID.
|
||||
|
||||
The `POST /api/v1/statuses/:id/bookmark` endpoint accepts optional parameter `folder_id` for bookmark folder ID.
|
||||
The `POST /api/v1/statuses/:id/bookmark` endpoint accepts optional parameter `folder_id` for bookmark folder ID. Bookmarking an already bookmarked post will update the folder association, or remove it if `folder_id` is omitted or `null`.
|
||||
|
||||
## Accounts
|
||||
|
||||
|
|
@ -98,6 +100,9 @@ Endpoints which accept `with_relationships` parameter:
|
|||
- `/api/v1/accounts/:id/followers`
|
||||
- `/api/v1/accounts/:id/following`
|
||||
- `/api/v1/mutes`
|
||||
- `/api/v1/blocks`
|
||||
- `/api/v1/search`
|
||||
- `/api/v2/search`
|
||||
|
||||
Has these additional fields under the `pleroma` object:
|
||||
|
||||
|
|
@ -122,8 +127,6 @@ Has these additional fields under the `pleroma` object:
|
|||
- `notification_settings`: object, can be absent. See `/api/v1/pleroma/notification_settings` for the parameters/keys returned.
|
||||
- `accepts_chat_messages`: boolean, but can be null if we don't have that information about a user
|
||||
- `favicon`: nullable URL string, Favicon image of the user's instance
|
||||
- `avatar_description`: string, image description for user avatar, defaults to empty string
|
||||
- `header_description`: string, image description for user banner, defaults to empty string
|
||||
|
||||
### Source
|
||||
|
||||
|
|
|
|||
|
|
@ -684,11 +684,13 @@ Audio scrobbling in Pleroma is **deprecated**.
|
|||
### Creates a new Listen activity for an account
|
||||
* Method `POST`
|
||||
* Authentication: required
|
||||
* OAuth scope: `write:scrobbles`
|
||||
* Params:
|
||||
* `title`: the title of the media playing
|
||||
* `album`: the album of the media playing [optional]
|
||||
* `artist`: the artist of the media playing [optional]
|
||||
* `length`: the length of the media playing [optional]
|
||||
* `external_link`: a URL referencing the media playing [optional]
|
||||
* Response: the newly created media metadata entity representing the Listen activity
|
||||
|
||||
# Emoji Reactions
|
||||
|
|
|
|||
|
|
@ -1,226 +0,0 @@
|
|||
# Installing on Arch Linux
|
||||
|
||||
{! backend/installation/otp_vs_from_source_source.include !}
|
||||
|
||||
## Installation
|
||||
|
||||
This guide will assume that you have administrative rights, either as root or a user with [sudo permissions](https://wiki.archlinux.org/index.php/Sudo). If you want to run this guide with root, ignore the `sudo` at the beginning of the lines, unless it calls a user like `sudo -Hu pleroma`; in this case, use `su <username> -s $SHELL -c 'command'` instead.
|
||||
|
||||
### Required packages
|
||||
|
||||
* `postgresql`
|
||||
* `elixir`
|
||||
* `git`
|
||||
* `base-devel`
|
||||
* `cmake`
|
||||
* `file`
|
||||
|
||||
#### Optional packages used in this guide
|
||||
|
||||
* `nginx` (preferred, example configs for other reverse proxies can be found in the repo)
|
||||
* `certbot` (or any other ACME client for Let’s Encrypt certificates)
|
||||
* `ImageMagick`
|
||||
* `ffmpeg`
|
||||
* `exiftool`
|
||||
|
||||
### Prepare the system
|
||||
|
||||
* First update the system, if not already done:
|
||||
|
||||
```shell
|
||||
sudo pacman -Syu
|
||||
```
|
||||
|
||||
* Install some of the above mentioned programs:
|
||||
|
||||
```shell
|
||||
sudo pacman -S git base-devel elixir cmake file
|
||||
```
|
||||
|
||||
### Install PostgreSQL
|
||||
|
||||
[Arch Wiki article](https://wiki.archlinux.org/index.php/PostgreSQL)
|
||||
|
||||
* Install the `postgresql` package:
|
||||
|
||||
```shell
|
||||
sudo pacman -S postgresql
|
||||
```
|
||||
|
||||
* Initialize the database cluster:
|
||||
|
||||
```shell
|
||||
sudo -iu postgres initdb -D /var/lib/postgres/data
|
||||
```
|
||||
|
||||
* Start and enable the `postgresql.service`
|
||||
|
||||
```shell
|
||||
sudo systemctl enable --now postgresql.service
|
||||
```
|
||||
|
||||
### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md))
|
||||
|
||||
```shell
|
||||
sudo pacman -S ffmpeg imagemagick perl-image-exiftool
|
||||
```
|
||||
|
||||
### Install PleromaBE
|
||||
|
||||
* Add a new system user for the Pleroma service:
|
||||
|
||||
```shell
|
||||
sudo useradd -r -s /bin/false -m -d /var/lib/pleroma -U pleroma
|
||||
```
|
||||
|
||||
**Note**: To execute a single command as the Pleroma system user, use `sudo -Hu pleroma command`. You can also switch to a shell by using `sudo -Hu pleroma $SHELL`. If you don’t have and want `sudo` on your system, you can use `su` as root user (UID 0) for a single command by using `su -l pleroma -s $SHELL -c 'command'` and `su -l pleroma -s $SHELL` for starting a shell.
|
||||
|
||||
* Git clone the PleromaBE repository and make the Pleroma user the owner of the directory:
|
||||
|
||||
```shell
|
||||
sudo mkdir -p /opt/pleroma
|
||||
sudo chown -R pleroma:pleroma /opt/pleroma
|
||||
sudo -Hu pleroma git clone -b stable https://git.pleroma.social/pleroma/pleroma /opt/pleroma
|
||||
```
|
||||
|
||||
* Change to the new directory:
|
||||
|
||||
```shell
|
||||
cd /opt/pleroma
|
||||
```
|
||||
|
||||
* Install the dependencies for Pleroma and answer with `yes` if it asks you to install `Hex`:
|
||||
|
||||
```shell
|
||||
sudo -Hu pleroma mix deps.get
|
||||
```
|
||||
|
||||
* Generate the configuration: `sudo -Hu pleroma MIX_ENV=prod mix pleroma.instance gen`
|
||||
* Answer with `yes` if it asks you to install `rebar3`.
|
||||
* This may take some time, because parts of pleroma get compiled first.
|
||||
* After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`.
|
||||
|
||||
* Check the configuration and if all looks right, rename it, so Pleroma will load it (`prod.secret.exs` for productive instance, `dev.secret.exs` for development instances):
|
||||
|
||||
```shell
|
||||
sudo -Hu pleroma mv config/{generated_config.exs,prod.secret.exs}
|
||||
```
|
||||
|
||||
* The previous command creates also the file `config/setup_db.psql`, with which you can create the database:
|
||||
|
||||
```shell
|
||||
sudo -Hu postgres psql -f config/setup_db.psql
|
||||
```
|
||||
|
||||
* Now run the database migration:
|
||||
|
||||
```shell
|
||||
sudo -Hu pleroma MIX_ENV=prod mix ecto.migrate
|
||||
```
|
||||
|
||||
* Now you can start Pleroma already
|
||||
|
||||
```shell
|
||||
sudo -Hu pleroma MIX_ENV=prod mix phx.server
|
||||
```
|
||||
|
||||
### Finalize installation
|
||||
|
||||
If you want to open your newly installed instance to the world, you should run nginx or some other webserver/proxy in front of Pleroma and you should consider to create a systemd service file for Pleroma.
|
||||
|
||||
#### Nginx
|
||||
|
||||
* Install nginx, if not already done:
|
||||
|
||||
```shell
|
||||
sudo pacman -S nginx
|
||||
```
|
||||
|
||||
* Create directories for available and enabled sites:
|
||||
|
||||
```shell
|
||||
sudo mkdir -p /etc/nginx/sites-{available,enabled}
|
||||
```
|
||||
|
||||
* Append the following line at the end of the `http` block in `/etc/nginx/nginx.conf`:
|
||||
|
||||
```Nginx
|
||||
include sites-enabled/*;
|
||||
```
|
||||
|
||||
* Setup your SSL cert, using your method of choice or certbot. If using certbot, first install it:
|
||||
|
||||
```shell
|
||||
sudo pacman -S certbot certbot-nginx
|
||||
```
|
||||
|
||||
and then set it up:
|
||||
|
||||
```shell
|
||||
sudo mkdir -p /var/lib/letsencrypt/
|
||||
sudo certbot certonly --email <your@emailaddress> -d <yourdomain> --standalone
|
||||
```
|
||||
|
||||
If that doesn’t work, make sure, that nginx is not already running. If it still doesn’t work, try setting up nginx first (change ssl “on” to “off” and try again).
|
||||
|
||||
---
|
||||
|
||||
* Copy the example nginx configuration and activate it:
|
||||
|
||||
```shell
|
||||
sudo cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.nginx
|
||||
sudo ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx
|
||||
```
|
||||
|
||||
* Before starting nginx edit the configuration and change it to your needs (e.g. change servername, change cert paths)
|
||||
|
||||
* (Strongly recommended) serve media on another domain
|
||||
|
||||
Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.
|
||||
|
||||
* Enable and start nginx:
|
||||
|
||||
```shell
|
||||
sudo systemctl enable --now nginx.service
|
||||
```
|
||||
|
||||
If you need to renew the certificate in the future, uncomment the relevant location block in the nginx config and run:
|
||||
|
||||
```shell
|
||||
sudo certbot certonly --email <your@emailaddress> -d <yourdomain> --webroot -w /var/lib/letsencrypt/
|
||||
```
|
||||
|
||||
#### Other webserver/proxies
|
||||
|
||||
You can find example configurations for them in `/opt/pleroma/installation/`.
|
||||
|
||||
#### Systemd service
|
||||
|
||||
* Copy example service file
|
||||
|
||||
```shell
|
||||
sudo cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
|
||||
```
|
||||
|
||||
* Edit the service file and make sure that all paths fit your installation
|
||||
* Enable and start `pleroma.service`:
|
||||
|
||||
```shell
|
||||
sudo systemctl enable --now pleroma.service
|
||||
```
|
||||
|
||||
#### Create your first user
|
||||
|
||||
If your instance is up and running, you can create your first user with administrative rights with the following task:
|
||||
|
||||
```shell
|
||||
sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
|
||||
```
|
||||
|
||||
#### Further reading
|
||||
|
||||
{! backend/installation/further_reading.include !}
|
||||
|
||||
## Questions
|
||||
|
||||
Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC.
|
||||
|
|
@ -1,294 +0,0 @@
|
|||
# Installing on NetBSD
|
||||
|
||||
{! backend/installation/generic_dependencies.include !}
|
||||
|
||||
# Installation options
|
||||
|
||||
Currently there are two options available for NetBSD: manual installation (from source) or using experimental package from [pkgsrc-wip](https://github.com/NetBSD/pkgsrc-wip/tree/master/pleroma).
|
||||
|
||||
WIP package can be installed via pkgsrc and can be crosscompiled for easier binary distribution. Source installation most probably will be restricted to a single machine.
|
||||
|
||||
## pkgsrc installation
|
||||
|
||||
WIP package creates Mix.Release (similar to how Docker images are built) but doesn't bundle Erlang runtime, listing it as a dependency instead. This allows for easier and more modular installations, especially on weaker machines. Currently this method also does not support all features of `pleroma_ctl` command (like changing installation type or managing frontends) as NetBSD is not yet a supported binary flavour of Pleroma's CI.
|
||||
|
||||
In any case, you can install it the same way as any other `pkgsrc-wip` package:
|
||||
|
||||
```
|
||||
cd /usr/pkgsrc
|
||||
git clone --depth 1 git://wip.pkgsrc.org/pkgsrc-wip.git wip
|
||||
cp -rf wip/pleroma www
|
||||
cp -rf wip/libvips graphics
|
||||
cd /usr/pkgsrc/www/pleroma
|
||||
bmake && bmake install
|
||||
```
|
||||
|
||||
Use `bmake package` to create a binary package. This can come especially handy if you're targeting embedded or low-power systems and are crosscompiling on a more powerful machine.
|
||||
|
||||
> Note: Elixir has [endianness bug](https://github.com/elixir-lang/elixir/issues/2785) which requires it to be compiled on a machine with the same endianness. In other words, package crosscompiled on amd64 (little endian) won't work on powerpc or sparc machines (big endian). While _in theory™_ nothing catastrophic should happen, one can see that for example regexes won't work properly. Some distributions just strip this warning away, so it doesn't bother the users... anyway, you've been warned.
|
||||
|
||||
## Source installation
|
||||
|
||||
pkgin should have been installed by the NetBSD installer if you selected
|
||||
the right options. If it isn't installed, install it using `pkg_add`.
|
||||
|
||||
Note that `postgresql11-contrib` is needed for the Postgres extensions
|
||||
Pleroma uses.
|
||||
|
||||
> Note: you can use modern versions of PostgreSQL. In this case, just use `postgresql16-contrib` and so on.
|
||||
|
||||
The `mksh` shell is needed to run the Elixir `mix` script.
|
||||
|
||||
`# pkgin install acmesh elixir git-base git-docs mksh nginx postgresql11-server postgresql11-client postgresql11-contrib sudo ffmpeg4 ImageMagick`
|
||||
|
||||
You can also build these packages using pkgsrc:
|
||||
```
|
||||
databases/postgresql11-contrib
|
||||
databases/postgresql11-client
|
||||
databases/postgresql11-server
|
||||
devel/git-base
|
||||
devel/git-docs
|
||||
devel/cmake
|
||||
lang/elixir
|
||||
security/acmesh
|
||||
security/sudo
|
||||
shells/mksh
|
||||
www/nginx
|
||||
```
|
||||
|
||||
Create a user for Pleroma:
|
||||
|
||||
```
|
||||
# groupadd pleroma
|
||||
# useradd -d /home/pleroma -m -g pleroma -s /usr/pkg/bin/mksh pleroma
|
||||
# echo 'export LC_ALL="en_GB.UTF-8"' >> /home/pleroma/.profile
|
||||
# su -l pleroma -c $SHELL
|
||||
```
|
||||
|
||||
Clone the repository:
|
||||
|
||||
```
|
||||
$ cd /home/pleroma
|
||||
$ git clone -b stable https://git.pleroma.social/pleroma/pleroma.git
|
||||
```
|
||||
|
||||
Get deps and compile:
|
||||
|
||||
```
|
||||
$ cd /home/pleroma/pleroma
|
||||
$ export MIX_ENV=prod
|
||||
$ mix deps.get
|
||||
$ mix compile
|
||||
```
|
||||
|
||||
## Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md))
|
||||
|
||||
`# pkgin install ImageMagick ffmpeg4 p5-Image-ExifTool`
|
||||
|
||||
or via pkgsrc:
|
||||
|
||||
```
|
||||
graphics/p5-Image-ExifTool
|
||||
graphics/ImageMagick
|
||||
multimedia/ffmpeg4
|
||||
```
|
||||
|
||||
# Configuration
|
||||
|
||||
## Understanding $PREFIX
|
||||
|
||||
From now on, you may encounter `$PREFIX` variable in the paths. This variable indicates your current local pkgsrc prefix. Usually it's `/usr/pkg` unless you configured it otherwise. Translating to pkgsrc's lingo, it's called `LOCALBASE`, which essentially means the same this. You may want to set it up for your local shell session (this uses `mksh` which should already be installed as one of the required dependencies):
|
||||
|
||||
```
|
||||
$ export PREFIX=$(pkg_info -Q LOCALBASE mksh)
|
||||
$ echo $PREFIX
|
||||
/usr/pkg
|
||||
```
|
||||
|
||||
## Setting up your instance
|
||||
|
||||
Now, you need to configure your instance. During this initial configuration, you will be asked some questions about your server. You will need a domain name at this point; it doesn't have to be deployed, but changing it later will be very cumbersome.
|
||||
|
||||
If you've installed via pkgsrc, `pleroma_ctl` should already be in your `PATH`; if you've installed from source, it's located at `/home/pleroma/pleroma/release/bin/pleroma_ctl`.
|
||||
|
||||
```
|
||||
$ su -l pleroma
|
||||
$ pleroma_ctl instance gen --output $PREFIX/etc/pleroma/config.exs --output-psql /tmp/setup_db.psql
|
||||
```
|
||||
|
||||
During installation, you will be asked about static and upload directories. Don't forget to create them and update permissions:
|
||||
|
||||
```
|
||||
mkdir -p /var/lib/pleroma/uploads
|
||||
chown -R pleroma:pleroma /var/lib/pleroma
|
||||
```
|
||||
|
||||
## Setting up the database
|
||||
|
||||
First, run `# /etc/rc.d/pgsql start`. Then, `$ sudo -Hu pgsql -g pgsql createdb`.
|
||||
|
||||
We can now initialize the database. You'll need to edit generated SQL file from the previous step. It's located at `/tmp/setup_db.psql`.
|
||||
|
||||
Edit this file, and *change the password* to a password of your choice. Make sure it is secure, since
|
||||
it'll be protecting your database. Now initialize the database:
|
||||
|
||||
```
|
||||
$ sudo -Hu pgsql -g pgsql psql -f /tmp/setup_db.psql
|
||||
```
|
||||
|
||||
Postgres allows connections from all users without a password by default. To
|
||||
fix this, edit `$PREFIX/pgsql/data/pg_hba.conf`. Change every `trust` to
|
||||
`password`.
|
||||
|
||||
Once this is done, restart Postgres with `# /etc/rc.d/pgsql restart`.
|
||||
|
||||
Run the database migrations.
|
||||
|
||||
### pkgsrc installation
|
||||
|
||||
```
|
||||
pleroma_ctl migrate
|
||||
```
|
||||
|
||||
### Source installation
|
||||
|
||||
You will need to do this whenever you update with `git pull`:
|
||||
|
||||
```
|
||||
$ cd /home/pleroma/pleroma
|
||||
$ MIX_ENV=prod mix ecto.migrate
|
||||
```
|
||||
|
||||
## Configuring nginx
|
||||
|
||||
Install the example configuration file
|
||||
(`$PREFIX/share/examples/pleroma/pleroma.nginx` or `/home/pleroma/pleroma/installation/pleroma.nginx`) to
|
||||
`$PREFIX/etc/nginx.conf`.
|
||||
|
||||
Note that it will need to be wrapped in a `http {}` block. You should add
|
||||
settings for the nginx daemon outside of the http block, for example:
|
||||
|
||||
```
|
||||
user nginx nginx;
|
||||
error_log /var/log/nginx/error.log;
|
||||
worker_processes 4;
|
||||
|
||||
events {
|
||||
}
|
||||
```
|
||||
|
||||
Edit the defaults:
|
||||
|
||||
* Change `ssl_certificate` and `ssl_trusted_certificate` to
|
||||
`/etc/nginx/tls/fullchain`.
|
||||
* Change `ssl_certificate_key` to `/etc/nginx/tls/key`.
|
||||
* Change `example.tld` to your instance's domain name.
|
||||
|
||||
### (Strongly recommended) serve media on another domain
|
||||
|
||||
Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.
|
||||
|
||||
## Configuring acme.sh
|
||||
|
||||
We'll be using acme.sh in Stateless Mode for TLS certificate renewal.
|
||||
|
||||
First, get your account fingerprint:
|
||||
|
||||
```
|
||||
$ sudo -Hu nginx -g nginx acme.sh --register-account
|
||||
```
|
||||
|
||||
You need to add the following to your nginx configuration for the server
|
||||
running on port 80:
|
||||
|
||||
```
|
||||
location ~ ^/\.well-known/acme-challenge/([-_a-zA-Z0-9]+)$ {
|
||||
default_type text/plain;
|
||||
return 200 "$1.6fXAG9VyG0IahirPEU2ZerUtItW2DHzDzD9wZaEKpqd";
|
||||
}
|
||||
```
|
||||
|
||||
Replace the string after after `$1.` with your fingerprint.
|
||||
|
||||
Start nginx:
|
||||
|
||||
```
|
||||
# /etc/rc.d/nginx start
|
||||
```
|
||||
|
||||
It should now be possible to issue a cert (replace `example.com`
|
||||
with your domain name):
|
||||
|
||||
```
|
||||
$ sudo -Hu nginx -g nginx acme.sh --issue -d example.com --stateless
|
||||
```
|
||||
|
||||
Let's add auto-renewal to `/etc/daily.local`
|
||||
(replace `example.com` with your domain):
|
||||
|
||||
```
|
||||
/usr/pkg/bin/sudo -Hu nginx -g nginx \
|
||||
/usr/pkg/sbin/acme.sh -r \
|
||||
-d example.com \
|
||||
--cert-file /etc/nginx/tls/cert \
|
||||
--key-file /etc/nginx/tls/key \
|
||||
--ca-file /etc/nginx/tls/ca \
|
||||
--fullchain-file /etc/nginx/tls/fullchain \
|
||||
--stateless
|
||||
```
|
||||
|
||||
## Autostart
|
||||
|
||||
For properly functioning instance, you will need pleroma (backend service), nginx (reverse proxy) and postgresql (database) services running. There's no requirement for them to reside on the same machine, but you have to provide autostart for each of them.
|
||||
|
||||
### nginx
|
||||
```
|
||||
# cp $PREFIX/share/examples/rc.d/nginx /etc/rc.d
|
||||
# echo "nginx=YES" >> /etc/rc.conf
|
||||
```
|
||||
|
||||
### postgresql
|
||||
|
||||
```
|
||||
# cp $PREFIX/share/examples/rc.d/pgsql /etc/rc.d
|
||||
# echo "pgsql=YES" >> /etc/rc.conf
|
||||
```
|
||||
|
||||
### pleroma
|
||||
|
||||
First, copy the script (pkgsrc variant)
|
||||
```
|
||||
# cp $PREFIX/share/examples/pleroma/pleroma.rc /etc/rc.d/pleroma
|
||||
```
|
||||
|
||||
or source variant
|
||||
```
|
||||
# cp /home/pleroma/pleroma/installation/netbsd/rc.d/pleroma /etc/rc.d/pleroma
|
||||
# chmod +x /etc/rc.d/pleroma
|
||||
```
|
||||
|
||||
Then, add the following to `/etc/rc.conf`:
|
||||
|
||||
```
|
||||
pleroma=YES
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
Run `# /etc/rc.d/pleroma start` to start Pleroma.
|
||||
Restart nginx with `# /etc/rc.d/nginx restart` and you should be up and running.
|
||||
|
||||
Make sure your time is in sync, or other instances will receive your posts with
|
||||
incorrect timestamps. You should have ntpd running.
|
||||
|
||||
## Instances running NetBSD
|
||||
|
||||
* <https://catgirl.science>
|
||||
|
||||
#### Further reading
|
||||
|
||||
{! backend/installation/further_reading.include !}
|
||||
|
||||
## Questions
|
||||
|
||||
Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC.
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
# Installing on NixOS
|
||||
|
||||
NixOS contains a source build package of pleroma and a NixOS module to install it.
|
||||
For installation add this to your configuration.nix and add a config.exs next to it:
|
||||
```nix
|
||||
services.pleroma = {
|
||||
enable = true;
|
||||
configs = [ (lib.fileContents ./config.exs) ];
|
||||
secretConfigFile = "/var/lib/pleroma/secret.exs";
|
||||
};
|
||||
```
|
||||
|
||||
## Questions
|
||||
The nix community uses matrix for communication: [#nix:nixos.org](https://matrix.to/#/#nix:nixos.org)
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ Note: the packages are not required with the current default settings of Pleroma
|
|||
|
||||
It is required for the following Pleroma features:
|
||||
|
||||
* `Pleroma.Upload.Filters.Mogrify`, `Pleroma.Upload.Filters.Mogrifun` upload filters (related config: `Plaroma.Upload/filters` in `config/config.exs`)
|
||||
* `Pleroma.Upload.Filters.Mogrify`, `Pleroma.Upload.Filters.Mogrifun` upload filters (related config: `Pleroma.Upload/filters` in `config/config.exs`)
|
||||
* Media preview proxy for still images (related config: `media_preview_proxy/enabled` in `config/config.exs`)
|
||||
|
||||
## `ffmpeg`
|
||||
|
|
@ -33,5 +33,5 @@ It is required for the following Pleroma features:
|
|||
|
||||
It is required for the following Pleroma features:
|
||||
|
||||
* `Pleroma.Upload.Filters.Exiftool.StripLocation` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`)
|
||||
* `Pleroma.Upload.Filters.Exiftool.ReadDescription` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`)
|
||||
* `Pleroma.Upload.Filters.Exiftool.StripLocation` upload filter (related config: `Pleroma.Upload/filters` in `config/config.exs`)
|
||||
* `Pleroma.Upload.Filters.Exiftool.ReadDescription` upload filter (related config: `Pleroma.Upload/filters` in `config/config.exs`)
|
||||
|
|
|
|||
|
|
@ -13,6 +13,9 @@ You will be running commands as root. If you aren't root already, please elevate
|
|||
|
||||
Similarly to other binaries, OTP releases tend to be only compatible with the distro they are built on, as such this guide focuses only on Debian/Ubuntu and Alpine.
|
||||
|
||||
!!! note
|
||||
If you get `GLIBC_... not found` errors on Debian/Ubuntu, you can run the OTP release from `/opt/pleroma` inside a newer distro container without upgrading the host. See [`release_to_docker_en.md`](release_to_docker_en.md).
|
||||
|
||||
### Detecting flavour
|
||||
|
||||
Paste the following into the shell:
|
||||
|
|
|
|||
61
docs/installation/release_to_docker_en.md
Normal file
61
docs/installation/release_to_docker_en.md
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
# Running OTP releases via Docker (glibc shim)
|
||||
|
||||
Pleroma OTP releases are built on specific distros. If your host OS is older than
|
||||
the build environment, you may hit runtime linker errors such as:
|
||||
|
||||
```
|
||||
/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found
|
||||
```
|
||||
|
||||
If you don't want to upgrade your host OS, you can run the existing OTP release
|
||||
from `/opt/pleroma` inside an Ubuntu 24.04 container while keeping your existing
|
||||
host config and data directories.
|
||||
|
||||
This approach uses a small "shim" container image to provide a newer `glibc`.
|
||||
It is **not** the official Pleroma Docker image.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Docker Engine + the Docker Compose plugin on the host
|
||||
- Root access (or equivalent access to the Docker socket)
|
||||
- Existing OTP release in `/opt/pleroma`
|
||||
- Existing config in `/etc/pleroma` and data in `/var/lib/pleroma`
|
||||
|
||||
## Setup
|
||||
|
||||
1. Copy the provided templates:
|
||||
|
||||
```sh
|
||||
mkdir -p /etc/pleroma/container
|
||||
cp -a /opt/pleroma/installation/release-to-docker/* /etc/pleroma/container/
|
||||
```
|
||||
|
||||
2. Build the shim image:
|
||||
|
||||
```sh
|
||||
cd /etc/pleroma/container
|
||||
docker compose build
|
||||
```
|
||||
|
||||
3. Replace your systemd unit:
|
||||
|
||||
```sh
|
||||
cp /etc/pleroma/container/pleroma.service /etc/systemd/system/pleroma.service
|
||||
systemctl daemon-reload
|
||||
systemctl enable --now pleroma
|
||||
journalctl -u pleroma -f
|
||||
```
|
||||
|
||||
## Running migrations / `pleroma_ctl`
|
||||
|
||||
Migrations are run automatically by default when the container starts. You can
|
||||
disable this by setting `PLEROMA_RUN_MIGRATIONS=0` in
|
||||
`/etc/pleroma/container/docker-compose.yml`.
|
||||
|
||||
To run admin commands inside the container:
|
||||
|
||||
```sh
|
||||
cd /etc/pleroma/container
|
||||
docker compose exec pleroma /opt/pleroma/bin/pleroma_ctl status
|
||||
docker compose run --rm --no-deps pleroma /opt/pleroma/bin/pleroma_ctl migrate
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue