summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/api/differences_in_mastoapi_responses.md32
-rw-r--r--docs/api/pleroma_api.md75
-rw-r--r--docs/config.md70
-rw-r--r--docs/config/custom_emoji.md27
-rw-r--r--docs/installation/arch_linux_en.md3
-rw-r--r--docs/installation/gentoo_en.md296
6 files changed, 471 insertions, 32 deletions
diff --git a/docs/api/differences_in_mastoapi_responses.md b/docs/api/differences_in_mastoapi_responses.md
index 923d94db2..1350ace43 100644
--- a/docs/api/differences_in_mastoapi_responses.md
+++ b/docs/api/differences_in_mastoapi_responses.md
@@ -20,6 +20,7 @@ Has these additional fields under the `pleroma` object:
- `local`: true if the post was made on the local instance.
- `conversation_id`: the ID of the conversation the status is associated with (if any)
+- `in_reply_to_account_acct`: the `acct` property of User entity for replied user (if any)
- `content`: a map consisting of alternate representations of the `content` property with the key being it's mimetype. Currently the only alternate representation supported is `text/plain`
- `spoiler_text`: a map consisting of alternate representations of the `spoiler_text` property with the key being it's mimetype. Currently the only alternate representation supported is `text/plain`
@@ -37,9 +38,24 @@ Has these additional fields under the `pleroma` object:
- `tags`: Lists an array of tags for the user
- `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/api/entities/#relationship
-- `is_moderator`: boolean, true if user is a moderator
-- `is_admin`: boolean, true if user is an admin
+- `is_moderator`: boolean, nullable, true if user is a moderator
+- `is_admin`: boolean, nullable, true if user is an admin
- `confirmation_pending`: boolean, true if a new user account is waiting on email confirmation to be activated
+- `hide_followers`: boolean, true when the user has follower hiding enabled
+- `hide_follows`: boolean, true when the user has follow hiding enabled
+
+### Source
+
+Has these additional fields under the `pleroma` object:
+
+- `show_role`: boolean, nullable, true when the user wants his role (e.g admin, moderator) to be shown
+- `no_rich_text` - boolean, nullable, true when html tags are stripped from all statuses requested from the API
+
+## Account Search
+
+Behavior has changed:
+
+- `/api/v1/accounts/search`: Does not require authentication
## Notifications
@@ -52,3 +68,15 @@ Has these additional fields under the `pleroma` object:
Additional parameters can be added to the JSON body/Form data:
- `preview`: boolean, if set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example.
+- `content_type`: string, contain the MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint.
+
+## PATCH `/api/v1/update_credentials`
+
+Additional parameters can be added to the JSON body/Form data:
+
+- `no_rich_text` - if true, html tags are stripped from all statuses requested from the API
+- `hide_followers` - if true, user's followers will be hidden
+- `hide_follows` - if true, user's follows will be hidden
+- `hide_favorites` - if true, user's favorites timeline will be hidden
+- `show_role` - if true, user's role (e.g admin, moderator) will be exposed to anyone in the API
+- `default_scope` - the scope returned under `privacy` key in Source subentity
diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md
index dbe250300..190846de9 100644
--- a/docs/api/pleroma_api.md
+++ b/docs/api/pleroma_api.md
@@ -77,7 +77,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* `token`: invite token required when the registrations aren't public.
* Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}`
* Example response:
-```
+```json
{
"background_image": null,
"cover_photo": "https://pleroma.soykaf.com/images/banner.png",
@@ -187,6 +187,62 @@ See [Admin-API](Admin-API.md)
}
```
+## `/api/v1/pleroma/accounts/:id/favourites`
+### Returns favorites timeline of any user
+* Method `GET`
+* Authentication: not required
+* Params:
+ * `id`: the id of the account for whom to return results
+ * `limit`: optional, the number of records to retrieve
+ * `since_id`: optional, returns results that are more recent than the specified id
+ * `max_id`: optional, returns results that are older than the specified id
+* Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
+* Example response:
+```json
+[
+ {
+ "account": {
+ "id": "9hptFmUF3ztxYh3Svg",
+ "url": "https://pleroma.example.org/users/nick2",
+ "username": "nick2",
+ ...
+ },
+ "application": {"name": "Web", "website": null},
+ "bookmarked": false,
+ "card": null,
+ "content": "This is :moominmamma: note 0",
+ "created_at": "2019-04-15T15:42:15.000Z",
+ "emojis": [],
+ "favourited": false,
+ "favourites_count": 1,
+ "id": "9hptFmVJ02khbzYJaS",
+ "in_reply_to_account_id": null,
+ "in_reply_to_id": null,
+ "language": null,
+ "media_attachments": [],
+ "mentions": [],
+ "muted": false,
+ "pinned": false,
+ "pleroma": {
+ "content": {"text/plain": "This is :moominmamma: note 0"},
+ "conversation_id": 13679,
+ "local": true,
+ "spoiler_text": {"text/plain": "2hu"}
+ },
+ "reblog": null,
+ "reblogged": false,
+ "reblogs_count": 0,
+ "replies_count": 0,
+ "sensitive": false,
+ "spoiler_text": "2hu",
+ "tags": [{"name": "2hu", "url": "/tag/2hu"}],
+ "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
+ "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
+ "visibility": "public"
+ }
+]
+```
+
## `/api/pleroma/notification_settings`
### Updates user notification settings
* Method `PUT`
@@ -197,3 +253,20 @@ See [Admin-API](Admin-API.md)
* `remote`: BOOLEAN field, receives notifications from people on remote instances
* `local`: BOOLEAN field, receives notifications from people on the local instance
* Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
+
+## `/api/pleroma/healthcheck`
+### Healthcheck endpoint with additional system data.
+* Method `GET`
+* Authentication: not required
+* Params: none
+* Response: JSON, statuses (200 - healthy, 503 unhealthy).
+* Example response:
+```json
+{
+ "pool_size": 0, # database connection pool
+ "active": 0, # active processes
+ "idle": 0, # idle processes
+ "memory_used": 0.00, # Memory used
+ "healthy": true # Instance state
+}
+```
diff --git a/docs/config.md b/docs/config.md
index b5ea58746..ad55d44a7 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -31,22 +31,22 @@ This filter replaces the filename (not the path) of an upload. For complete obfu
* `text`: Text to replace filenames in links. If empty, `{random}.extension` will be used.
-## Pleroma.Mailer
+## Pleroma.Emails.Mailer
* `adapter`: one of the mail adapters listed in [Swoosh readme](https://github.com/swoosh/swoosh#adapters), or `Swoosh.Adapters.Local` for in-memory mailbox.
* `api_key` / `password` and / or other adapter-specific settings, per the above documentation.
An example for Sendgrid adapter:
-```exs
-config :pleroma, Pleroma.Mailer,
+```elixir
+config :pleroma, Pleroma.Emails.Mailer,
adapter: Swoosh.Adapters.Sendgrid,
api_key: "YOUR_API_KEY"
```
An example for SMTP adapter:
-```exs
-config :pleroma, Pleroma.Mailer,
+```elixir
+config :pleroma, Pleroma.Emails.Mailer,
adapter: Swoosh.Adapters.SMTP,
relay: "smtp.gmail.com",
username: "YOUR_USERNAME@gmail.com",
@@ -63,6 +63,7 @@ config :pleroma, Pleroma.Mailer,
## :instance
* `name`: The instance’s name
* `email`: Email used to reach an Administrator/Moderator of the instance
+* `notify_email`: Email used for notifications.
* `description`: The instance’s description, can be seen in nodeinfo and ``/api/v1/instance``
* `limit`: Posts character limit (CW/Subject included in the counter)
* `remote_limit`: Hard character limit beyond which remote posts will be dropped.
@@ -86,7 +87,6 @@ config :pleroma, Pleroma.Mailer,
* `quarantined_instances`: List of ActivityPub instances where private(DMs, followers-only) activities will not be send.
* `managed_config`: Whenether the config for pleroma-fe is configured in this config or in ``static/config.json``
* `allowed_post_formats`: MIME-type list of formats allowed to be posted (transformed into HTML)
-* `finmoji_enabled`: Whenether to enable the finmojis in the custom emojis.
* `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo).
* `scope_copy`: Copy the scope (private/unlisted/public) in replies to posts by default.
* `subject_line_behavior`: Allows changing the default behaviour of subject lines in replies. Valid values:
@@ -103,12 +103,13 @@ config :pleroma, Pleroma.Mailer,
* `welcome_user_nickname`: The nickname of the local user that sends the welcome message.
* `max_report_comment_size`: The maximum size of the report comment (Default: `1000`)
* `safe_dm_mentions`: If set to true, only mentions at the beginning of a post will be used to address people in direct messages. This is to prevent accidental mentioning of people when talking about them (e.g. "@friend hey i really don't like @enemy"). (Default: `false`)
+* `healthcheck`: if set to true, system data will be shown on ``/api/pleroma/healthcheck``.
## :logger
* `backends`: `:console` is used to send logs to stdout, `{ExSyslogger, :ex_syslogger}` to log to syslog, and `Quack.Logger` to log to Slack
An example to enable ONLY ExSyslogger (f/ex in ``prod.secret.exs``) with info and debug suppressed:
-```
+```elixir
config :logger,
backends: [{ExSyslogger, :ex_syslogger}]
@@ -117,7 +118,7 @@ config :logger, :ex_syslogger,
```
Another example, keeping console output and adding the pid to syslog output:
-```
+```elixir
config :logger,
backends: [:console, {ExSyslogger, :ex_syslogger}]
@@ -129,7 +130,7 @@ config :logger, :ex_syslogger,
See: [logger’s documentation](https://hexdocs.pm/logger/Logger.html) and [ex_syslogger’s documentation](https://hexdocs.pm/ex_syslogger/)
An example of logging info to local syslog, but warn to a Slack channel:
-```
+```elixir
config :logger,
backends: [ {ExSyslogger, :ex_syslogger}, Quack.Logger ],
level: :info
@@ -155,14 +156,30 @@ Frontends can access these settings at `/api/pleroma/frontend_configurations`
To add your own configuration for PleromaFE, use it like this:
-`config :pleroma, :frontend_configurations, pleroma_fe: %{redirectRootNoLogin: "/main/all", ...}`
+```elixir
+config :pleroma, :frontend_configurations,
+ pleroma_fe: %{
+ theme: "pleroma-dark",
+ # ... see /priv/static/static/config.json for the available keys.
+},
+ masto_fe: %{
+ showInstanceSpecificPanel: true
+ }
+```
+
+These settings **need to be complete**, they will override the defaults.
-These settings need to be complete, they will override the defaults. See `priv/static/static/config.json` for the available keys.
+NOTE: for versions < 1.0, you need to set [`:fe`](#fe) to false, as shown a few lines below.
## :fe
__THIS IS DEPRECATED__
-If you are using this method, please change it to the `frontend_configurations` method. Please set this option to false in your config like this: `config :pleroma, :fe, false`.
+If you are using this method, please change it to the [`frontend_configurations`](#frontend_configurations) method.
+Please **set this option to false** in your config like this:
+
+```elixir
+config :pleroma, :fe, false
+```
This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:instance`` is set to false.
@@ -204,6 +221,7 @@ This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:i
* `enabled`: Enables proxying of remote media to the instance’s proxy
* `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host/CDN fronts.
* `proxy_opts`: All options defined in `Pleroma.ReverseProxy` documentation, defaults to `[max_body_length: (25*1_048_576)]`.
+* `whitelist`: List of domains to bypass the mediaproxy
## :gopher
* `enabled`: Enables the gopher interface
@@ -221,6 +239,8 @@ This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:i
- `scheme` - e.g `http`, `https`
- `port`
- `path`
+* `extra_cookie_attrs` - a list of `Key=Value` strings to be added as non-standard cookie attributes. Defaults to `["SameSite=Lax"]`. See the [SameSite article](https://www.owasp.org/index.php/SameSite) on OWASP for more info.
+
**Important note**: if you modify anything inside these lists, default `config.exs` values will be overwritten, which may result in breakage, to make sure this does not happen please copy the default value for the list from `config.exs` and modify/add only what you need
@@ -270,7 +290,7 @@ their ActivityPub ID.
An example:
-```exs
+```elixir
config :pleroma, :mrf_user_allowlist,
"example.org": ["https://example.org/users/admin"]
```
@@ -299,7 +319,7 @@ the source code is here: https://github.com/koto-bank/kocaptcha. The default end
Allows to set a token that can be used to authenticate with the admin api without using an actual user by giving it as the 'admin_token' parameter. Example:
-```exs
+```elixir
config :pleroma, :admin_token, "somerandomtoken"
```
@@ -317,7 +337,7 @@ Pleroma has the following queues:
* `federator_outgoing` - Outgoing federation
* `federator_incoming` - Incoming federation
-* `mailer` - Email sender, see [`Pleroma.Mailer`](#pleroma-mailer)
+* `mailer` - Email sender, see [`Pleroma.Emails.Mailer`](#pleroma-emails-mailer)
* `transmogrifier` - Transmogrifier
* `web_push` - Web push notifications
* `scheduled_activities` - Scheduled activities, see [`Pleroma.ScheduledActivities`](#pleromascheduledactivity)
@@ -340,9 +360,10 @@ This config contains two queues: `federator_incoming` and `federator_outgoing`.
* `max_retries`: The maximum number of times a federation job is retried
## Pleroma.Web.Metadata
-* `providers`: a list of metadata providers to enable. Providers availible:
+* `providers`: a list of metadata providers to enable. Providers available:
* Pleroma.Web.Metadata.Providers.OpenGraph
* Pleroma.Web.Metadata.Providers.TwitterCard
+ * Pleroma.Web.Metadata.Providers.RelMe - add links from user bio with rel=me into the `<header>` as `<link rel=me>`
* `unfurl_nsfw`: If set to `true` nsfw attachments will be shown in previews
## :rich_media
@@ -382,7 +403,7 @@ Configuration for the `auto_linker` library:
Example:
-```exs
+```elixir
config :auto_linker,
opts: [
scheme: true,
@@ -427,7 +448,7 @@ Pleroma account will be created with the same name as the LDAP user name.
Authentication / authorization settings.
-* `auth_template`: authentication form template. By default it's `show.html` which corresponds to `lib/pleroma/web/templates/o_auth/o_auth/show.html.eex`.
+* `auth_template`: authentication form template. By default it's `show.html` which corresponds to `lib/pleroma/web/templates/o_auth/o_auth/show.html.eex`.
* `oauth_consumer_template`: OAuth consumer mode authentication form template. By default it's `consumer.html` which corresponds to `lib/pleroma/web/templates/o_auth/o_auth/consumer.html.eex`.
* `oauth_consumer_strategies`: the list of enabled OAuth consumer strategies; by default it's set by OAUTH_CONSUMER_STRATEGIES environment variable.
@@ -440,7 +461,9 @@ Note: each strategy is shipped as a separate dependency; in order to get the str
e.g. `OAUTH_CONSUMER_STRATEGIES="twitter facebook google microsoft" mix deps.get`.
The server should also be started with `OAUTH_CONSUMER_STRATEGIES="..." mix phx.server` in case you enable any strategies.
-Note: each strategy requires separate setup (on external provider side and Pleroma side). Below are the guidelines on setting up most popular strategies.
+Note: each strategy requires separate setup (on external provider side and Pleroma side). Below are the guidelines on setting up most popular strategies.
+
+Note: make sure that `"SameSite=Lax"` is set in `extra_cookie_attrs` when you have this feature enabled. OAuth consumer mode will not work with `"SameSite=Strict"`
* For Twitter, [register an app](https://developer.twitter.com/en/apps), configure callback URL to https://<your_host>/oauth/twitter/callback
@@ -453,7 +476,7 @@ Note: each strategy requires separate setup (on external provider side and Plero
Once the app is configured on external OAuth provider side, add app's credentials and strategy-specific settings (if any — e.g. see Microsoft below) to `config/prod.secret.exs`,
per strategy's documentation (e.g. [ueberauth_twitter](https://github.com/ueberauth/ueberauth_twitter)). Example config basing on environment variables:
-```
+```elixir
# Twitter
config :ueberauth, Ueberauth.Strategy.Twitter.OAuth,
consumer_key: System.get_env("TWITTER_CONSUMER_KEY"),
@@ -475,9 +498,14 @@ config :ueberauth, Ueberauth.Strategy.Google.OAuth,
config :ueberauth, Ueberauth.Strategy.Microsoft.OAuth,
client_id: System.get_env("MICROSOFT_CLIENT_ID"),
client_secret: System.get_env("MICROSOFT_CLIENT_SECRET")
-
+
config :ueberauth, Ueberauth,
providers: [
microsoft: {Ueberauth.Strategy.Microsoft, [callback_params: []]}
]
```
+
+## :emoji
+* `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]`
+* `groups`: Emojis are ordered in groups (tags). This is an array of key-value pairs where the key is the groupname and the value the location or array of locations. `*` can be used as a wildcard. Example `[Custom: ["/emoji/*.png", "/emoji/custom/*.png"]]`
+* `default_manifest`: Location of the JSON-manifest. This manifest contains information about the emoji-packs you can download. Currently only one manifest can be added (no arrays).
diff --git a/docs/config/custom_emoji.md b/docs/config/custom_emoji.md
index 419a7d0e2..f72c0edbc 100644
--- a/docs/config/custom_emoji.md
+++ b/docs/config/custom_emoji.md
@@ -1,15 +1,25 @@
# Custom Emoji
+Before you add your own custom emoji, check if they are available in an existing pack.
+See `Mix.Tasks.Pleroma.Emoji` for information about emoji packs.
+
To add custom emoji:
-* Add the image file(s) to `priv/static/emoji/custom`
-* In case of conflicts: add the desired shortcode with the path to `config/custom_emoji.txt`, comma-separated and one per line
-* Force recompilation (``mix clean && mix compile``)
+* Create the `STATIC-DIR/emoji/` directory if it doesn't exist
+ (`STATIC-DIR` is configurable, `instance/static/` by default)
+* Create a directory with whatever name you want (custom is a good name to show the purpose of it).
+ This will create a local emoji pack.
+* Put your `.png` emoji files in that directory. In case of conflicts, you can create an `emoji.txt`
+ file in that directory and specify a custom shortcode using the following format:
+ `shortcode, file-path, tag1, tag2, etc`. One emoji per line. Note that if you do so,
+ you'll have to list all other emojis in the pack too.
+* Either restart pleroma or connect to the iex session pleroma's running and
+ run `Pleroma.Emoji.reload/0` in it.
Example:
-image files (in `/priv/static/emoji/custom`): `happy.png` and `sad.png`
+image files (in `instance/static/emoji/custom`): `happy.png` and `sad.png`
-content of `config/custom_emoji.txt`:
+content of `emoji.txt`:
```
happy, /emoji/custom/happy.png, Tag1,Tag2
sad, /emoji/custom/sad.png, Tag1
@@ -18,9 +28,14 @@ foo, /emoji/custom/foo.png
The files should be PNG (APNG is okay with `.png` for `image/png` Content-type) and under 50kb for compatibility with mastodon.
+Default file extentions and locations for emojis are set in `config.exs`. To use different locations or file-extentions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extentions:
+```elixir
+config :pleroma, :emoji, shortcode_globs: ["/emoji/custom/**/*.png", "/emoji/custom/**/*.gif"]
+```
+
## Emoji tags (groups)
-Default tags are set in `config.exs`.
+Default tags are set in `config.exs`. To set your own tags, copy the structure to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it.
```elixir
config :pleroma, :emoji,
shortcode_globs: ["/emoji/custom/**/*.png"],
diff --git a/docs/installation/arch_linux_en.md b/docs/installation/arch_linux_en.md
index 4b3bbbbb0..2b040cfbc 100644
--- a/docs/installation/arch_linux_en.md
+++ b/docs/installation/arch_linux_en.md
@@ -7,7 +7,6 @@ This guide will assume that you have administrative rights, either as root or a
* `postgresql`
* `elixir`
-* `erlang-unixodbc`
* `git`
* `base-devel`
@@ -27,7 +26,7 @@ sudo pacman -Syu
* Install some of the above mentioned programs:
```shell
-sudo pacman -S git base-devel elixir erlang-unixodbc
+sudo pacman -S git base-devel elixir
```
### Install PostgreSQL
diff --git a/docs/installation/gentoo_en.md b/docs/installation/gentoo_en.md
new file mode 100644
index 000000000..fccaad378
--- /dev/null
+++ b/docs/installation/gentoo_en.md
@@ -0,0 +1,296 @@
+# Installing on Gentoo GNU/Linux
+## Installation
+
+This guide will assume that you have administrative rights, either as root or a user with [sudo permissions](https://wiki.gentoo.org/wiki/Sudo). Lines that begin with `#` indicate that they should be run as the superuser. Lines using `$` should be run as the indicated user, e.g. `pleroma$` should be run as the `pleroma` user.
+
+### Configuring your hostname (optional)
+
+If you would like your prompt to permanently include your host/domain, change `/etc/conf.d/hostname` to your hostname. You can reboot or use the `hostname` command to make immediate changes.
+
+### Your make.conf, package.use, and USE flags
+
+The only specific USE flag you should need is the `uuid` flag for `dev-db/postgresql`. Add the following line to any new file in `/etc/portage/package.use`. If you would like a suggested name for the file, either `postgresql` or `pleroma` would do fine, depending on how you like to arrange your package.use flags.
+
+```text
+dev-db/postgresql uuid
+```
+
+You could opt to add `USE="uuid"` to `/etc/portage/make.conf` if you'd rather set this as a global USE flags, but this flags does unrelated things in other packages, so keep that in mind if you elect to do so.
+
+Double check your compiler flags in `/etc/portage/make.conf`. If you require any special compilation flags or would like to set up remote builds, now is the time to do so. Be sure that your CFLAGS and MAKEOPTS make sense for the platform you are using. It is not recommended to use above `-O2` or risky optimization flags for a production server.
+
+### Installing a cron daemon
+
+Gentoo quite pointedly does not come with a cron daemon installed, and as such it is recommended you install one to automate certbot renewals and to allow other system administration tasks to be run automatically. Gentoo has [a whole wide world of cron options](https://wiki.gentoo.org/wiki/Cron) but if you just want A Cron That Works, `emerge --ask virtual/cron` will install the default cron implementation (probably cronie) which will work just fine. For the purpouses of this guide, we will be doing just that.
+
+### Required ebuilds
+
+* `dev-db/postgresql`
+* `dev-lang/elixir`
+* `dev-vcs/git`
+
+#### Optional ebuilds used in this guide
+
+* `www-servers/nginx` (preferred, example configs for other reverse proxies can be found in the repo)
+* `app-crypt/certbot` (or any other ACME client for Let’s Encrypt certificates)
+* `app-crypt/certbot-nginx` (nginx certbot plugin that allows use of the all-powerful `--nginx` flag on certbot)
+
+### Prepare the system
+
+* First ensure that you have the latest copy of the portage ebuilds if you have not synced them yet:
+
+```shell
+ # emaint sync -a
+```
+
+* Emerge all required the required and suggested software in one go:
+
+```shell
+ # emerge --ask dev-db/postgresql dev-lang/elixir dev-vcs/git www-servers/nginx app-crypt/certbot app-crypt/certbot-nginx
+```
+
+If you would not like to install the optional packages, remove them from this line.
+
+If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, strech a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do.
+
+### Install PostgreSQL
+
+[Gentoo Wiki article](https://wiki.gentoo.org/wiki/PostgreSQL) as well as [PostgreSQL QuickStart](https://wiki.gentoo.org/wiki/PostgreSQL/QuickStart) might be worth a quick glance, as the way Gentoo handles postgres is slightly unusual, with built in capability to have two different databases running for testing and live or whatever other purpouse. While it is still straightforward to install, it does mean that the version numbers used in this guide might change for future updates, so keep an eye out for the output you get from `emerge` to ensure you are using the correct ones.
+
+* Install postgresql if you have not done so already:
+
+```shell
+ # emerge --ask dev-db/postgresql
+```
+
+Ensure that `/etc/conf.d/postgresql-11` has the encoding you want (it defaults to UTF8 which is probably what you want) and make any adjustments to the data directory if you find it necessary. Be sure to adjust the number at the end depending on what version of postgres you actually installed.
+
+* Initialize the database cluster
+
+The output from emerging postgresql should give you a command for initializing the postgres database. The default slot should be indicated in this command, ensure that it matches the command below.
+
+```shell
+ # emerge --config dev-db/postgresql:11
+```
+
+* Start postgres and enable the system service
+
+```shell
+ # /etc/init.d/postgresql-11 start
+ # rc-update add postgresql-11 default
+ ```
+
+### A note on licenses, the AGPL, and deployment procedures
+
+If you do not plan to make any modifications to your Pleroma instance, cloning directly from the main repo will get you what you need. However, if you plan on doing any contributions to upstream development, making changes or modifications to your instance, making custom themes, or want to play around--and let's be honest here, if you're using Gentoo that is most likely you--you will save yourself a lot of headache later if you take the time right now to fork the Pleroma repo and use that in the following section.
+
+Not only does this make it much easier to deploy changes you make, as you can commit and pull from upstream and all that good stuff from the comfort of your local machine then simply `git pull` on your instance server when you're ready to deploy, it also ensures you are compliant with the Affero General Public Licence that Pleroma is licenced under, which stipulates that all network services provided with modified AGPL code must publish their changes on a publicly available internet service and for free. It also makes it much easier to ask for help from and provide help to your fellow Pleroma admins if your public repo always reflects what you are running because it is part of your deployment procedure.
+
+### Install PleromaBE
+
+* Add a new system user for the Pleroma service and set up default directories:
+
+Remove `,wheel` if you do not want this user to be able to use `sudo`, however note that being able to `sudo` as the `pleroma` user will make finishing the insallation and common maintenence tasks somewhat easier:
+
+```shell
+ # useradd -m -G users,wheel -s /bin/bash pleroma
+```
+
+Optional: If you are using sudo, review your sudo setup to ensure it works for you. The `/etc/sudoers` file has a lot of options and examples to help you, and [the Gentoo sudo guide](https://wiki.gentoo.org/wiki/Sudo) has more information. Finishing this installation will be somewhat easier if you have a way to sudo from the `pleroma` user, but it might be best to not allow that user to sudo during normal operation, and as such there will be a reminder at the end of this guide to double check if you would like to lock down the `pleroma` user after initial setup.
+
+**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 or want `sudo` or would like to use the system as the `pleroma` user for instance maintenance tasks, you can simply use `su - pleroma` to switch to the `pleroma` user.
+
+* Git clone the PleromaBE repository and make the Pleroma user the owner of the directory:
+
+It is highly recommended you use your own fork for the `https://path/to/repo` part below, however if you foolishly decide to forego using your own fork, the primary repo `https://git.pleroma.social/pleroma/pleroma` will work here.
+
+```shell
+ pleroma$ cd ~
+ pleroma$ git clone https://path/to/repo
+```
+
+* Change to the new directory:
+
+```shell
+pleroma$ cd ~/pleroma
+```
+
+* Install the dependencies for Pleroma and answer with `yes` if it asks you to install `Hex`:
+
+```shell
+pleroma$ mix deps.get
+```
+
+* Generate the configuration:
+
+```shell
+pleroma$ mix pleroma.instance gen
+```
+
+ * Answer with `yes` if it asks you to install `rebar3`.
+
+ * This part precompiles some parts of Pleroma, so it might take a few moments
+
+ * After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`.
+
+ * Spend some time with `generated_config.exs` to ensure that everything is in order. If you plan on using an S3-compatible service to store your local media, that can be done here. You will likely mostly be using `prod.secret.exs` for a production instance, however if you would like to set up a development environment, make a copy to `dev.secret.exs` and adjust settings as needed as well.
+
+```shell
+pleroma$ mv config/generated_config.exs config/prod.secret.exs
+```
+
+* The previous command creates also the file `config/setup_db.psql`, with which you can create the database. Ensure that it is using the correct database name on the `CREATE DATABASE` and the `\c` lines, then run the postgres script:
+
+```shell
+pleroma$ sudo -Hu postgres psql -f config/setup_db.psql
+```
+
+* Now run the database migration:
+
+```shell
+pleroma$ MIX_ENV=prod mix ecto.migrate
+```
+
+* Now you can start Pleroma already
+
+```shell
+pleroma$ MIX_ENV=prod mix phx.server
+```
+
+It probably won't work over the public internet quite yet, however, as we still need to set up a web servere to proxy to the pleroma application, as well as configure SSL.
+
+### Finalize installation
+
+Assuming you want to open your newly installed federated social network to, well, the federation, you should run nginx or some other webserver/proxy in front of Pleroma. It is also a good idea to set up Pleroma to run as a system service.
+
+#### Nginx
+
+* Install nginx, if not already done:
+
+```shell
+ # emerge --ask www-servers/nginx
+```
+
+* Create directories for available and enabled sites:
+
+```shell
+ # 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, install it if you haven't already:
+
+```shell
+ # emerge --ask app-crypt/certbot app-crypt/certbot-nginx
+```
+
+and then set it up:
+
+```shell
+ # mkdir -p /var/lib/letsencrypt/
+ # certbot certonly --email <your@emailaddress> -d <yourdomain> --standalone
+```
+
+If that doesn't work the first time, add `--dry-run` to further attempts to avoid being ratelimited as you identify the issue, and do not remove it until the dry run succeeds. 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). Often the answer to issues with certbot is to use the `--nginx` flag once you have nginx up and running.
+
+If you are using any additional subdomains, such as for a media proxy, you can re-run the same command with the subdomain in question. When it comes time to renew later, you will not need to run multiple times for each domain, one renew will handle it.
+
+---
+
+* Copy the example nginx configuration and activate it:
+
+```shell
+ # cp /home/pleroma/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/
+ # ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx
+```
+
+* Take some time to ensure that your nginx config is correct
+
+Replace all instances of `example.tld` with your instance's public URL. If for whatever reason you made changes to the port that your pleroma app runs on, be sure that is reflected in your configuration.
+
+Pay special attention to the line that begins with `ssl_ecdh_curve`. It is stongly advised to comment that line out so that OpenSSL will use its full capabilities, and it is also possible you are running OpenSSL 1.0.2 necessitating that you do this.
+
+* Enable and start nginx:
+
+```shell
+ # rc-update add nginx default
+ # /etc/init.d/nginx start
+```
+
+If you are using certbot, it is HIGHLY recommend you set up a cron job that renews your certificate, and that you install the suggested `certbot-nginx` plugin. If you don't do these things, you only have yourself to blame when your instance breaks suddenly because you forgot about it.
+
+First, ensure that the command you will be installing into your crontab works.
+
+```shell
+ # /usr/bin/certbot renew --nginx
+```
+
+Assuming not much time has passed since you got certbot working a few steps ago, you should get a message for all domains you installed certificates for saying `Cert not yet due for renewal`.
+
+Now, run crontab as a superuser with `crontab -e` or `sudo crontab -e` as appropriate, and add the following line to your cron:
+
+```cron
+0 0 1 * * /usr/bin/certbot renew --nginx
+```
+
+This will run certbot on the first of the month at midnight. If you'd rather run more frequently, it's not a bad idea, feel free to go for it.
+
+#### Other webserver/proxies
+
+If you would like to use other webservers or proxies, there are example configurations for some popular alternatives in `/home/pleroma/pleroma/installation/`. You can, of course, check out [the Gentoo wiki](https://wiki.gentoo.org) for more information on installing and configuring said alternatives.
+
+#### Create the uploads folder
+
+Even if you are using S3, Pleroma needs someplace to store media posted on your instance. If you are using the `/home/pleroma/pleroma` root folder suggested by this guide, simply:
+
+```shell
+ pleroma$ mkdir -p ~/pleroma/uploads
+ ```
+
+#### init.d service
+
+* Copy example service file
+
+```shell
+ # cp /home/pleroma/pleroma/installation/init.d/pleroma /etc/init.d/
+```
+
+* Be sure to take a look at this service file and make sure that all paths fit your installation
+
+* Enable and start `pleroma`:
+
+```shell
+ # rc-update add pleroma default
+ # /etc/init.d/pleroma start
+```
+
+#### 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
+pleroma$ MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
+```
+
+#### Privilege cleanup
+
+If you opted to allow sudo for the `pleroma` user but would like to remove the ability for greater security, now might be a good time to edit `/etc/sudoers` and/or change the groups the `pleroma` user belongs to. Be sure to restart the pleroma service afterwards to ensure it picks up on the changes.
+
+#### Further reading
+
+* [Admin tasks](Admin tasks)
+* [Backup your instance](Backup-your-instance)
+* [Configuration tips](General tips for customizing pleroma fe)
+* [Hardening your instance](Hardening-your-instance)
+* [How to activate mediaproxy](How-to-activate-mediaproxy)
+* [Small Pleroma-FE customizations](Small customizations)
+* [Updating your instance](Updating-your-instance)
+
+## Questions
+
+Questions about the installation or didn’t it work as it should be, ask in [#pleroma:matrix.org](https://matrix.heldscal.la/#/room/#freenode_#pleroma:matrix.org) or IRC Channel **#pleroma** on **Freenode**.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-03 10:54:22 +0000