From 75290cbfbd0f93cf3ecec5f44c4624b8c8601c51 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Thu, 26 Sep 2019 18:49:57 +0700 Subject: Add Pleroma.JobQueueMonitor --- lib/pleroma/application.ex | 1 + lib/pleroma/healthcheck.ex | 8 +++ lib/pleroma/job_queue_monitor.ex | 115 +++++++++++++++++++++++++++++++++++ lib/pleroma/workers/worker_helper.ex | 1 + test/healthcheck_test.exs | 9 ++- 5 files changed, 133 insertions(+), 1 deletion(-) create mode 100644 lib/pleroma/job_queue_monitor.ex diff --git a/lib/pleroma/application.ex b/lib/pleroma/application.ex index 7aec2c545..3e21d4403 100644 --- a/lib/pleroma/application.ex +++ b/lib/pleroma/application.ex @@ -42,6 +42,7 @@ defmodule Pleroma.Application do hackney_pool_children() ++ [ Pleroma.Stats, + Pleroma.JobQueueMonitor, {Oban, Pleroma.Config.get(Oban)} ] ++ task_children(@env) ++ diff --git a/lib/pleroma/healthcheck.ex b/lib/pleroma/healthcheck.ex index 977b78c26..fc2129815 100644 --- a/lib/pleroma/healthcheck.ex +++ b/lib/pleroma/healthcheck.ex @@ -14,6 +14,7 @@ defmodule Pleroma.Healthcheck do active: 0, idle: 0, memory_used: 0, + job_queue_stats: nil, healthy: true @type t :: %__MODULE__{ @@ -21,6 +22,7 @@ defmodule Pleroma.Healthcheck do active: non_neg_integer(), idle: non_neg_integer(), memory_used: number(), + job_queue_stats: map(), healthy: boolean() } @@ -30,6 +32,7 @@ defmodule Pleroma.Healthcheck do memory_used: Float.round(:erlang.memory(:total) / 1024 / 1024, 2) } |> assign_db_info() + |> assign_job_queue_stats() |> check_health() end @@ -55,6 +58,11 @@ defmodule Pleroma.Healthcheck do Map.merge(healthcheck, db_info) end + defp assign_job_queue_stats(healthcheck) do + stats = Pleroma.JobQueueMonitor.stats() + Map.put(healthcheck, :job_queue_stats, stats) + end + @spec check_health(Healthcheck.t()) :: Healthcheck.t() def check_health(%{pool_size: pool_size, active: active} = check) when active >= pool_size do diff --git a/lib/pleroma/job_queue_monitor.ex b/lib/pleroma/job_queue_monitor.ex new file mode 100644 index 000000000..685ba2ead --- /dev/null +++ b/lib/pleroma/job_queue_monitor.ex @@ -0,0 +1,115 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.JobQueueMonitor do + use GenServer + + @initial_state %{workers: %{}, queues: %{}, processed_jobs: 0, enqueued: 0} + @queue %{processed_jobs: 0, success: 0, failure: 0, enqueued: 0} + @operation %{processed_jobs: 0, success: 0, failure: 0, enqueued: 0} + + def start_link(_) do + GenServer.start_link(__MODULE__, @initial_state, name: __MODULE__) + end + + @impl true + def init(state) do + :telemetry.attach("oban-monitor-failure", [:oban, :failure], &handle_event/4, nil) + :telemetry.attach("oban-monitor-success", [:oban, :success], &handle_event/4, nil) + + {:ok, state} + end + + def stats do + GenServer.call(__MODULE__, :stats) + end + + def enqueue({:ok, job}) do + meta = Map.take(job, [:args, :queue, :worker]) + GenServer.cast(__MODULE__, {:process_enqueue, meta}) + + {:ok, job} + end + + def enqueue(result), do: result + + def handle_event([:oban, status], %{duration: duration}, meta, _) do + GenServer.cast(__MODULE__, {:process_event, status, duration, meta}) + end + + @impl true + def handle_call(:stats, _from, state) do + {:reply, state, state} + end + + def handle_cast({:process_enqueue, meta}, state) do + state = + state + |> Map.update!(:workers, fn workers -> + workers + |> Map.put_new(meta.worker, %{}) + |> Map.update!(meta.worker, &update_worker(&1, :enqueue, meta)) + end) + |> Map.update!(:queues, fn workers -> + workers + |> Map.put_new(meta.queue, @queue) + |> Map.update!(meta.queue, fn queue -> Map.update!(queue, :enqueued, &(&1 + 1)) end) + end) + |> Map.update!(:enqueued, &(&1 + 1)) + + {:noreply, state} + end + + @impl true + def handle_cast({:process_event, status, duration, meta}, state) do + state = + state + |> Map.update!(:workers, fn workers -> + workers + |> Map.put_new(meta.worker, %{}) + |> Map.update!(meta.worker, &update_worker(&1, status, meta, duration)) + end) + |> Map.update!(:queues, fn workers -> + workers + |> Map.put_new(meta.queue, @queue) + |> Map.update!(meta.queue, &update_queue(&1, status, meta, duration)) + end) + |> Map.update!(:processed_jobs, &(&1 + 1)) + |> decr_enqueued() + + {:noreply, state} + end + + defp update_worker(worker, status, meta, duration \\ 0) do + worker + |> Map.put_new(meta.args["op"], @operation) + |> Map.update!(meta.args["op"], &update_op(&1, status, meta, duration)) + end + + defp update_op(op, :enqueue, _meta, _duration) do + op + |> Map.update!(:enqueued, &(&1 + 1)) + end + + defp update_op(op, status, _meta, _duration) do + op + |> Map.update!(:processed_jobs, &(&1 + 1)) + |> Map.update!(status, &(&1 + 1)) + |> decr_enqueued() + end + + defp update_queue(queue, status, _meta, _duration) do + queue + |> Map.update!(:processed_jobs, &(&1 + 1)) + |> Map.update!(status, &(&1 + 1)) + |> decr_enqueued() + end + + defp decr_enqueued(map) do + Map.update!(map, :enqueued, fn + 0 -> 0 + enqueued -> enqueued - 1 + end) + end +end diff --git a/lib/pleroma/workers/worker_helper.ex b/lib/pleroma/workers/worker_helper.ex index 358efa14a..a43ce8bc0 100644 --- a/lib/pleroma/workers/worker_helper.ex +++ b/lib/pleroma/workers/worker_helper.ex @@ -40,6 +40,7 @@ defmodule Pleroma.Workers.WorkerHelper do unquote(caller_module) |> apply(:new, [params, worker_args]) |> Pleroma.Repo.insert() + |> Pleroma.JobQueueMonitor.enqueue() end end end diff --git a/test/healthcheck_test.exs b/test/healthcheck_test.exs index 6bb8d5b7f..66d5026ff 100644 --- a/test/healthcheck_test.exs +++ b/test/healthcheck_test.exs @@ -9,7 +9,14 @@ defmodule Pleroma.HealthcheckTest do test "system_info/0" do result = Healthcheck.system_info() |> Map.from_struct() - assert Map.keys(result) == [:active, :healthy, :idle, :memory_used, :pool_size] + assert Map.keys(result) == [ + :active, + :healthy, + :idle, + :job_queue_stats, + :memory_used, + :pool_size + ] end describe "check_health/1" do -- cgit v1.2.3 From 26693292f4b2062504fc9a24e824a6f56cb6b555 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 2 Oct 2019 14:50:25 +0700 Subject: Remove `:enqueued` counter --- lib/pleroma/job_queue_monitor.ex | 45 ++++-------------------------------- lib/pleroma/workers/worker_helper.ex | 1 - 2 files changed, 4 insertions(+), 42 deletions(-) diff --git a/lib/pleroma/job_queue_monitor.ex b/lib/pleroma/job_queue_monitor.ex index 685ba2ead..3feea8381 100644 --- a/lib/pleroma/job_queue_monitor.ex +++ b/lib/pleroma/job_queue_monitor.ex @@ -5,9 +5,9 @@ defmodule Pleroma.JobQueueMonitor do use GenServer - @initial_state %{workers: %{}, queues: %{}, processed_jobs: 0, enqueued: 0} - @queue %{processed_jobs: 0, success: 0, failure: 0, enqueued: 0} - @operation %{processed_jobs: 0, success: 0, failure: 0, enqueued: 0} + @initial_state %{workers: %{}, queues: %{}, processed_jobs: 0} + @queue %{processed_jobs: 0, success: 0, failure: 0} + @operation %{processed_jobs: 0, success: 0, failure: 0} def start_link(_) do GenServer.start_link(__MODULE__, @initial_state, name: __MODULE__) @@ -25,15 +25,6 @@ defmodule Pleroma.JobQueueMonitor do GenServer.call(__MODULE__, :stats) end - def enqueue({:ok, job}) do - meta = Map.take(job, [:args, :queue, :worker]) - GenServer.cast(__MODULE__, {:process_enqueue, meta}) - - {:ok, job} - end - - def enqueue(result), do: result - def handle_event([:oban, status], %{duration: duration}, meta, _) do GenServer.cast(__MODULE__, {:process_event, status, duration, meta}) end @@ -43,24 +34,6 @@ defmodule Pleroma.JobQueueMonitor do {:reply, state, state} end - def handle_cast({:process_enqueue, meta}, state) do - state = - state - |> Map.update!(:workers, fn workers -> - workers - |> Map.put_new(meta.worker, %{}) - |> Map.update!(meta.worker, &update_worker(&1, :enqueue, meta)) - end) - |> Map.update!(:queues, fn workers -> - workers - |> Map.put_new(meta.queue, @queue) - |> Map.update!(meta.queue, fn queue -> Map.update!(queue, :enqueued, &(&1 + 1)) end) - end) - |> Map.update!(:enqueued, &(&1 + 1)) - - {:noreply, state} - end - @impl true def handle_cast({:process_event, status, duration, meta}, state) do state = @@ -76,12 +49,11 @@ defmodule Pleroma.JobQueueMonitor do |> Map.update!(meta.queue, &update_queue(&1, status, meta, duration)) end) |> Map.update!(:processed_jobs, &(&1 + 1)) - |> decr_enqueued() {:noreply, state} end - defp update_worker(worker, status, meta, duration \\ 0) do + defp update_worker(worker, status, meta, duration) do worker |> Map.put_new(meta.args["op"], @operation) |> Map.update!(meta.args["op"], &update_op(&1, status, meta, duration)) @@ -96,20 +68,11 @@ defmodule Pleroma.JobQueueMonitor do op |> Map.update!(:processed_jobs, &(&1 + 1)) |> Map.update!(status, &(&1 + 1)) - |> decr_enqueued() end defp update_queue(queue, status, _meta, _duration) do queue |> Map.update!(:processed_jobs, &(&1 + 1)) |> Map.update!(status, &(&1 + 1)) - |> decr_enqueued() - end - - defp decr_enqueued(map) do - Map.update!(map, :enqueued, fn - 0 -> 0 - enqueued -> enqueued - 1 - end) end end diff --git a/lib/pleroma/workers/worker_helper.ex b/lib/pleroma/workers/worker_helper.ex index a43ce8bc0..358efa14a 100644 --- a/lib/pleroma/workers/worker_helper.ex +++ b/lib/pleroma/workers/worker_helper.ex @@ -40,7 +40,6 @@ defmodule Pleroma.Workers.WorkerHelper do unquote(caller_module) |> apply(:new, [params, worker_args]) |> Pleroma.Repo.insert() - |> Pleroma.JobQueueMonitor.enqueue() end end end -- cgit v1.2.3 From 93f966ea4bb2b4d551cb3e248150809554deddc8 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 2 Oct 2019 14:51:30 +0700 Subject: Update CHANGELOG and pleroma_api.md --- CHANGELOG.md | 1 + docs/api/pleroma_api.md | 9 +++++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a76e6cf8..0a88f9d75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] ### Added - Refreshing poll results for remote polls +- Job queue stats to the healthcheck page - Admin API: Add ability to require password reset ### Changed diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md index a469ddfbf..dfd6623ec 100644 --- a/docs/api/pleroma_api.md +++ b/docs/api/pleroma_api.md @@ -317,7 +317,8 @@ See [Admin-API](Admin-API.md) "active": 0, # active processes "idle": 0, # idle processes "memory_used": 0.00, # Memory used - "healthy": true # Instance state + "healthy": true, # Instance state + "job_queue_stats": {} # Job queue stats } ``` @@ -391,7 +392,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa ### Update a file in a custom emoji pack * Method `POST` * Authentication: required -* Params: +* Params: * if the `action` is `add`, adds an emoji named `shortcode` to the pack `pack_name`, that means that the emoji file needs to be uploaded with the request (thus requiring it to be a multipart request) and be named `file`. @@ -408,7 +409,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa ### Updates (replaces) pack metadata * Method `POST` * Authentication: required -* Params: +* Params: * `new_data`: new metadata to replace the old one * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a problem with the new metadata (the error is specified in the "error" part of the response JSON) @@ -417,7 +418,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa ### Requests the instance to download the pack from another instance * Method `POST` * Authentication: required -* Params: +* Params: * `instance_address`: the address of the instance to download from * `pack_name`: the pack to download from that instance * Response: JSON, "ok" and 200 status if the pack was downloaded, or 500 if there were -- cgit v1.2.3 From 0fc29deba06b6a897f3534ce68abfdadcab12a6b Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 2 Oct 2019 15:24:21 +0700 Subject: Add tests for Pleroma.JobQueueMonitor --- test/job_queue_monitor_test.exs | 70 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 test/job_queue_monitor_test.exs diff --git a/test/job_queue_monitor_test.exs b/test/job_queue_monitor_test.exs new file mode 100644 index 000000000..17c6f3246 --- /dev/null +++ b/test/job_queue_monitor_test.exs @@ -0,0 +1,70 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.JobQueueMonitorTest do + use ExUnit.Case, async: true + + alias Pleroma.JobQueueMonitor + + @success {:process_event, :success, 1337, + %{ + args: %{"op" => "refresh_subscriptions"}, + attempt: 1, + id: 339, + max_attempts: 5, + queue: "federator_outgoing", + worker: "Pleroma.Workers.SubscriberWorker" + }} + + @failure {:process_event, :failure, 22_521_134, + %{ + args: %{"op" => "force_password_reset", "user_id" => "9nJG6n6Nbu7tj9GJX6"}, + attempt: 1, + error: %RuntimeError{message: "oops"}, + id: 345, + kind: :exception, + max_attempts: 1, + queue: "background", + stack: [ + {Pleroma.Workers.BackgroundWorker, :perform, 2, + [file: 'lib/pleroma/workers/background_worker.ex', line: 31]}, + {Oban.Queue.Executor, :safe_call, 1, + [file: 'lib/oban/queue/executor.ex', line: 42]}, + {:timer, :tc, 3, [file: 'timer.erl', line: 197]}, + {Oban.Queue.Executor, :call, 2, [file: 'lib/oban/queue/executor.ex', line: 23]}, + {Task.Supervised, :invoke_mfa, 2, [file: 'lib/task/supervised.ex', line: 90]}, + {:proc_lib, :init_p_do_apply, 3, [file: 'proc_lib.erl', line: 249]} + ], + worker: "Pleroma.Workers.BackgroundWorker" + }} + + test "stats/0" do + assert %{processed_jobs: _, queues: _, workers: _} = JobQueueMonitor.stats() + end + + test "handle_cast/2" do + state = %{workers: %{}, queues: %{}, processed_jobs: 0} + + assert {:noreply, state} = JobQueueMonitor.handle_cast(@success, state) + assert {:noreply, state} = JobQueueMonitor.handle_cast(@failure, state) + assert {:noreply, state} = JobQueueMonitor.handle_cast(@success, state) + assert {:noreply, state} = JobQueueMonitor.handle_cast(@failure, state) + + assert state == %{ + processed_jobs: 4, + queues: %{ + "background" => %{failure: 2, processed_jobs: 2, success: 0}, + "federator_outgoing" => %{failure: 0, processed_jobs: 2, success: 2} + }, + workers: %{ + "Pleroma.Workers.BackgroundWorker" => %{ + "force_password_reset" => %{failure: 2, processed_jobs: 2, success: 0} + }, + "Pleroma.Workers.SubscriberWorker" => %{ + "refresh_subscriptions" => %{failure: 0, processed_jobs: 2, success: 2} + } + } + } + end +end -- cgit v1.2.3 From 1c6e1055c876c7ac4a4d42259aebd07c942561e2 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 2 Oct 2019 19:16:34 +0700 Subject: Add CustomEmojiController --- .../controllers/custom_emoji_controller.ex | 11 +++++++++ .../controllers/mastodon_api_controller.ex | 28 ++++------------------ .../web/mastodon_api/views/custom_emoji_view.ex | 28 ++++++++++++++++++++++ lib/pleroma/web/router.ex | 7 +++--- test/web/activity_pub/transmogrifier_test.exs | 1 - .../controllers/custom_emoji_controller_test.exs | 22 +++++++++++++++++ .../mastodon_api/mastodon_api_controller_test.exs | 17 ------------- 7 files changed, 68 insertions(+), 46 deletions(-) create mode 100644 lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex create mode 100644 lib/pleroma/web/mastodon_api/views/custom_emoji_view.ex create mode 100644 test/web/mastodon_api/controllers/custom_emoji_controller_test.exs diff --git a/lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex b/lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex new file mode 100644 index 000000000..391c0648b --- /dev/null +++ b/lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex @@ -0,0 +1,11 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.Web.MastodonAPI.CustomEmojiController do + use Pleroma.Web, :controller + + def index(conn, _params) do + render(conn, "index.json", custom_emojis: Pleroma.Emoji.get_all()) + end +end diff --git a/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex b/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex index 98dd9f375..a66335c02 100644 --- a/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex +++ b/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex @@ -11,7 +11,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIController do alias Pleroma.Config alias Pleroma.Pagination alias Pleroma.User - alias Pleroma.Web alias Pleroma.Web.ActivityPub.ActivityPub alias Pleroma.Web.CommonAPI alias Pleroma.Web.MastodonAPI.AccountView @@ -22,28 +21,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIController do action_fallback(Pleroma.Web.MastodonAPI.FallbackController) - defp mastodonized_emoji do - Pleroma.Emoji.get_all() - |> Enum.map(fn {shortcode, %Pleroma.Emoji{file: relative_url, tags: tags}} -> - url = to_string(URI.merge(Web.base_url(), relative_url)) - - %{ - "shortcode" => shortcode, - "static_url" => url, - "visible_in_picker" => true, - "url" => url, - "tags" => tags, - # Assuming that a comma is authorized in the category name - "category" => (tags -- ["Custom"]) |> Enum.join(",") - } - end) - end - - def custom_emojis(conn, _params) do - mastodon_emoji = mastodonized_emoji() - json(conn, mastodon_emoji) - end - def follows(%{assigns: %{user: follower}} = conn, %{"uri" => uri}) do with {_, %User{} = followed} <- {:followed, User.get_cached_by_nickname(uri)}, {_, true} <- {:followed, follower.id != followed.id}, @@ -114,7 +91,10 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIController do token = get_session(conn, :oauth_token) if user && token do - mastodon_emoji = mastodonized_emoji() + mastodon_emoji = + Pleroma.Web.MastodonAPI.CustomEmojiView.render("index.json", %{ + custom_emojis: Pleroma.Emoji.get_all() + }) limit = Config.get([:instance, :limit]) diff --git a/lib/pleroma/web/mastodon_api/views/custom_emoji_view.ex b/lib/pleroma/web/mastodon_api/views/custom_emoji_view.ex new file mode 100644 index 000000000..cb8688941 --- /dev/null +++ b/lib/pleroma/web/mastodon_api/views/custom_emoji_view.ex @@ -0,0 +1,28 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.Web.MastodonAPI.CustomEmojiView do + use Pleroma.Web, :view + + alias Pleroma.Emoji + alias Pleroma.Web + + def render("index.json", %{custom_emojis: custom_emojis}) do + render_many(custom_emojis, __MODULE__, "show.json") + end + + def render("show.json", %{custom_emoji: {shortcode, %Emoji{file: relative_url, tags: tags}}}) do + url = Web.base_url() |> URI.merge(relative_url) |> to_string() + + %{ + "shortcode" => shortcode, + "static_url" => url, + "visible_in_picker" => true, + "url" => url, + "tags" => tags, + # Assuming that a comma is authorized in the category name + "category" => tags |> List.delete("Custom") |> Enum.join(",") + } + end +end diff --git a/lib/pleroma/web/router.ex b/lib/pleroma/web/router.ex index a355a14bd..5d14c7742 100644 --- a/lib/pleroma/web/router.ex +++ b/lib/pleroma/web/router.ex @@ -461,6 +461,7 @@ defmodule Pleroma.Web.Router do pipe_through(:api) post("/accounts", AccountController, :create) + get("/accounts/search", SearchController, :account_search) get("/instance", InstanceController, :show) get("/instance/peers", InstanceController, :peers) @@ -468,15 +469,13 @@ defmodule Pleroma.Web.Router do post("/apps", AppController, :create) get("/apps/verify_credentials", AppController, :verify_credentials) - get("/custom_emojis", MastodonAPIController, :custom_emojis) - get("/statuses/:id/card", StatusController, :card) get("/statuses/:id/favourited_by", StatusController, :favourited_by) get("/statuses/:id/reblogged_by", StatusController, :reblogged_by) - get("/trends", MastodonAPIController, :empty_array) + get("/custom_emojis", CustomEmojiController, :index) - get("/accounts/search", SearchController, :account_search) + get("/trends", MastodonAPIController, :empty_array) scope [] do pipe_through(:oauth_read_or_public) diff --git a/test/web/activity_pub/transmogrifier_test.exs b/test/web/activity_pub/transmogrifier_test.exs index b995f0224..6c208bdc0 100644 --- a/test/web/activity_pub/transmogrifier_test.exs +++ b/test/web/activity_pub/transmogrifier_test.exs @@ -1084,7 +1084,6 @@ defmodule Pleroma.Web.ActivityPub.TransmogrifierTest do {:ok, announce_activity, _} = CommonAPI.repeat(activity.id, user) {:ok, modified} = Transmogrifier.prepare_outgoing(announce_activity.data) - object = modified["object"] assert modified["object"]["content"] == "hey" assert modified["object"]["actor"] == modified["object"]["attributedTo"] diff --git a/test/web/mastodon_api/controllers/custom_emoji_controller_test.exs b/test/web/mastodon_api/controllers/custom_emoji_controller_test.exs new file mode 100644 index 000000000..2d988b0b8 --- /dev/null +++ b/test/web/mastodon_api/controllers/custom_emoji_controller_test.exs @@ -0,0 +1,22 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.Web.MastodonAPI.CustomEmojiControllerTest do + use Pleroma.Web.ConnCase, async: true + + test "with tags", %{conn: conn} do + [emoji | _body] = + conn + |> get("/api/v1/custom_emojis") + |> json_response(200) + + assert Map.has_key?(emoji, "shortcode") + assert Map.has_key?(emoji, "static_url") + assert Map.has_key?(emoji, "tags") + assert is_list(emoji["tags"]) + assert Map.has_key?(emoji, "category") + assert Map.has_key?(emoji, "url") + assert Map.has_key?(emoji, "visible_in_picker") + end +end diff --git a/test/web/mastodon_api/mastodon_api_controller_test.exs b/test/web/mastodon_api/mastodon_api_controller_test.exs index 7a58b13dc..e8fd4827c 100644 --- a/test/web/mastodon_api/mastodon_api_controller_test.exs +++ b/test/web/mastodon_api/mastodon_api_controller_test.exs @@ -159,23 +159,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIControllerTest do end end - describe "custom emoji" do - test "with tags", %{conn: conn} do - [emoji | _body] = - conn - |> get("/api/v1/custom_emojis") - |> json_response(200) - - assert Map.has_key?(emoji, "shortcode") - assert Map.has_key?(emoji, "static_url") - assert Map.has_key?(emoji, "tags") - assert is_list(emoji["tags"]) - assert Map.has_key?(emoji, "category") - assert Map.has_key?(emoji, "url") - assert Map.has_key?(emoji, "visible_in_picker") - end - end - describe "index/2 redirections" do setup %{conn: conn} do session_opts = [ -- cgit v1.2.3 From d3c404af124c7083b1f23466b9e82df5d2a407d0 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 2 Oct 2019 20:05:14 +0700 Subject: Add MastoFEController --- lib/pleroma/web/masto_fe_controller.ex | 36 ++++++ .../mastodon_api/controllers/auth_controller.ex | 2 +- .../controllers/mastodon_api_controller.ex | 124 --------------------- .../web/mastodon_api/views/mastodon_view.ex | 8 -- lib/pleroma/web/router.ex | 14 +-- lib/pleroma/web/templates/masto_fe/index.html.eex | 31 ++++++ .../templates/mastodon_api/mastodon/index.html.eex | 31 ------ lib/pleroma/web/views/masto_fe_view.ex | 102 +++++++++++++++++ test/web/masto_fe_controller_test.exs | 83 ++++++++++++++ .../mastodon_api/mastodon_api_controller_test.exs | 72 ------------ 10 files changed, 260 insertions(+), 243 deletions(-) create mode 100644 lib/pleroma/web/masto_fe_controller.ex delete mode 100644 lib/pleroma/web/mastodon_api/views/mastodon_view.ex create mode 100644 lib/pleroma/web/templates/masto_fe/index.html.eex delete mode 100644 lib/pleroma/web/templates/mastodon_api/mastodon/index.html.eex create mode 100644 lib/pleroma/web/views/masto_fe_view.ex create mode 100644 test/web/masto_fe_controller_test.exs diff --git a/lib/pleroma/web/masto_fe_controller.ex b/lib/pleroma/web/masto_fe_controller.ex new file mode 100644 index 000000000..ac9af7502 --- /dev/null +++ b/lib/pleroma/web/masto_fe_controller.ex @@ -0,0 +1,36 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.Web.MastoFEController do + use Pleroma.Web, :controller + + alias Pleroma.User + + @doc "GET /web/*path" + def index(%{assigns: %{user: user}} = conn, _params) do + token = get_session(conn, :oauth_token) + + if user && token do + conn + |> put_layout(false) + |> render("index.html", token: token, user: user, custom_emojis: Pleroma.Emoji.get_all()) + else + conn + |> put_session(:return_to, conn.request_path) + |> redirect(to: "/web/login") + end + end + + @doc "PUT /api/web/settings" + def put_settings(%{assigns: %{user: user}} = conn, %{"data" => settings} = _params) do + with {:ok, _} <- User.update_info(user, &User.Info.mastodon_settings_update(&1, settings)) do + json(conn, %{}) + else + e -> + conn + |> put_status(:internal_server_error) + |> json(%{error: inspect(e)}) + end + end +end diff --git a/lib/pleroma/web/mastodon_api/controllers/auth_controller.ex b/lib/pleroma/web/mastodon_api/controllers/auth_controller.ex index 0dee670af..bfd5120ba 100644 --- a/lib/pleroma/web/mastodon_api/controllers/auth_controller.ex +++ b/lib/pleroma/web/mastodon_api/controllers/auth_controller.ex @@ -75,7 +75,7 @@ defmodule Pleroma.Web.MastodonAPI.AuthController do defp local_mastodon_root_path(conn) do case get_session(conn, :return_to) do nil -> - mastodon_api_path(conn, :index, ["getting-started"]) + masto_fe_path(conn, :index, ["getting-started"]) return_to -> delete_session(conn, :return_to) diff --git a/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex b/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex index a66335c02..e92f5d089 100644 --- a/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex +++ b/lib/pleroma/web/mastodon_api/controllers/mastodon_api_controller.ex @@ -8,13 +8,11 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIController do import Pleroma.Web.ControllerHelper, only: [add_link_headers: 2] alias Pleroma.Bookmark - alias Pleroma.Config alias Pleroma.Pagination alias Pleroma.User alias Pleroma.Web.ActivityPub.ActivityPub alias Pleroma.Web.CommonAPI alias Pleroma.Web.MastodonAPI.AccountView - alias Pleroma.Web.MastodonAPI.MastodonView alias Pleroma.Web.MastodonAPI.StatusView require Logger @@ -87,124 +85,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIController do |> render("index.json", %{activities: activities, for: user, as: :activity}) end - def index(%{assigns: %{user: user}} = conn, _params) do - token = get_session(conn, :oauth_token) - - if user && token do - mastodon_emoji = - Pleroma.Web.MastodonAPI.CustomEmojiView.render("index.json", %{ - custom_emojis: Pleroma.Emoji.get_all() - }) - - limit = Config.get([:instance, :limit]) - - accounts = Map.put(%{}, user.id, AccountView.render("show.json", %{user: user, for: user})) - - initial_state = - %{ - meta: %{ - streaming_api_base_url: Pleroma.Web.Endpoint.websocket_url(), - access_token: token, - locale: "en", - domain: Pleroma.Web.Endpoint.host(), - admin: "1", - me: "#{user.id}", - unfollow_modal: false, - boost_modal: false, - delete_modal: true, - auto_play_gif: false, - display_sensitive_media: false, - reduce_motion: false, - max_toot_chars: limit, - mascot: User.get_mascot(user)["url"] - }, - poll_limits: Config.get([:instance, :poll_limits]), - rights: %{ - delete_others_notice: present?(user.info.is_moderator), - admin: present?(user.info.is_admin) - }, - compose: %{ - me: "#{user.id}", - default_privacy: user.info.default_scope, - default_sensitive: false, - allow_content_types: Config.get([:instance, :allowed_post_formats]) - }, - media_attachments: %{ - accept_content_types: [ - ".jpg", - ".jpeg", - ".png", - ".gif", - ".webm", - ".mp4", - ".m4v", - "image\/jpeg", - "image\/png", - "image\/gif", - "video\/webm", - "video\/mp4" - ] - }, - settings: - user.info.settings || - %{ - onboarded: true, - home: %{ - shows: %{ - reblog: true, - reply: true - } - }, - notifications: %{ - alerts: %{ - follow: true, - favourite: true, - reblog: true, - mention: true - }, - shows: %{ - follow: true, - favourite: true, - reblog: true, - mention: true - }, - sounds: %{ - follow: true, - favourite: true, - reblog: true, - mention: true - } - } - }, - push_subscription: nil, - accounts: accounts, - custom_emojis: mastodon_emoji, - char_limit: limit - } - |> Jason.encode!() - - conn - |> put_layout(false) - |> put_view(MastodonView) - |> render("index.html", %{initial_state: initial_state}) - else - conn - |> put_session(:return_to, conn.request_path) - |> redirect(to: "/web/login") - end - end - - def put_settings(%{assigns: %{user: user}} = conn, %{"data" => settings} = _params) do - with {:ok, _} <- User.update_info(user, &User.Info.mastodon_settings_update(&1, settings)) do - json(conn, %{}) - else - e -> - conn - |> put_status(:internal_server_error) - |> json(%{error: inspect(e)}) - end - end - # Stubs for unimplemented mastodon api # def empty_array(conn, _) do @@ -216,8 +96,4 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIController do Logger.debug("Unimplemented, returning an empty object") json(conn, %{}) end - - defp present?(nil), do: false - defp present?(false), do: false - defp present?(_), do: true end diff --git a/lib/pleroma/web/mastodon_api/views/mastodon_view.ex b/lib/pleroma/web/mastodon_api/views/mastodon_view.ex deleted file mode 100644 index 33b9a74be..000000000 --- a/lib/pleroma/web/mastodon_api/views/mastodon_view.ex +++ /dev/null @@ -1,8 +0,0 @@ -# Pleroma: A lightweight social networking server -# Copyright © 2017-2019 Pleroma Authors -# SPDX-License-Identifier: AGPL-3.0-only - -defmodule Pleroma.Web.MastodonAPI.MastodonView do - use Pleroma.Web, :view - import Phoenix.HTML -end diff --git a/lib/pleroma/web/router.ex b/lib/pleroma/web/router.ex index 5d14c7742..f91af8137 100644 --- a/lib/pleroma/web/router.ex +++ b/lib/pleroma/web/router.ex @@ -451,10 +451,10 @@ defmodule Pleroma.Web.Router do end end - scope "/api/web", Pleroma.Web.MastodonAPI do + scope "/api/web", Pleroma.Web do pipe_through([:authenticated_api, :oauth_write]) - put("/settings", MastodonAPIController, :put_settings) + put("/settings", MastoFEController, :put_settings) end scope "/api/v1", Pleroma.Web.MastodonAPI do @@ -658,17 +658,17 @@ defmodule Pleroma.Web.Router do get("/:version", Nodeinfo.NodeinfoController, :nodeinfo) end - scope "/", Pleroma.Web.MastodonAPI do + scope "/", Pleroma.Web do pipe_through(:mastodon_html) - get("/web/login", AuthController, :login) - delete("/auth/sign_out", AuthController, :logout) + get("/web/login", MastodonAPI.AuthController, :login) + delete("/auth/sign_out", MastodonAPI.AuthController, :logout) - post("/auth/password", AuthController, :password_reset) + post("/auth/password", MastodonAPI.AuthController, :password_reset) scope [] do pipe_through(:oauth_read) - get("/web/*path", MastodonAPIController, :index) + get("/web/*path", MastoFEController, :index) end end diff --git a/lib/pleroma/web/templates/masto_fe/index.html.eex b/lib/pleroma/web/templates/masto_fe/index.html.eex new file mode 100644 index 000000000..feff36fae --- /dev/null +++ b/lib/pleroma/web/templates/masto_fe/index.html.eex @@ -0,0 +1,31 @@ + + + + + + +<%= Pleroma.Config.get([:instance, :name]) %> + + + + + + + + + + + + + + + + + + + + +
+
+ + diff --git a/lib/pleroma/web/templates/mastodon_api/mastodon/index.html.eex b/lib/pleroma/web/templates/mastodon_api/mastodon/index.html.eex deleted file mode 100644 index 3325beca1..000000000 --- a/lib/pleroma/web/templates/mastodon_api/mastodon/index.html.eex +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - -<%= Pleroma.Config.get([:instance, :name]) %> - - - - - - - - - - - - - - - - - - - - -
-
- - diff --git a/lib/pleroma/web/views/masto_fe_view.ex b/lib/pleroma/web/views/masto_fe_view.ex new file mode 100644 index 000000000..21b086d4c --- /dev/null +++ b/lib/pleroma/web/views/masto_fe_view.ex @@ -0,0 +1,102 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.Web.MastoFEView do + use Pleroma.Web, :view + alias Pleroma.Config + alias Pleroma.User + alias Pleroma.Web.MastodonAPI.AccountView + alias Pleroma.Web.MastodonAPI.CustomEmojiView + + @default_settings %{ + onboarded: true, + home: %{ + shows: %{ + reblog: true, + reply: true + } + }, + notifications: %{ + alerts: %{ + follow: true, + favourite: true, + reblog: true, + mention: true + }, + shows: %{ + follow: true, + favourite: true, + reblog: true, + mention: true + }, + sounds: %{ + follow: true, + favourite: true, + reblog: true, + mention: true + } + } + } + + def initial_state(token, user, custom_emojis) do + limit = Config.get([:instance, :limit]) + + %{ + meta: %{ + streaming_api_base_url: Pleroma.Web.Endpoint.websocket_url(), + access_token: token, + locale: "en", + domain: Pleroma.Web.Endpoint.host(), + admin: "1", + me: "#{user.id}", + unfollow_modal: false, + boost_modal: false, + delete_modal: true, + auto_play_gif: false, + display_sensitive_media: false, + reduce_motion: false, + max_toot_chars: limit, + mascot: User.get_mascot(user)["url"] + }, + poll_limits: Config.get([:instance, :poll_limits]), + rights: %{ + delete_others_notice: present?(user.info.is_moderator), + admin: present?(user.info.is_admin) + }, + compose: %{ + me: "#{user.id}", + default_privacy: user.info.default_scope, + default_sensitive: false, + allow_content_types: Config.get([:instance, :allowed_post_formats]) + }, + media_attachments: %{ + accept_content_types: [ + ".jpg", + ".jpeg", + ".png", + ".gif", + ".webm", + ".mp4", + ".m4v", + "image\/jpeg", + "image\/png", + "image\/gif", + "video\/webm", + "video\/mp4" + ] + }, + settings: user.info.settings || @default_settings, + push_subscription: nil, + accounts: %{user.id => render(AccountView, "show.json", user: user, for: user)}, + custom_emojis: render(CustomEmojiView, "index.json", custom_emojis: custom_emojis), + char_limit: limit + } + |> Jason.encode!() + |> Phoenix.HTML.raw() + end + + defp present?(nil), do: false + defp present?(false), do: false + defp present?(_), do: true +end diff --git a/test/web/masto_fe_controller_test.exs b/test/web/masto_fe_controller_test.exs new file mode 100644 index 000000000..04f144049 --- /dev/null +++ b/test/web/masto_fe_controller_test.exs @@ -0,0 +1,83 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + +defmodule Pleroma.Web.MastodonAPI.MastoFEController do + use Pleroma.Web.ConnCase + + alias Pleroma.User + alias Pleroma.Config + import Pleroma.Factory + + clear_config([:instance, :public]) + + test "put settings", %{conn: conn} do + user = insert(:user) + + conn = + conn + |> assign(:user, user) + |> put("/api/web/settings", %{"data" => %{"programming" => "socks"}}) + + assert _result = json_response(conn, 200) + + user = User.get_cached_by_ap_id(user.ap_id) + assert user.info.settings == %{"programming" => "socks"} + end + + describe "index/2 redirections" do + setup %{conn: conn} do + session_opts = [ + store: :cookie, + key: "_test", + signing_salt: "cooldude" + ] + + conn = + conn + |> Plug.Session.call(Plug.Session.init(session_opts)) + |> fetch_session() + + test_path = "/web/statuses/test" + %{conn: conn, path: test_path} + end + + test "redirects not logged-in users to the login page", %{conn: conn, path: path} do + conn = get(conn, path) + + assert conn.status == 302 + assert redirected_to(conn) == "/web/login" + end + + test "redirects not logged-in users to the login page on private instances", %{ + conn: conn, + path: path + } do + Config.put([:instance, :public], false) + + conn = get(conn, path) + + assert conn.status == 302 + assert redirected_to(conn) == "/web/login" + end + + test "does not redirect logged in users to the login page", %{conn: conn, path: path} do + token = insert(:oauth_token) + + conn = + conn + |> assign(:user, token.user) + |> put_session(:oauth_token, token.token) + |> get(path) + + assert conn.status == 200 + end + + test "saves referer path to session", %{conn: conn, path: path} do + conn = get(conn, path) + return_to = Plug.Conn.get_session(conn, :return_to) + + assert return_to == path + end + end +end diff --git a/test/web/mastodon_api/mastodon_api_controller_test.exs b/test/web/mastodon_api/mastodon_api_controller_test.exs index e8fd4827c..c03003dac 100644 --- a/test/web/mastodon_api/mastodon_api_controller_test.exs +++ b/test/web/mastodon_api/mastodon_api_controller_test.exs @@ -5,7 +5,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIControllerTest do use Pleroma.Web.ConnCase - alias Pleroma.Config alias Pleroma.Notification alias Pleroma.Repo alias Pleroma.User @@ -19,7 +18,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIControllerTest do :ok end - clear_config([:instance, :public]) clear_config([:rich_media, :enabled]) test "getting a list of mutes", %{conn: conn} do @@ -113,20 +111,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIControllerTest do assert [] = json_response(third_conn, 200) end - test "put settings", %{conn: conn} do - user = insert(:user) - - conn = - conn - |> assign(:user, user) - |> put("/api/web/settings", %{"data" => %{"programming" => "socks"}}) - - assert _result = json_response(conn, 200) - - user = User.get_cached_by_ap_id(user.ap_id) - assert user.info.settings == %{"programming" => "socks"} - end - describe "link headers" do test "preserves parameters in link headers", %{conn: conn} do user = insert(:user) @@ -159,62 +143,6 @@ defmodule Pleroma.Web.MastodonAPI.MastodonAPIControllerTest do end end - describe "index/2 redirections" do - setup %{conn: conn} do - session_opts = [ - store: :cookie, - key: "_test", - signing_salt: "cooldude" - ] - - conn = - conn - |> Plug.Session.call(Plug.Session.init(session_opts)) - |> fetch_session() - - test_path = "/web/statuses/test" - %{conn: conn, path: test_path} - end - - test "redirects not logged-in users to the login page", %{conn: conn, path: path} do - conn = get(conn, path) - - assert conn.status == 302 - assert redirected_to(conn) == "/web/login" - end - - test "redirects not logged-in users to the login page on private instances", %{ - conn: conn, - path: path - } do - Config.put([:instance, :public], false) - - conn = get(conn, path) - - assert conn.status == 302 - assert redirected_to(conn) == "/web/login" - end - - test "does not redirect logged in users to the login page", %{conn: conn, path: path} do - token = insert(:oauth_token) - - conn = - conn - |> assign(:user, token.user) - |> put_session(:oauth_token, token.token) - |> get(path) - - assert conn.status == 200 - end - - test "saves referer path to session", %{conn: conn, path: path} do - conn = get(conn, path) - return_to = Plug.Conn.get_session(conn, :return_to) - - assert return_to == path - end - end - describe "empty_array, stubs for mastodon api" do test "GET /api/v1/accounts/:id/identity_proofs", %{conn: conn} do user = insert(:user) -- cgit v1.2.3 From 9b68aab8b3cf576f91566cd659e4e5719dccb15a Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 2 Oct 2019 21:12:01 +0700 Subject: Fix credo warning --- test/web/masto_fe_controller_test.exs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/test/web/masto_fe_controller_test.exs b/test/web/masto_fe_controller_test.exs index 04f144049..ab9dab352 100644 --- a/test/web/masto_fe_controller_test.exs +++ b/test/web/masto_fe_controller_test.exs @@ -5,8 +5,9 @@ defmodule Pleroma.Web.MastodonAPI.MastoFEController do use Pleroma.Web.ConnCase - alias Pleroma.User alias Pleroma.Config + alias Pleroma.User + import Pleroma.Factory clear_config([:instance, :public]) -- cgit v1.2.3 From acc62f327d45c0a9a0414da56bc339ec3e22cb63 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Wed, 2 Oct 2019 23:28:45 +0300 Subject: Rename some directories because MkDocs uses them for categories --- docs/API/admin_api.md | 763 ++++++++++++++++++++ docs/API/differences_in_mastoapi_responses.md | 149 ++++ docs/API/pleroma_api.md | 473 +++++++++++++ docs/API/prometheus.md | 22 + docs/admin/backup.md | 17 - docs/admin/updating.md | 9 - docs/administration/backup.md | 17 + docs/administration/updating.md | 9 + docs/api/admin_api.md | 763 -------------------- docs/api/differences_in_mastoapi_responses.md | 149 ---- docs/api/pleroma_api.md | 473 ------------- docs/api/prometheus.md | 22 - docs/config.md | 773 --------------------- .../General-tips-for-customizing-Pleroma-FE.md | 17 - docs/config/custom_emoji.md | 68 -- docs/config/hardening.md | 103 --- docs/config/howto_mediaproxy.md | 34 - docs/config/howto_mongooseim.md | 10 - docs/config/howto_proxy.md | 12 - ...howto_set_richmedia_cache_ttl_based_on_image.md | 33 - docs/config/howto_user_recomendation.md | 31 - docs/config/i2p.md | 196 ------ docs/config/mrf.md | 122 ---- docs/config/onion_federation.md | 159 ----- docs/config/small_customizations.md | 12 - docs/config/static_dir.md | 69 -- .../General-tips-for-customizing-Pleroma-FE.md | 17 + docs/configuration/config.md | 773 +++++++++++++++++++++ docs/configuration/custom_emoji.md | 68 ++ docs/configuration/hardening.md | 103 +++ docs/configuration/howto_mediaproxy.md | 34 + docs/configuration/howto_mongooseim.md | 10 + docs/configuration/howto_proxy.md | 12 + ...howto_set_richmedia_cache_ttl_based_on_image.md | 33 + docs/configuration/howto_user_recomendation.md | 31 + docs/configuration/i2p.md | 196 ++++++ docs/configuration/mrf.md | 122 ++++ docs/configuration/onion_federation.md | 159 +++++ docs/configuration/small_customizations.md | 12 + docs/configuration/static_dir.md | 69 ++ 40 files changed, 3072 insertions(+), 3072 deletions(-) create mode 100644 docs/API/admin_api.md create mode 100644 docs/API/differences_in_mastoapi_responses.md create mode 100644 docs/API/pleroma_api.md create mode 100644 docs/API/prometheus.md delete mode 100644 docs/admin/backup.md delete mode 100644 docs/admin/updating.md create mode 100644 docs/administration/backup.md create mode 100644 docs/administration/updating.md delete mode 100644 docs/api/admin_api.md delete mode 100644 docs/api/differences_in_mastoapi_responses.md delete mode 100644 docs/api/pleroma_api.md delete mode 100644 docs/api/prometheus.md delete mode 100644 docs/config.md delete mode 100644 docs/config/General-tips-for-customizing-Pleroma-FE.md delete mode 100644 docs/config/custom_emoji.md delete mode 100644 docs/config/hardening.md delete mode 100644 docs/config/howto_mediaproxy.md delete mode 100644 docs/config/howto_mongooseim.md delete mode 100644 docs/config/howto_proxy.md delete mode 100644 docs/config/howto_set_richmedia_cache_ttl_based_on_image.md delete mode 100644 docs/config/howto_user_recomendation.md delete mode 100644 docs/config/i2p.md delete mode 100644 docs/config/mrf.md delete mode 100644 docs/config/onion_federation.md delete mode 100644 docs/config/small_customizations.md delete mode 100644 docs/config/static_dir.md create mode 100644 docs/configuration/General-tips-for-customizing-Pleroma-FE.md create mode 100644 docs/configuration/config.md create mode 100644 docs/configuration/custom_emoji.md create mode 100644 docs/configuration/hardening.md create mode 100644 docs/configuration/howto_mediaproxy.md create mode 100644 docs/configuration/howto_mongooseim.md create mode 100644 docs/configuration/howto_proxy.md create mode 100644 docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md create mode 100644 docs/configuration/howto_user_recomendation.md create mode 100644 docs/configuration/i2p.md create mode 100644 docs/configuration/mrf.md create mode 100644 docs/configuration/onion_federation.md create mode 100644 docs/configuration/small_customizations.md create mode 100644 docs/configuration/static_dir.md diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md new file mode 100644 index 000000000..ee9e68cb1 --- /dev/null +++ b/docs/API/admin_api.md @@ -0,0 +1,763 @@ +# Admin API + +Authentication is required and the user must be an admin. + +## `/api/pleroma/admin/users` + +### List users + +- Method `GET` +- Query Params: + - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain) + - *optional* `filters`: **string** comma-separated string of filters: + - `local`: only local users + - `external`: only external users + - `active`: only active users + - `deactivated`: only deactivated users + - `is_admin`: users with admin role + - `is_moderator`: users with moderator role + - *optional* `page`: **integer** page number + - *optional* `page_size`: **integer** number of users per page (default is `50`) + - *optional* `tags`: **[string]** tags list + - *optional* `name`: **string** user display name + - *optional* `email`: **string** user email +- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com` +- Response: + +```json +{ + "page_size": integer, + "count": integer, + "users": [ + { + "deactivated": bool, + "id": integer, + "nickname": string, + "roles": { + "admin": bool, + "moderator": bool + }, + "local": bool, + "tags": array, + "avatar": string, + "display_name": string + }, + ... + ] +} +``` + +## `/api/pleroma/admin/users` + +### Remove a user + +- Method `DELETE` +- Params: + - `nickname` +- Response: User’s nickname + +### Create a user + +- Method: `POST` +- Params: + `users`: [ + { + `nickname`, + `email`, + `password` + } + ] +- Response: User’s nickname + +## `/api/pleroma/admin/users/follow` +### Make a user follow another user + +- Methods: `POST` +- Params: + - `follower`: The nickname of the follower + - `followed`: The nickname of the followed +- Response: + - "ok" + +## `/api/pleroma/admin/users/unfollow` +### Make a user unfollow another user + +- Methods: `POST` +- Params: + - `follower`: The nickname of the follower + - `followed`: The nickname of the followed +- Response: + - "ok" + +## `/api/pleroma/admin/users/:nickname/toggle_activation` + +### Toggle user activation + +- Method: `PATCH` +- Params: + - `nickname` +- Response: User’s object + +```json +{ + "deactivated": bool, + "id": integer, + "nickname": string +} +``` + +## `/api/pleroma/admin/users/tag` + +### Tag a list of users + +- Method: `PUT` +- Params: + - `nicknames` (array) + - `tags` (array) + +### Untag a list of users + +- Method: `DELETE` +- Params: + - `nicknames` (array) + - `tags` (array) + +## `/api/pleroma/admin/users/:nickname/permission_group` + +### Get user user permission groups membership + +- Method: `GET` +- Params: none +- Response: + +```json +{ + "is_moderator": bool, + "is_admin": bool +} +``` + +## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group` + +Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist. + +### Get user user permission groups membership per permission group + +- Method: `GET` +- Params: none +- Response: + +```json +{ + "is_moderator": bool, + "is_admin": bool +} +``` + +### Add user in permission group + +- Method: `POST` +- Params: none +- Response: + - On failure: `{"error": "…"}` + - On success: JSON of the `user.info` + +### Remove user from permission group + +- Method: `DELETE` +- Params: none +- Response: + - On failure: `{"error": "…"}` + - On success: JSON of the `user.info` +- Note: An admin cannot revoke their own admin status. + +## `/api/pleroma/admin/users/:nickname/activation_status` + +### Active or deactivate a user + +- Method: `PUT` +- Params: + - `nickname` + - `status` BOOLEAN field, false value means deactivation. + +## `/api/pleroma/admin/users/:nickname_or_id` + +### Retrive the details of a user + +- Method: `GET` +- Params: + - `nickname` or `id` +- Response: + - On failure: `Not found` + - On success: JSON of the user + +## `/api/pleroma/admin/users/:nickname_or_id/statuses` + +### Retrive user's latest statuses + +- Method: `GET` +- Params: + - `nickname` or `id` + - *optional* `page_size`: number of statuses to return (default is `20`) + - *optional* `godmode`: `true`/`false` – allows to see private statuses +- Response: + - On failure: `Not found` + - On success: JSON array of user's latest statuses + +## `/api/pleroma/admin/relay` + +### Follow a Relay + +- Methods: `POST` +- Params: + - `relay_url` +- Response: + - On success: URL of the followed relay + +### Unfollow a Relay + +- Methods: `DELETE` +- Params: + - `relay_url` +- Response: + - On success: URL of the unfollowed relay + +## `/api/pleroma/admin/users/invite_token` + +### Create an account registration invite token + +- Methods: `POST` +- Params: + - *optional* `max_use` (integer) + - *optional* `expires_at` (date string e.g. "2019-04-07") +- Response: + +```json +{ + "id": integer, + "token": string, + "used": boolean, + "expires_at": date, + "uses": integer, + "max_use": integer, + "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) +} +``` + +## `/api/pleroma/admin/users/invites` + +### Get a list of generated invites + +- Methods: `GET` +- Params: none +- Response: + +```json +{ + + "invites": [ + { + "id": integer, + "token": string, + "used": boolean, + "expires_at": date, + "uses": integer, + "max_use": integer, + "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) + }, + ... + ] +} +``` + +## `/api/pleroma/admin/users/revoke_invite` + +### Revoke invite by token + +- Methods: `POST` +- Params: + - `token` +- Response: + +```json +{ + "id": integer, + "token": string, + "used": boolean, + "expires_at": date, + "uses": integer, + "max_use": integer, + "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) + +} +``` + + +## `/api/pleroma/admin/users/email_invite` + +### Sends registration invite via email + +- Methods: `POST` +- Params: + - `email` + - `name`, optional + +## `/api/pleroma/admin/users/:nickname/password_reset` + +### Get a password reset token for a given nickname + +- Methods: `GET` +- Params: none +- Response: + +```json +{ + "token": "base64 reset token", + "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token" +} +``` + + +## `/api/pleroma/admin/users/:nickname/force_password_reset` + +### Force passord reset for a user with a given nickname + +- Methods: `PATCH` +- Params: none +- Response: none (code `204`) + +## `/api/pleroma/admin/reports` +### Get a list of reports +- Method `GET` +- Params: + - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved` + - *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`) +- 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: + - `account`: the user who has been reported + - `actor`: the user who has sent the report + - `statuses`: list of statuses that have been included to the report + +```json +{ + "total" : 1, + "reports": [ + { + "account": { + "acct": "user", + "avatar": "https://pleroma.example.org/images/avi.png", + "avatar_static": "https://pleroma.example.org/images/avi.png", + "bot": false, + "created_at": "2019-04-23T17:32:04.000Z", + "display_name": "User", + "emojis": [], + "fields": [], + "followers_count": 1, + "following_count": 1, + "header": "https://pleroma.example.org/images/banner.png", + "header_static": "https://pleroma.example.org/images/banner.png", + "id": "9i6dAJqSGSKMzLG2Lo", + "locked": false, + "note": "", + "pleroma": { + "confirmation_pending": false, + "hide_favorites": true, + "hide_followers": false, + "hide_follows": false, + "is_admin": false, + "is_moderator": false, + "relationship": {}, + "tags": [] + }, + "source": { + "note": "", + "pleroma": {}, + "sensitive": false + }, + "tags": ["force_unlisted"], + "statuses_count": 3, + "url": "https://pleroma.example.org/users/user", + "username": "user" + }, + "actor": { + "acct": "lain", + "avatar": "https://pleroma.example.org/images/avi.png", + "avatar_static": "https://pleroma.example.org/images/avi.png", + "bot": false, + "created_at": "2019-03-28T17:36:03.000Z", + "display_name": "Roger Braun", + "emojis": [], + "fields": [], + "followers_count": 1, + "following_count": 1, + "header": "https://pleroma.example.org/images/banner.png", + "header_static": "https://pleroma.example.org/images/banner.png", + "id": "9hEkA5JsvAdlSrocam", + "locked": false, + "note": "", + "pleroma": { + "confirmation_pending": false, + "hide_favorites": false, + "hide_followers": false, + "hide_follows": false, + "is_admin": false, + "is_moderator": false, + "relationship": {}, + "tags": [] + }, + "source": { + "note": "", + "pleroma": {}, + "sensitive": false + }, + "tags": ["force_unlisted"], + "statuses_count": 1, + "url": "https://pleroma.example.org/users/lain", + "username": "lain" + }, + "content": "Please delete it", + "created_at": "2019-04-29T19:48:15.000Z", + "id": "9iJGOv1j8hxuw19bcm", + "state": "open", + "statuses": [ + { + "account": { ... }, + "application": { + "name": "Web", + "website": null + }, + "bookmarked": false, + "card": null, + "content": "@lain click on my link https://www.google.com/", + "created_at": "2019-04-23T19:15:47.000Z", + "emojis": [], + "favourited": false, + "favourites_count": 0, + "id": "9i6mQ9uVrrOmOime8m", + "in_reply_to_account_id": null, + "in_reply_to_id": null, + "language": null, + "media_attachments": [], + "mentions": [ + { + "acct": "lain", + "id": "9hEkA5JsvAdlSrocam", + "url": "https://pleroma.example.org/users/lain", + "username": "lain" + }, + { + "acct": "user", + "id": "9i6dAJqSGSKMzLG2Lo", + "url": "https://pleroma.example.org/users/user", + "username": "user" + } + ], + "muted": false, + "pinned": false, + "pleroma": { + "content": { + "text/plain": "@lain click on my link https://www.google.com/" + }, + "conversation_id": 28, + "in_reply_to_account_acct": null, + "local": true, + "spoiler_text": { + "text/plain": "" + } + }, + "reblog": null, + "reblogged": false, + "reblogs_count": 0, + "replies_count": 0, + "sensitive": false, + "spoiler_text": "", + "tags": [], + "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396", + "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m", + "visibility": "direct" + } + ] + } + ] +} +``` + +## `/api/pleroma/admin/reports/:id` +### Get an individual report +- Method `GET` +- Params: + - `id` +- Response: + - On failure: + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, Report object (see above) + +## `/api/pleroma/admin/reports/:id` +### Change the state of the report +- Method `PUT` +- Params: + - `id` + - `state`: required, the new state. Valid values are `open`, `closed` and `resolved` +- Response: + - On failure: + - 400 Bad Request `"Unsupported state"` + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, Report object (see above) + +## `/api/pleroma/admin/reports/:id/respond` +### Respond to a report +- Method `POST` +- Params: + - `id` + - `status`: required, the message +- Response: + - On failure: + - 400 Bad Request `"Invalid parameters"` when `status` is missing + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, created Mastodon Status entity + +```json +{ + "account": { ... }, + "application": { + "name": "Web", + "website": null + }, + "bookmarked": false, + "card": null, + "content": "Your claim is going to be closed", + "created_at": "2019-05-11T17:13:03.000Z", + "emojis": [], + "favourited": false, + "favourites_count": 0, + "id": "9ihuiSL1405I65TmEq", + "in_reply_to_account_id": null, + "in_reply_to_id": null, + "language": null, + "media_attachments": [], + "mentions": [ + { + "acct": "user", + "id": "9i6dAJqSGSKMzLG2Lo", + "url": "https://pleroma.example.org/users/user", + "username": "user" + }, + { + "acct": "admin", + "id": "9hEkA5JsvAdlSrocam", + "url": "https://pleroma.example.org/users/admin", + "username": "admin" + } + ], + "muted": false, + "pinned": false, + "pleroma": { + "content": { + "text/plain": "Your claim is going to be closed" + }, + "conversation_id": 35, + "in_reply_to_account_acct": null, + "local": true, + "spoiler_text": { + "text/plain": "" + } + }, + "reblog": null, + "reblogged": false, + "reblogs_count": 0, + "replies_count": 0, + "sensitive": false, + "spoiler_text": "", + "tags": [], + "uri": "https://pleroma.example.org/objects/cab0836d-9814-46cd-a0ea-529da9db5fcb", + "url": "https://pleroma.example.org/notice/9ihuiSL1405I65TmEq", + "visibility": "direct" +} +``` + +## `/api/pleroma/admin/statuses/:id` +### Change the scope of an individual reported status +- Method `PUT` +- Params: + - `id` + - `sensitive`: optional, valid values are `true` or `false` + - `visibility`: optional, valid values are `public`, `private` and `unlisted` +- Response: + - On failure: + - 400 Bad Request `"Unsupported visibility"` + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, Mastodon Status entity + +## `/api/pleroma/admin/statuses/:id` +### Delete an individual reported status +- Method `DELETE` +- Params: + - `id` +- Response: + - On failure: + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: 200 OK `{}` + + +## `/api/pleroma/admin/config/migrate_to_db` +### Run mix task pleroma.config migrate_to_db +Copy settings on key `:pleroma` to DB. +- Method `GET` +- Params: none +- Response: + +```json +{} +``` + +## `/api/pleroma/admin/config/migrate_from_db` +### Run mix task pleroma.config migrate_from_db +Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB. +- Method `GET` +- Params: none +- Response: + +```json +{} +``` + +## `/api/pleroma/admin/config` +### List config settings +List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. +- Method `GET` +- Params: none +- Response: + +```json +{ + configs: [ + { + "group": string, + "key": string or string with leading `:` for atoms, + "value": string or {} or [] or {"tuple": []} + } + ] +} +``` + +## `/api/pleroma/admin/config` +### Update config settings +Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. +Module name can be passed as string, which starts with `Pleroma`, e.g. `"Pleroma.Upload"`. +Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`. +Tuples can be passed as `{"tuple": ["first_val", Pleroma.Module, []]}`. +`{"tuple": ["some_string", "Pleroma.Some.Module", []]}` will be converted to `{"some_string", Pleroma.Some.Module, []}`. +Keywords can be passed as lists with 2 child tuples, e.g. +`[{"tuple": ["first_val", Pleroma.Module]}, {"tuple": ["second_val", true]}]`. + +If value contains list of settings `[subkey: val1, subkey2: val2, subkey3: val3]`, it's possible to remove only subkeys instead of all settings passing `subkeys` parameter. E.g.: +{"group": "pleroma", "key": "some_key", "delete": "true", "subkeys": [":subkey", ":subkey3"]}. + +Compile time settings (need instance reboot): +- all settings by this keys: + - `:hackney_pools` + - `:chat` + - `Pleroma.Web.Endpoint` + - `Pleroma.Repo` +- part settings: + - `Pleroma.Captcha` -> `:seconds_valid` + - `Pleroma.Upload` -> `:proxy_remote` + - `:instance` -> `:upload_limit` + +- Method `POST` +- Params: + - `configs` => [ + - `group` (string) + - `key` (string or string with leading `:` for atoms) + - `value` (string, [], {} or {"tuple": []}) + - `delete` = true (optional, if parameter must be deleted) + - `subkeys` [(string with leading `:` for atoms)] (optional, works only if `delete=true` parameter is passed, otherwise will be ignored) + ] + +- Request (example): + +```json +{ + configs: [ + { + "group": "pleroma", + "key": "Pleroma.Upload", + "value": [ + {"tuple": [":uploader", "Pleroma.Uploaders.Local"]}, + {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]}, + {"tuple": [":link_name", true]}, + {"tuple": [":proxy_remote", false]}, + {"tuple": [":proxy_opts", [ + {"tuple": [":redirect_on_failure", false]}, + {"tuple": [":max_body_length", 1048576]}, + {"tuple": [":http": [ + {"tuple": [":follow_redirect", true]}, + {"tuple": [":pool", ":upload"]}, + ]]} + ] + ]}, + {"tuple": [":dispatch", { + "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []] + }]} + ] + } + ] +} +``` + +- Response: + +```json +{ + configs: [ + { + "group": string, + "key": string or string with leading `:` for atoms, + "value": string or {} or [] or {"tuple": []} + } + ] +} +``` + +## `/api/pleroma/admin/moderation_log` +### Get moderation log +- Method `GET` +- Params: + - *optional* `page`: **integer** page number + - *optional* `page_size`: **integer** number of log entries per page (default is `50`) + - *optional* `start_date`: **datetime (ISO 8601)** filter logs by creation date, start from `start_date`. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. `2005-08-09T18:31:42` + - *optional* `end_date`: **datetime (ISO 8601)** filter logs by creation date, end by from `end_date`. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. 2005-08-09T18:31:42 + - *optional* `user_id`: **integer** filter logs by actor's id + - *optional* `search`: **string** search logs by the log message +- Response: + +```json +[ + { + "data": { + "actor": { + "id": 1, + "nickname": "lain" + }, + "action": "relay_follow" + }, + "time": 1502812026, // timestamp + "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message + } +] +``` + +## `POST /api/pleroma/admin/reload_emoji` +### Reload the instance's custom emoji +* Method `POST` +* Authentication: required +* Params: None +* Response: JSON, "ok" and 200 status diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md new file mode 100644 index 000000000..d007a69c3 --- /dev/null +++ b/docs/API/differences_in_mastoapi_responses.md @@ -0,0 +1,149 @@ +# Differences in Mastodon API responses from vanilla Mastodon + +A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` + +## Flake IDs + +Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mastodon's ids they are sortable strings + +## Attachment cap + +Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Pleroma however does not enforce any limits on attachment count neither when returning the status object nor when posting. + +## Timelines + +Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users. + +## Statuses + +- `visibility`: has an additional possible value `list` + +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 AP context the status is associated with (if any) +- `direct_conversation_id`: the ID of the Mastodon direct message 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` +- `expires_at`: a datetime (iso8601) that states when the post will expire (be deleted automatically), or empty if the post won't expire +- `thread_muted`: true if the thread the post belongs to is muted + +## Attachments + +Has these additional fields under the `pleroma` object: + +- `mime_type`: mime type of the attachment. + +## Accounts + +The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc. + +- `/api/v1/accounts/:id` +- `/api/v1/accounts/:id/statuses` + +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, 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 +- `hide_followers_count`: boolean, true when the user has follower stat hiding enabled +- `hide_follows_count`: boolean, true when the user has follow stat hiding enabled +- `settings_store`: A generic map of settings for frontends. Opaque to the backend. Only returned in `verify_credentials` and `update_credentials` +- `chat_token`: The token needed for Pleroma chat. Only returned in `verify_credentials` +- `deactivated`: boolean, true when the user is deactivated + +### 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 + +## Conversations + +Has an additional field under the `pleroma` object: + +- `recipients`: The list of the recipients of this Conversation. These will be addressed when replying to this conversation. + +## Account Search + +Behavior has changed: + +- `/api/v1/accounts/search`: Does not require authentication + + +## Notifications + +Has these additional fields under the `pleroma` object: + +- `is_seen`: true if the notification was read by the user + +## POST `/api/v1/statuses` + +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. +- `to`: A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply. +- `visibility`: string, besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`. +- `expires_in`: The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour. +- `in_reply_to_conversation_id`: Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`. + +## GET `/api/v1/statuses` + +An endpoint to get multiple statuses by IDs. + +Required parameters: + +- `ids`: array of activity ids + +Usage example: `GET /api/v1/statuses/?ids[]=1&ids[]=2`. + +Returns: array of Status. + +The maximum number of statuses is limited to 100 per request. + +## 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_followers_count` - if true, user's follower count will be hidden +- `hide_follows_count` - if true, user's follow count 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 +- `pleroma_settings_store` - Opaque user settings to be saved on the backend. +- `skip_thread_containment` - if true, skip filtering out broken threads +- `pleroma_background_image` - sets the background image of the user. + +### Pleroma Settings Store +Pleroma has mechanism that allows frontends to save blobs of json for each user on the backend. This can be used to save frontend-specific settings for a user that the backend does not need to know about. + +The parameter should have a form of `{frontend_name: {...}}`, with `frontend_name` identifying your type of client, e.g. `pleroma_fe`. It will overwrite everything under this property, but will not overwrite other frontend's settings. + +This information is returned in the `verify_credentials` endpoint. + +## Authentication + +*Pleroma supports refreshing tokens. + +`POST /oauth/token` +Post here request with grant_type=refresh_token to obtain new access token. Returns an access token. + +## Account Registration +`POST /api/v1/accounts` + +Has theses additionnal parameters (which are the same as in Pleroma-API): + * `fullname`: optional + * `bio`: optional + * `captcha_solution`: optional, contains provider-specific captcha solution, + * `captcha_token`: optional, contains provider-specific captcha token + * `token`: invite token required when the registerations aren't public. diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md new file mode 100644 index 000000000..41889a0ef --- /dev/null +++ b/docs/API/pleroma_api.md @@ -0,0 +1,473 @@ +# Pleroma API + +Requests that require it can be authenticated with [an OAuth token](https://tools.ietf.org/html/rfc6749), the `_pleroma_key` cookie, or [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization). + +Request parameters can be passed via [query strings](https://en.wikipedia.org/wiki/Query_string) or as [form data](https://www.w3.org/TR/html401/interact/forms.html). Files must be uploaded as `multipart/form-data`. + +## `/api/pleroma/emoji` +### Lists the custom emoji on that server. +* Method: `GET` +* Authentication: not required +* Params: none +* Response: JSON +* Example response: +```json +{ + "girlpower": { + "tags": [ + "Finmoji" + ], + "image_url": "/finmoji/128px/girlpower-128.png" + }, + "education": { + "tags": [ + "Finmoji" + ], + "image_url": "/finmoji/128px/education-128.png" + }, + "finnishlove": { + "tags": [ + "Finmoji" + ], + "image_url": "/finmoji/128px/finnishlove-128.png" + } +} +``` +* Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format + +## `/api/pleroma/follow_import` +### Imports your follows, for example from a Mastodon CSV file. +* Method: `POST` +* Authentication: required +* Params: + * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow +* Response: HTTP 200 on success, 500 on error +* Note: Users that can't be followed are silently skipped. + +## `/api/pleroma/captcha` +### Get a new captcha +* Method: `GET` +* Authentication: not required +* Params: none +* Response: Provider specific JSON, the only guaranteed parameter is `type` +* Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}` + +## `/api/pleroma/delete_account` +### Delete an account +* Method `POST` +* Authentication: required +* Params: + * `password`: user's password +* Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise +* Example response: `{"error": "Invalid password."}` + +## `/api/pleroma/disable_account` +### Disable an account +* Method `POST` +* Authentication: required +* Params: + * `password`: user's password +* Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise +* Example response: `{"error": "Invalid password."}` + +## `/api/account/register` +### Register a new user +* Method `POST` +* Authentication: not required +* Params: + * `nickname` + * `fullname` + * `bio` + * `email` + * `password` + * `confirm` + * `captcha_solution`: optional, contains provider-specific captcha solution, + * `captcha_token`: optional, contains provider-specific captcha token + * `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", + "created_at": "Tue Dec 18 16:55:56 +0000 2018", + "default_scope": "public", + "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.", + "description_html": "blushy-crushy fediverse idol + pleroma dev.
let's be friends
ぷれろまの生徒会長。謎の外人。日本語OK.
公主病.", + "favourites_count": 0, + "fields": [], + "followers_count": 0, + "following": false, + "follows_you": false, + "friends_count": 0, + "id": 6, + "is_local": true, + "locked": false, + "name": "lain", + "name_html": "lain", + "no_rich_text": false, + "pleroma": { + "tags": [] + }, + "profile_image_url": "https://pleroma.soykaf.com/images/avi.png", + "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png", + "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png", + "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png", + "rights": { + "delete_others_notice": false + }, + "screen_name": "lain", + "statuses_count": 0, + "statusnet_blocking": false, + "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain" +} +``` + +## `/api/pleroma/admin/`… +See [Admin-API](Admin-API.md) + +## `/api/v1/pleroma/notifications/read` +### Mark notifications as read +* Method `POST` +* Authentication: required +* Params (mutually exclusive): + * `id`: a single notification id to read + * `max_id`: read all notifications up to this id +* Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned. + +## `/api/v1/pleroma/accounts/:id/subscribe` +### Subscribe to receive notifications for all statuses posted by a user +* Method `POST` +* Authentication: required +* Params: + * `id`: account id to subscribe to +* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}` +* Example response: +```json +{ + "id": "abcdefg", + "following": true, + "followed_by": false, + "blocking": false, + "muting": false, + "muting_notifications": false, + "subscribing": true, + "requested": false, + "domain_blocking": false, + "showing_reblogs": true, + "endorsed": false +} +``` + +## `/api/v1/pleroma/accounts/:id/unsubscribe` +### Unsubscribe to stop receiving notifications from user statuses +* Method `POST` +* Authentication: required +* Params: + * `id`: account id to unsubscribe from +* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}` +* Example response: +```json +{ + "id": "abcdefg", + "following": true, + "followed_by": false, + "blocking": false, + "muting": false, + "muting_notifications": false, + "subscribing": false, + "requested": false, + "domain_blocking": false, + "showing_reblogs": true, + "endorsed": false +} +``` + +## `/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/v1/pleroma/accounts/update_*` +### Set and clear account avatar, banner, and background + +- PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image +- PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image +- PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image + +## `/api/v1/pleroma/accounts/confirmation_resend` +### Resend confirmation email +* Method `POST` +* Params: + * `email`: email of that needs to be verified +* Authentication: not required +* Response: 204 No Content + +## `/api/v1/pleroma/mascot` +### Gets user mascot image +* Method `GET` +* Authentication: required + +* Response: JSON. Returns a mastodon media attachment entity. +* Example response: +```json +{ + "id": "abcdefg", + "url": "https://pleroma.example.org/media/abcdefg.png", + "type": "image", + "pleroma": { + "mime_type": "image/png" + } +} +``` + +### Updates user mascot image +* Method `PUT` +* Authentication: required +* Params: + * `image`: Multipart image +* Response: JSON. Returns a mastodon media attachment entity + when successful, otherwise returns HTTP 415 `{"error": "error_msg"}` +* Example response: +```json +{ + "id": "abcdefg", + "url": "https://pleroma.example.org/media/abcdefg.png", + "type": "image", + "pleroma": { + "mime_type": "image/png" + } +} +``` +* Note: Behaves exactly the same as `POST /api/v1/upload`. + Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`. + +## `/api/pleroma/notification_settings` +### Updates user notification settings +* Method `PUT` +* Authentication: required +* Params: + * `followers`: BOOLEAN field, receives notifications from followers + * `follows`: BOOLEAN field, receives notifications from people the user follows + * `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 +} +``` + +## `/api/pleroma/change_email` +### Change account email +* Method `POST` +* Authentication: required +* Params: + * `password`: user's password + * `email`: new email +* Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise +* Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma. + +# Pleroma Conversations + +Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints: + +1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user. +2. Pleroma Conversations statuses can be requested by Conversation id. +3. Pleroma Conversations can be replied to. + +Conversations have the additional field "recipients" under the "pleroma" key. This holds a list of all the accounts that will receive a message in this conversation. + +The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation. + + +## `GET /api/v1/pleroma/conversations/:id/statuses` +### Timeline for a given conversation +* Method `GET` +* Authentication: required +* Params: Like other timelines +* Response: JSON, statuses (200 - healthy, 503 unhealthy). + +## `GET /api/v1/pleroma/conversations/:id` +### The conversation with the given ID. +* Method `GET` +* Authentication: required +* Params: None +* Response: JSON, statuses (200 - healthy, 503 unhealthy). + +## `PATCH /api/v1/pleroma/conversations/:id` +### Update a conversation. Used to change the set of recipients. +* Method `PATCH` +* Authentication: required +* Params: + * `recipients`: A list of ids of users that should receive posts to this conversation. This will replace the current list of recipients, so submit the full list. The owner of owner of the conversation will always be part of the set of recipients, though. +* Response: JSON, statuses (200 - healthy, 503 unhealthy) + +## `GET /api/pleroma/emoji/packs` +### Lists the custom emoji packs on the server +* Method `GET` +* Authentication: not required +* Params: None +* Response: JSON, "ok" and 200 status and the JSON hashmap of "pack name" to "pack contents" + +## `PUT /api/pleroma/emoji/packs/:name` +### Creates an empty custom emoji pack +* Method `PUT` +* Authentication: required +* Params: None +* Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists + +## `DELETE /api/pleroma/emoji/packs/:name` +### Delete a custom emoji pack +* Method `DELETE` +* Authentication: required +* Params: None +* Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack + +## `POST /api/pleroma/emoji/packs/:name/update_file` +### Update a file in a custom emoji pack +* Method `POST` +* Authentication: required +* Params: + * if the `action` is `add`, adds an emoji named `shortcode` to the pack `pack_name`, + that means that the emoji file needs to be uploaded with the request + (thus requiring it to be a multipart request) and be named `file`. + There can also be an optional `filename` that will be the new emoji file name + (if it's not there, the name will be taken from the uploaded file). + * if the `action` is `update`, changes emoji shortcode + (from `shortcode` to `new_shortcode` or moves the file (from the current filename to `new_filename`) + * if the `action` is `remove`, removes the emoji named `shortcode` and it's associated file +* Response: JSON, updated "files" section of the pack and 200 status, 409 if the trying to use a shortcode + that is already taken, 400 if there was an error with the shortcode, filename or file (additional info + in the "error" part of the response JSON) + +## `POST /api/pleroma/emoji/packs/:name/update_metadata` +### Updates (replaces) pack metadata +* Method `POST` +* Authentication: required +* Params: + * `new_data`: new metadata to replace the old one +* Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a + problem with the new metadata (the error is specified in the "error" part of the response JSON) + +## `POST /api/pleroma/emoji/packs/download_from` +### Requests the instance to download the pack from another instance +* Method `POST` +* Authentication: required +* Params: + * `instance_address`: the address of the instance to download from + * `pack_name`: the pack to download from that instance +* Response: JSON, "ok" and 200 status if the pack was downloaded, or 500 if there were + errors downloading the pack + +## `POST /api/pleroma/emoji/packs/list_from` +### Requests the instance to list the packs from another instance +* Method `POST` +* Authentication: required +* Params: + * `instance_address`: the address of the instance to download from +* Response: JSON with the pack list, same as if the request was made to that instance's + list endpoint directly + 200 status + +## `GET /api/pleroma/emoji/packs/:name/download_shared` +### Requests a local pack from the instance +* Method `GET` +* Authentication: not required +* Params: None +* Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared, + 404 if the pack does not exist + +## `GET /api/v1/pleroma/accounts/:id/scrobbles` +### Requests a list of current and recent Listen activities for an account +* Method `GET` +* Authentication: not required +* Params: None +* Response: An array of media metadata entities. +* Example response: +```json +[ + { + "account": {...}, + "id": "1234", + "title": "Some Title", + "artist": "Some Artist", + "album": "Some Album", + "length": 180000, + "created_at": "2019-09-28T12:40:45.000Z" + } +] +``` + +## `POST /api/v1/pleroma/scrobble` +### Creates a new Listen activity for an account +* Method `POST` +* Authentication: required +* 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] +* Response: the newly created media metadata entity representing the Listen activity diff --git a/docs/API/prometheus.md b/docs/API/prometheus.md new file mode 100644 index 000000000..19c564e3c --- /dev/null +++ b/docs/API/prometheus.md @@ -0,0 +1,22 @@ +# Prometheus Metrics + +Pleroma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library. + +## `/api/pleroma/app_metrics` +### Exports Prometheus application metrics +* Method: `GET` +* Authentication: not required +* Params: none +* Response: JSON + +## Grafana +### Config example +The following is a config example to use with [Grafana](https://grafana.com) + +``` + - job_name: 'beam' + metrics_path: /api/pleroma/app_metrics + scheme: https + static_configs: + - targets: ['pleroma.soykaf.com'] +``` diff --git a/docs/admin/backup.md b/docs/admin/backup.md deleted file mode 100644 index 2c70e7bf8..000000000 --- a/docs/admin/backup.md +++ /dev/null @@ -1,17 +0,0 @@ -# Backup/Restore your instance - -## Backup - -1. Stop the Pleroma service. -2. Go to the working directory of Pleroma (default is `/opt/pleroma`) -3. Run `sudo -Hu postgres pg_dump -d --format=custom -f ` -4. Copy `pleroma.pgdump`, `config/prod.secret.exs` and the `uploads` folder to your backup destination. If you have other modifications, copy those changes too. -5. Restart the Pleroma service. - -## Restore - -1. Stop the Pleroma service. -2. Go to the working directory of Pleroma (default is `/opt/pleroma`) -3. Copy the above mentioned files back to their original position. -4. Run `sudo -Hu postgres pg_restore -d -v -1 ` -5. Restart the Pleroma service. diff --git a/docs/admin/updating.md b/docs/admin/updating.md deleted file mode 100644 index 84e6ef18d..000000000 --- a/docs/admin/updating.md +++ /dev/null @@ -1,9 +0,0 @@ -# Updating your instance -1. Go to the working directory of Pleroma (default is `/opt/pleroma`) -2. Run `git pull`. This pulls the latest changes from upstream. -3. Run `mix deps.get`. This pulls in any new dependencies. -4. Stop the Pleroma service. -5. Run `mix ecto.migrate`[^1]. This task performs database migrations, if there were any. -6. Start the Pleroma service. - -[^1]: Prefix with `MIX_ENV=prod` to run it using the production config file. diff --git a/docs/administration/backup.md b/docs/administration/backup.md new file mode 100644 index 000000000..2c70e7bf8 --- /dev/null +++ b/docs/administration/backup.md @@ -0,0 +1,17 @@ +# Backup/Restore your instance + +## Backup + +1. Stop the Pleroma service. +2. Go to the working directory of Pleroma (default is `/opt/pleroma`) +3. Run `sudo -Hu postgres pg_dump -d --format=custom -f ` +4. Copy `pleroma.pgdump`, `config/prod.secret.exs` and the `uploads` folder to your backup destination. If you have other modifications, copy those changes too. +5. Restart the Pleroma service. + +## Restore + +1. Stop the Pleroma service. +2. Go to the working directory of Pleroma (default is `/opt/pleroma`) +3. Copy the above mentioned files back to their original position. +4. Run `sudo -Hu postgres pg_restore -d -v -1 ` +5. Restart the Pleroma service. diff --git a/docs/administration/updating.md b/docs/administration/updating.md new file mode 100644 index 000000000..84e6ef18d --- /dev/null +++ b/docs/administration/updating.md @@ -0,0 +1,9 @@ +# Updating your instance +1. Go to the working directory of Pleroma (default is `/opt/pleroma`) +2. Run `git pull`. This pulls the latest changes from upstream. +3. Run `mix deps.get`. This pulls in any new dependencies. +4. Stop the Pleroma service. +5. Run `mix ecto.migrate`[^1]. This task performs database migrations, if there were any. +6. Start the Pleroma service. + +[^1]: Prefix with `MIX_ENV=prod` to run it using the production config file. diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md deleted file mode 100644 index ee9e68cb1..000000000 --- a/docs/api/admin_api.md +++ /dev/null @@ -1,763 +0,0 @@ -# Admin API - -Authentication is required and the user must be an admin. - -## `/api/pleroma/admin/users` - -### List users - -- Method `GET` -- Query Params: - - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain) - - *optional* `filters`: **string** comma-separated string of filters: - - `local`: only local users - - `external`: only external users - - `active`: only active users - - `deactivated`: only deactivated users - - `is_admin`: users with admin role - - `is_moderator`: users with moderator role - - *optional* `page`: **integer** page number - - *optional* `page_size`: **integer** number of users per page (default is `50`) - - *optional* `tags`: **[string]** tags list - - *optional* `name`: **string** user display name - - *optional* `email`: **string** user email -- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com` -- Response: - -```json -{ - "page_size": integer, - "count": integer, - "users": [ - { - "deactivated": bool, - "id": integer, - "nickname": string, - "roles": { - "admin": bool, - "moderator": bool - }, - "local": bool, - "tags": array, - "avatar": string, - "display_name": string - }, - ... - ] -} -``` - -## `/api/pleroma/admin/users` - -### Remove a user - -- Method `DELETE` -- Params: - - `nickname` -- Response: User’s nickname - -### Create a user - -- Method: `POST` -- Params: - `users`: [ - { - `nickname`, - `email`, - `password` - } - ] -- Response: User’s nickname - -## `/api/pleroma/admin/users/follow` -### Make a user follow another user - -- Methods: `POST` -- Params: - - `follower`: The nickname of the follower - - `followed`: The nickname of the followed -- Response: - - "ok" - -## `/api/pleroma/admin/users/unfollow` -### Make a user unfollow another user - -- Methods: `POST` -- Params: - - `follower`: The nickname of the follower - - `followed`: The nickname of the followed -- Response: - - "ok" - -## `/api/pleroma/admin/users/:nickname/toggle_activation` - -### Toggle user activation - -- Method: `PATCH` -- Params: - - `nickname` -- Response: User’s object - -```json -{ - "deactivated": bool, - "id": integer, - "nickname": string -} -``` - -## `/api/pleroma/admin/users/tag` - -### Tag a list of users - -- Method: `PUT` -- Params: - - `nicknames` (array) - - `tags` (array) - -### Untag a list of users - -- Method: `DELETE` -- Params: - - `nicknames` (array) - - `tags` (array) - -## `/api/pleroma/admin/users/:nickname/permission_group` - -### Get user user permission groups membership - -- Method: `GET` -- Params: none -- Response: - -```json -{ - "is_moderator": bool, - "is_admin": bool -} -``` - -## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group` - -Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist. - -### Get user user permission groups membership per permission group - -- Method: `GET` -- Params: none -- Response: - -```json -{ - "is_moderator": bool, - "is_admin": bool -} -``` - -### Add user in permission group - -- Method: `POST` -- Params: none -- Response: - - On failure: `{"error": "…"}` - - On success: JSON of the `user.info` - -### Remove user from permission group - -- Method: `DELETE` -- Params: none -- Response: - - On failure: `{"error": "…"}` - - On success: JSON of the `user.info` -- Note: An admin cannot revoke their own admin status. - -## `/api/pleroma/admin/users/:nickname/activation_status` - -### Active or deactivate a user - -- Method: `PUT` -- Params: - - `nickname` - - `status` BOOLEAN field, false value means deactivation. - -## `/api/pleroma/admin/users/:nickname_or_id` - -### Retrive the details of a user - -- Method: `GET` -- Params: - - `nickname` or `id` -- Response: - - On failure: `Not found` - - On success: JSON of the user - -## `/api/pleroma/admin/users/:nickname_or_id/statuses` - -### Retrive user's latest statuses - -- Method: `GET` -- Params: - - `nickname` or `id` - - *optional* `page_size`: number of statuses to return (default is `20`) - - *optional* `godmode`: `true`/`false` – allows to see private statuses -- Response: - - On failure: `Not found` - - On success: JSON array of user's latest statuses - -## `/api/pleroma/admin/relay` - -### Follow a Relay - -- Methods: `POST` -- Params: - - `relay_url` -- Response: - - On success: URL of the followed relay - -### Unfollow a Relay - -- Methods: `DELETE` -- Params: - - `relay_url` -- Response: - - On success: URL of the unfollowed relay - -## `/api/pleroma/admin/users/invite_token` - -### Create an account registration invite token - -- Methods: `POST` -- Params: - - *optional* `max_use` (integer) - - *optional* `expires_at` (date string e.g. "2019-04-07") -- Response: - -```json -{ - "id": integer, - "token": string, - "used": boolean, - "expires_at": date, - "uses": integer, - "max_use": integer, - "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) -} -``` - -## `/api/pleroma/admin/users/invites` - -### Get a list of generated invites - -- Methods: `GET` -- Params: none -- Response: - -```json -{ - - "invites": [ - { - "id": integer, - "token": string, - "used": boolean, - "expires_at": date, - "uses": integer, - "max_use": integer, - "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) - }, - ... - ] -} -``` - -## `/api/pleroma/admin/users/revoke_invite` - -### Revoke invite by token - -- Methods: `POST` -- Params: - - `token` -- Response: - -```json -{ - "id": integer, - "token": string, - "used": boolean, - "expires_at": date, - "uses": integer, - "max_use": integer, - "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) - -} -``` - - -## `/api/pleroma/admin/users/email_invite` - -### Sends registration invite via email - -- Methods: `POST` -- Params: - - `email` - - `name`, optional - -## `/api/pleroma/admin/users/:nickname/password_reset` - -### Get a password reset token for a given nickname - -- Methods: `GET` -- Params: none -- Response: - -```json -{ - "token": "base64 reset token", - "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token" -} -``` - - -## `/api/pleroma/admin/users/:nickname/force_password_reset` - -### Force passord reset for a user with a given nickname - -- Methods: `PATCH` -- Params: none -- Response: none (code `204`) - -## `/api/pleroma/admin/reports` -### Get a list of reports -- Method `GET` -- Params: - - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved` - - *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`) -- 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: - - `account`: the user who has been reported - - `actor`: the user who has sent the report - - `statuses`: list of statuses that have been included to the report - -```json -{ - "total" : 1, - "reports": [ - { - "account": { - "acct": "user", - "avatar": "https://pleroma.example.org/images/avi.png", - "avatar_static": "https://pleroma.example.org/images/avi.png", - "bot": false, - "created_at": "2019-04-23T17:32:04.000Z", - "display_name": "User", - "emojis": [], - "fields": [], - "followers_count": 1, - "following_count": 1, - "header": "https://pleroma.example.org/images/banner.png", - "header_static": "https://pleroma.example.org/images/banner.png", - "id": "9i6dAJqSGSKMzLG2Lo", - "locked": false, - "note": "", - "pleroma": { - "confirmation_pending": false, - "hide_favorites": true, - "hide_followers": false, - "hide_follows": false, - "is_admin": false, - "is_moderator": false, - "relationship": {}, - "tags": [] - }, - "source": { - "note": "", - "pleroma": {}, - "sensitive": false - }, - "tags": ["force_unlisted"], - "statuses_count": 3, - "url": "https://pleroma.example.org/users/user", - "username": "user" - }, - "actor": { - "acct": "lain", - "avatar": "https://pleroma.example.org/images/avi.png", - "avatar_static": "https://pleroma.example.org/images/avi.png", - "bot": false, - "created_at": "2019-03-28T17:36:03.000Z", - "display_name": "Roger Braun", - "emojis": [], - "fields": [], - "followers_count": 1, - "following_count": 1, - "header": "https://pleroma.example.org/images/banner.png", - "header_static": "https://pleroma.example.org/images/banner.png", - "id": "9hEkA5JsvAdlSrocam", - "locked": false, - "note": "", - "pleroma": { - "confirmation_pending": false, - "hide_favorites": false, - "hide_followers": false, - "hide_follows": false, - "is_admin": false, - "is_moderator": false, - "relationship": {}, - "tags": [] - }, - "source": { - "note": "", - "pleroma": {}, - "sensitive": false - }, - "tags": ["force_unlisted"], - "statuses_count": 1, - "url": "https://pleroma.example.org/users/lain", - "username": "lain" - }, - "content": "Please delete it", - "created_at": "2019-04-29T19:48:15.000Z", - "id": "9iJGOv1j8hxuw19bcm", - "state": "open", - "statuses": [ - { - "account": { ... }, - "application": { - "name": "Web", - "website": null - }, - "bookmarked": false, - "card": null, - "content": "@lain click on my link https://www.google.com/", - "created_at": "2019-04-23T19:15:47.000Z", - "emojis": [], - "favourited": false, - "favourites_count": 0, - "id": "9i6mQ9uVrrOmOime8m", - "in_reply_to_account_id": null, - "in_reply_to_id": null, - "language": null, - "media_attachments": [], - "mentions": [ - { - "acct": "lain", - "id": "9hEkA5JsvAdlSrocam", - "url": "https://pleroma.example.org/users/lain", - "username": "lain" - }, - { - "acct": "user", - "id": "9i6dAJqSGSKMzLG2Lo", - "url": "https://pleroma.example.org/users/user", - "username": "user" - } - ], - "muted": false, - "pinned": false, - "pleroma": { - "content": { - "text/plain": "@lain click on my link https://www.google.com/" - }, - "conversation_id": 28, - "in_reply_to_account_acct": null, - "local": true, - "spoiler_text": { - "text/plain": "" - } - }, - "reblog": null, - "reblogged": false, - "reblogs_count": 0, - "replies_count": 0, - "sensitive": false, - "spoiler_text": "", - "tags": [], - "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396", - "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m", - "visibility": "direct" - } - ] - } - ] -} -``` - -## `/api/pleroma/admin/reports/:id` -### Get an individual report -- Method `GET` -- Params: - - `id` -- Response: - - On failure: - - 403 Forbidden `{"error": "error_msg"}` - - 404 Not Found `"Not found"` - - On success: JSON, Report object (see above) - -## `/api/pleroma/admin/reports/:id` -### Change the state of the report -- Method `PUT` -- Params: - - `id` - - `state`: required, the new state. Valid values are `open`, `closed` and `resolved` -- Response: - - On failure: - - 400 Bad Request `"Unsupported state"` - - 403 Forbidden `{"error": "error_msg"}` - - 404 Not Found `"Not found"` - - On success: JSON, Report object (see above) - -## `/api/pleroma/admin/reports/:id/respond` -### Respond to a report -- Method `POST` -- Params: - - `id` - - `status`: required, the message -- Response: - - On failure: - - 400 Bad Request `"Invalid parameters"` when `status` is missing - - 403 Forbidden `{"error": "error_msg"}` - - 404 Not Found `"Not found"` - - On success: JSON, created Mastodon Status entity - -```json -{ - "account": { ... }, - "application": { - "name": "Web", - "website": null - }, - "bookmarked": false, - "card": null, - "content": "Your claim is going to be closed", - "created_at": "2019-05-11T17:13:03.000Z", - "emojis": [], - "favourited": false, - "favourites_count": 0, - "id": "9ihuiSL1405I65TmEq", - "in_reply_to_account_id": null, - "in_reply_to_id": null, - "language": null, - "media_attachments": [], - "mentions": [ - { - "acct": "user", - "id": "9i6dAJqSGSKMzLG2Lo", - "url": "https://pleroma.example.org/users/user", - "username": "user" - }, - { - "acct": "admin", - "id": "9hEkA5JsvAdlSrocam", - "url": "https://pleroma.example.org/users/admin", - "username": "admin" - } - ], - "muted": false, - "pinned": false, - "pleroma": { - "content": { - "text/plain": "Your claim is going to be closed" - }, - "conversation_id": 35, - "in_reply_to_account_acct": null, - "local": true, - "spoiler_text": { - "text/plain": "" - } - }, - "reblog": null, - "reblogged": false, - "reblogs_count": 0, - "replies_count": 0, - "sensitive": false, - "spoiler_text": "", - "tags": [], - "uri": "https://pleroma.example.org/objects/cab0836d-9814-46cd-a0ea-529da9db5fcb", - "url": "https://pleroma.example.org/notice/9ihuiSL1405I65TmEq", - "visibility": "direct" -} -``` - -## `/api/pleroma/admin/statuses/:id` -### Change the scope of an individual reported status -- Method `PUT` -- Params: - - `id` - - `sensitive`: optional, valid values are `true` or `false` - - `visibility`: optional, valid values are `public`, `private` and `unlisted` -- Response: - - On failure: - - 400 Bad Request `"Unsupported visibility"` - - 403 Forbidden `{"error": "error_msg"}` - - 404 Not Found `"Not found"` - - On success: JSON, Mastodon Status entity - -## `/api/pleroma/admin/statuses/:id` -### Delete an individual reported status -- Method `DELETE` -- Params: - - `id` -- Response: - - On failure: - - 403 Forbidden `{"error": "error_msg"}` - - 404 Not Found `"Not found"` - - On success: 200 OK `{}` - - -## `/api/pleroma/admin/config/migrate_to_db` -### Run mix task pleroma.config migrate_to_db -Copy settings on key `:pleroma` to DB. -- Method `GET` -- Params: none -- Response: - -```json -{} -``` - -## `/api/pleroma/admin/config/migrate_from_db` -### Run mix task pleroma.config migrate_from_db -Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB. -- Method `GET` -- Params: none -- Response: - -```json -{} -``` - -## `/api/pleroma/admin/config` -### List config settings -List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. -- Method `GET` -- Params: none -- Response: - -```json -{ - configs: [ - { - "group": string, - "key": string or string with leading `:` for atoms, - "value": string or {} or [] or {"tuple": []} - } - ] -} -``` - -## `/api/pleroma/admin/config` -### Update config settings -Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. -Module name can be passed as string, which starts with `Pleroma`, e.g. `"Pleroma.Upload"`. -Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`. -Tuples can be passed as `{"tuple": ["first_val", Pleroma.Module, []]}`. -`{"tuple": ["some_string", "Pleroma.Some.Module", []]}` will be converted to `{"some_string", Pleroma.Some.Module, []}`. -Keywords can be passed as lists with 2 child tuples, e.g. -`[{"tuple": ["first_val", Pleroma.Module]}, {"tuple": ["second_val", true]}]`. - -If value contains list of settings `[subkey: val1, subkey2: val2, subkey3: val3]`, it's possible to remove only subkeys instead of all settings passing `subkeys` parameter. E.g.: -{"group": "pleroma", "key": "some_key", "delete": "true", "subkeys": [":subkey", ":subkey3"]}. - -Compile time settings (need instance reboot): -- all settings by this keys: - - `:hackney_pools` - - `:chat` - - `Pleroma.Web.Endpoint` - - `Pleroma.Repo` -- part settings: - - `Pleroma.Captcha` -> `:seconds_valid` - - `Pleroma.Upload` -> `:proxy_remote` - - `:instance` -> `:upload_limit` - -- Method `POST` -- Params: - - `configs` => [ - - `group` (string) - - `key` (string or string with leading `:` for atoms) - - `value` (string, [], {} or {"tuple": []}) - - `delete` = true (optional, if parameter must be deleted) - - `subkeys` [(string with leading `:` for atoms)] (optional, works only if `delete=true` parameter is passed, otherwise will be ignored) - ] - -- Request (example): - -```json -{ - configs: [ - { - "group": "pleroma", - "key": "Pleroma.Upload", - "value": [ - {"tuple": [":uploader", "Pleroma.Uploaders.Local"]}, - {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]}, - {"tuple": [":link_name", true]}, - {"tuple": [":proxy_remote", false]}, - {"tuple": [":proxy_opts", [ - {"tuple": [":redirect_on_failure", false]}, - {"tuple": [":max_body_length", 1048576]}, - {"tuple": [":http": [ - {"tuple": [":follow_redirect", true]}, - {"tuple": [":pool", ":upload"]}, - ]]} - ] - ]}, - {"tuple": [":dispatch", { - "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []] - }]} - ] - } - ] -} -``` - -- Response: - -```json -{ - configs: [ - { - "group": string, - "key": string or string with leading `:` for atoms, - "value": string or {} or [] or {"tuple": []} - } - ] -} -``` - -## `/api/pleroma/admin/moderation_log` -### Get moderation log -- Method `GET` -- Params: - - *optional* `page`: **integer** page number - - *optional* `page_size`: **integer** number of log entries per page (default is `50`) - - *optional* `start_date`: **datetime (ISO 8601)** filter logs by creation date, start from `start_date`. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. `2005-08-09T18:31:42` - - *optional* `end_date`: **datetime (ISO 8601)** filter logs by creation date, end by from `end_date`. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. 2005-08-09T18:31:42 - - *optional* `user_id`: **integer** filter logs by actor's id - - *optional* `search`: **string** search logs by the log message -- Response: - -```json -[ - { - "data": { - "actor": { - "id": 1, - "nickname": "lain" - }, - "action": "relay_follow" - }, - "time": 1502812026, // timestamp - "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message - } -] -``` - -## `POST /api/pleroma/admin/reload_emoji` -### Reload the instance's custom emoji -* Method `POST` -* Authentication: required -* Params: None -* Response: JSON, "ok" and 200 status diff --git a/docs/api/differences_in_mastoapi_responses.md b/docs/api/differences_in_mastoapi_responses.md deleted file mode 100644 index d007a69c3..000000000 --- a/docs/api/differences_in_mastoapi_responses.md +++ /dev/null @@ -1,149 +0,0 @@ -# Differences in Mastodon API responses from vanilla Mastodon - -A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` - -## Flake IDs - -Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mastodon's ids they are sortable strings - -## Attachment cap - -Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Pleroma however does not enforce any limits on attachment count neither when returning the status object nor when posting. - -## Timelines - -Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users. - -## Statuses - -- `visibility`: has an additional possible value `list` - -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 AP context the status is associated with (if any) -- `direct_conversation_id`: the ID of the Mastodon direct message 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` -- `expires_at`: a datetime (iso8601) that states when the post will expire (be deleted automatically), or empty if the post won't expire -- `thread_muted`: true if the thread the post belongs to is muted - -## Attachments - -Has these additional fields under the `pleroma` object: - -- `mime_type`: mime type of the attachment. - -## Accounts - -The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc. - -- `/api/v1/accounts/:id` -- `/api/v1/accounts/:id/statuses` - -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, 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 -- `hide_followers_count`: boolean, true when the user has follower stat hiding enabled -- `hide_follows_count`: boolean, true when the user has follow stat hiding enabled -- `settings_store`: A generic map of settings for frontends. Opaque to the backend. Only returned in `verify_credentials` and `update_credentials` -- `chat_token`: The token needed for Pleroma chat. Only returned in `verify_credentials` -- `deactivated`: boolean, true when the user is deactivated - -### 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 - -## Conversations - -Has an additional field under the `pleroma` object: - -- `recipients`: The list of the recipients of this Conversation. These will be addressed when replying to this conversation. - -## Account Search - -Behavior has changed: - -- `/api/v1/accounts/search`: Does not require authentication - - -## Notifications - -Has these additional fields under the `pleroma` object: - -- `is_seen`: true if the notification was read by the user - -## POST `/api/v1/statuses` - -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. -- `to`: A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply. -- `visibility`: string, besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`. -- `expires_in`: The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour. -- `in_reply_to_conversation_id`: Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`. - -## GET `/api/v1/statuses` - -An endpoint to get multiple statuses by IDs. - -Required parameters: - -- `ids`: array of activity ids - -Usage example: `GET /api/v1/statuses/?ids[]=1&ids[]=2`. - -Returns: array of Status. - -The maximum number of statuses is limited to 100 per request. - -## 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_followers_count` - if true, user's follower count will be hidden -- `hide_follows_count` - if true, user's follow count 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 -- `pleroma_settings_store` - Opaque user settings to be saved on the backend. -- `skip_thread_containment` - if true, skip filtering out broken threads -- `pleroma_background_image` - sets the background image of the user. - -### Pleroma Settings Store -Pleroma has mechanism that allows frontends to save blobs of json for each user on the backend. This can be used to save frontend-specific settings for a user that the backend does not need to know about. - -The parameter should have a form of `{frontend_name: {...}}`, with `frontend_name` identifying your type of client, e.g. `pleroma_fe`. It will overwrite everything under this property, but will not overwrite other frontend's settings. - -This information is returned in the `verify_credentials` endpoint. - -## Authentication - -*Pleroma supports refreshing tokens. - -`POST /oauth/token` -Post here request with grant_type=refresh_token to obtain new access token. Returns an access token. - -## Account Registration -`POST /api/v1/accounts` - -Has theses additionnal parameters (which are the same as in Pleroma-API): - * `fullname`: optional - * `bio`: optional - * `captcha_solution`: optional, contains provider-specific captcha solution, - * `captcha_token`: optional, contains provider-specific captcha token - * `token`: invite token required when the registerations aren't public. diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md deleted file mode 100644 index 41889a0ef..000000000 --- a/docs/api/pleroma_api.md +++ /dev/null @@ -1,473 +0,0 @@ -# Pleroma API - -Requests that require it can be authenticated with [an OAuth token](https://tools.ietf.org/html/rfc6749), the `_pleroma_key` cookie, or [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization). - -Request parameters can be passed via [query strings](https://en.wikipedia.org/wiki/Query_string) or as [form data](https://www.w3.org/TR/html401/interact/forms.html). Files must be uploaded as `multipart/form-data`. - -## `/api/pleroma/emoji` -### Lists the custom emoji on that server. -* Method: `GET` -* Authentication: not required -* Params: none -* Response: JSON -* Example response: -```json -{ - "girlpower": { - "tags": [ - "Finmoji" - ], - "image_url": "/finmoji/128px/girlpower-128.png" - }, - "education": { - "tags": [ - "Finmoji" - ], - "image_url": "/finmoji/128px/education-128.png" - }, - "finnishlove": { - "tags": [ - "Finmoji" - ], - "image_url": "/finmoji/128px/finnishlove-128.png" - } -} -``` -* Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format - -## `/api/pleroma/follow_import` -### Imports your follows, for example from a Mastodon CSV file. -* Method: `POST` -* Authentication: required -* Params: - * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow -* Response: HTTP 200 on success, 500 on error -* Note: Users that can't be followed are silently skipped. - -## `/api/pleroma/captcha` -### Get a new captcha -* Method: `GET` -* Authentication: not required -* Params: none -* Response: Provider specific JSON, the only guaranteed parameter is `type` -* Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}` - -## `/api/pleroma/delete_account` -### Delete an account -* Method `POST` -* Authentication: required -* Params: - * `password`: user's password -* Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise -* Example response: `{"error": "Invalid password."}` - -## `/api/pleroma/disable_account` -### Disable an account -* Method `POST` -* Authentication: required -* Params: - * `password`: user's password -* Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise -* Example response: `{"error": "Invalid password."}` - -## `/api/account/register` -### Register a new user -* Method `POST` -* Authentication: not required -* Params: - * `nickname` - * `fullname` - * `bio` - * `email` - * `password` - * `confirm` - * `captcha_solution`: optional, contains provider-specific captcha solution, - * `captcha_token`: optional, contains provider-specific captcha token - * `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", - "created_at": "Tue Dec 18 16:55:56 +0000 2018", - "default_scope": "public", - "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.", - "description_html": "blushy-crushy fediverse idol + pleroma dev.
let's be friends
ぷれろまの生徒会長。謎の外人。日本語OK.
公主病.", - "favourites_count": 0, - "fields": [], - "followers_count": 0, - "following": false, - "follows_you": false, - "friends_count": 0, - "id": 6, - "is_local": true, - "locked": false, - "name": "lain", - "name_html": "lain", - "no_rich_text": false, - "pleroma": { - "tags": [] - }, - "profile_image_url": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png", - "rights": { - "delete_others_notice": false - }, - "screen_name": "lain", - "statuses_count": 0, - "statusnet_blocking": false, - "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain" -} -``` - -## `/api/pleroma/admin/`… -See [Admin-API](Admin-API.md) - -## `/api/v1/pleroma/notifications/read` -### Mark notifications as read -* Method `POST` -* Authentication: required -* Params (mutually exclusive): - * `id`: a single notification id to read - * `max_id`: read all notifications up to this id -* Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned. - -## `/api/v1/pleroma/accounts/:id/subscribe` -### Subscribe to receive notifications for all statuses posted by a user -* Method `POST` -* Authentication: required -* Params: - * `id`: account id to subscribe to -* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}` -* Example response: -```json -{ - "id": "abcdefg", - "following": true, - "followed_by": false, - "blocking": false, - "muting": false, - "muting_notifications": false, - "subscribing": true, - "requested": false, - "domain_blocking": false, - "showing_reblogs": true, - "endorsed": false -} -``` - -## `/api/v1/pleroma/accounts/:id/unsubscribe` -### Unsubscribe to stop receiving notifications from user statuses -* Method `POST` -* Authentication: required -* Params: - * `id`: account id to unsubscribe from -* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}` -* Example response: -```json -{ - "id": "abcdefg", - "following": true, - "followed_by": false, - "blocking": false, - "muting": false, - "muting_notifications": false, - "subscribing": false, - "requested": false, - "domain_blocking": false, - "showing_reblogs": true, - "endorsed": false -} -``` - -## `/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/v1/pleroma/accounts/update_*` -### Set and clear account avatar, banner, and background - -- PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image -- PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image -- PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image - -## `/api/v1/pleroma/accounts/confirmation_resend` -### Resend confirmation email -* Method `POST` -* Params: - * `email`: email of that needs to be verified -* Authentication: not required -* Response: 204 No Content - -## `/api/v1/pleroma/mascot` -### Gets user mascot image -* Method `GET` -* Authentication: required - -* Response: JSON. Returns a mastodon media attachment entity. -* Example response: -```json -{ - "id": "abcdefg", - "url": "https://pleroma.example.org/media/abcdefg.png", - "type": "image", - "pleroma": { - "mime_type": "image/png" - } -} -``` - -### Updates user mascot image -* Method `PUT` -* Authentication: required -* Params: - * `image`: Multipart image -* Response: JSON. Returns a mastodon media attachment entity - when successful, otherwise returns HTTP 415 `{"error": "error_msg"}` -* Example response: -```json -{ - "id": "abcdefg", - "url": "https://pleroma.example.org/media/abcdefg.png", - "type": "image", - "pleroma": { - "mime_type": "image/png" - } -} -``` -* Note: Behaves exactly the same as `POST /api/v1/upload`. - Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`. - -## `/api/pleroma/notification_settings` -### Updates user notification settings -* Method `PUT` -* Authentication: required -* Params: - * `followers`: BOOLEAN field, receives notifications from followers - * `follows`: BOOLEAN field, receives notifications from people the user follows - * `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 -} -``` - -## `/api/pleroma/change_email` -### Change account email -* Method `POST` -* Authentication: required -* Params: - * `password`: user's password - * `email`: new email -* Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise -* Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma. - -# Pleroma Conversations - -Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints: - -1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user. -2. Pleroma Conversations statuses can be requested by Conversation id. -3. Pleroma Conversations can be replied to. - -Conversations have the additional field "recipients" under the "pleroma" key. This holds a list of all the accounts that will receive a message in this conversation. - -The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation. - - -## `GET /api/v1/pleroma/conversations/:id/statuses` -### Timeline for a given conversation -* Method `GET` -* Authentication: required -* Params: Like other timelines -* Response: JSON, statuses (200 - healthy, 503 unhealthy). - -## `GET /api/v1/pleroma/conversations/:id` -### The conversation with the given ID. -* Method `GET` -* Authentication: required -* Params: None -* Response: JSON, statuses (200 - healthy, 503 unhealthy). - -## `PATCH /api/v1/pleroma/conversations/:id` -### Update a conversation. Used to change the set of recipients. -* Method `PATCH` -* Authentication: required -* Params: - * `recipients`: A list of ids of users that should receive posts to this conversation. This will replace the current list of recipients, so submit the full list. The owner of owner of the conversation will always be part of the set of recipients, though. -* Response: JSON, statuses (200 - healthy, 503 unhealthy) - -## `GET /api/pleroma/emoji/packs` -### Lists the custom emoji packs on the server -* Method `GET` -* Authentication: not required -* Params: None -* Response: JSON, "ok" and 200 status and the JSON hashmap of "pack name" to "pack contents" - -## `PUT /api/pleroma/emoji/packs/:name` -### Creates an empty custom emoji pack -* Method `PUT` -* Authentication: required -* Params: None -* Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists - -## `DELETE /api/pleroma/emoji/packs/:name` -### Delete a custom emoji pack -* Method `DELETE` -* Authentication: required -* Params: None -* Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack - -## `POST /api/pleroma/emoji/packs/:name/update_file` -### Update a file in a custom emoji pack -* Method `POST` -* Authentication: required -* Params: - * if the `action` is `add`, adds an emoji named `shortcode` to the pack `pack_name`, - that means that the emoji file needs to be uploaded with the request - (thus requiring it to be a multipart request) and be named `file`. - There can also be an optional `filename` that will be the new emoji file name - (if it's not there, the name will be taken from the uploaded file). - * if the `action` is `update`, changes emoji shortcode - (from `shortcode` to `new_shortcode` or moves the file (from the current filename to `new_filename`) - * if the `action` is `remove`, removes the emoji named `shortcode` and it's associated file -* Response: JSON, updated "files" section of the pack and 200 status, 409 if the trying to use a shortcode - that is already taken, 400 if there was an error with the shortcode, filename or file (additional info - in the "error" part of the response JSON) - -## `POST /api/pleroma/emoji/packs/:name/update_metadata` -### Updates (replaces) pack metadata -* Method `POST` -* Authentication: required -* Params: - * `new_data`: new metadata to replace the old one -* Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a - problem with the new metadata (the error is specified in the "error" part of the response JSON) - -## `POST /api/pleroma/emoji/packs/download_from` -### Requests the instance to download the pack from another instance -* Method `POST` -* Authentication: required -* Params: - * `instance_address`: the address of the instance to download from - * `pack_name`: the pack to download from that instance -* Response: JSON, "ok" and 200 status if the pack was downloaded, or 500 if there were - errors downloading the pack - -## `POST /api/pleroma/emoji/packs/list_from` -### Requests the instance to list the packs from another instance -* Method `POST` -* Authentication: required -* Params: - * `instance_address`: the address of the instance to download from -* Response: JSON with the pack list, same as if the request was made to that instance's - list endpoint directly + 200 status - -## `GET /api/pleroma/emoji/packs/:name/download_shared` -### Requests a local pack from the instance -* Method `GET` -* Authentication: not required -* Params: None -* Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared, - 404 if the pack does not exist - -## `GET /api/v1/pleroma/accounts/:id/scrobbles` -### Requests a list of current and recent Listen activities for an account -* Method `GET` -* Authentication: not required -* Params: None -* Response: An array of media metadata entities. -* Example response: -```json -[ - { - "account": {...}, - "id": "1234", - "title": "Some Title", - "artist": "Some Artist", - "album": "Some Album", - "length": 180000, - "created_at": "2019-09-28T12:40:45.000Z" - } -] -``` - -## `POST /api/v1/pleroma/scrobble` -### Creates a new Listen activity for an account -* Method `POST` -* Authentication: required -* 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] -* Response: the newly created media metadata entity representing the Listen activity diff --git a/docs/api/prometheus.md b/docs/api/prometheus.md deleted file mode 100644 index 19c564e3c..000000000 --- a/docs/api/prometheus.md +++ /dev/null @@ -1,22 +0,0 @@ -# Prometheus Metrics - -Pleroma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library. - -## `/api/pleroma/app_metrics` -### Exports Prometheus application metrics -* Method: `GET` -* Authentication: not required -* Params: none -* Response: JSON - -## Grafana -### Config example -The following is a config example to use with [Grafana](https://grafana.com) - -``` - - job_name: 'beam' - metrics_path: /api/pleroma/app_metrics - scheme: https - static_configs: - - targets: ['pleroma.soykaf.com'] -``` diff --git a/docs/config.md b/docs/config.md deleted file mode 100644 index 262d15bba..000000000 --- a/docs/config.md +++ /dev/null @@ -1,773 +0,0 @@ -# Configuration - -This file describe the configuration, it is recommended to edit the relevant *.secret.exs file instead of the others founds in the ``config`` directory. -If you run Pleroma with ``MIX_ENV=prod`` the file is ``prod.secret.exs``, otherwise it is ``dev.secret.exs``. - -## Pleroma.Upload -* `uploader`: Select which `Pleroma.Uploaders` to use -* `filters`: List of `Pleroma.Upload.Filter` to use. -* `link_name`: When enabled Pleroma will add a `name` parameter to the url of the upload, for example `https://instance.tld/media/corndog.png?name=corndog.png`. This is needed to provide the correct filename in Content-Disposition headers when using filters like `Pleroma.Upload.Filter.Dedupe` -* `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host. -* `proxy_remote`: If you're using a remote uploader, Pleroma will proxy media requests instead of redirecting to it. -* `proxy_opts`: Proxy options, see `Pleroma.ReverseProxy` documentation. - -Note: `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`. - -## Pleroma.Uploaders.Local -* `uploads`: Which directory to store the user-uploads in, relative to pleroma’s working directory - -## Pleroma.Uploaders.S3 -* `bucket`: S3 bucket name -* `bucket_namespace`: S3 bucket namespace -* `public_endpoint`: S3 endpoint that the user finally accesses(ex. "https://s3.dualstack.ap-northeast-1.amazonaws.com") -* `truncated_namespace`: If you use S3 compatible service such as Digital Ocean Spaces or CDN, set folder name or "" etc. -For example, when using CDN to S3 virtual host format, set "". -At this time, write CNAME to CDN in public_endpoint. -* `streaming_enabled`: Enable streaming uploads, when enabled the file will be sent to the server in chunks as it's being read. This may be unsupported by some providers, try disabling this if you have upload problems. - -## Pleroma.Upload.Filter.Mogrify - -* `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"implode", "1"}]`. - -## Pleroma.Upload.Filter.Dedupe - -No specific configuration. - -## Pleroma.Upload.Filter.AnonymizeFilename - -This filter replaces the filename (not the path) of an upload. For complete obfuscation, add -`Pleroma.Upload.Filter.Dedupe` before AnonymizeFilename. - -* `text`: Text to replace filenames in links. If empty, `{random}.extension` will be used. You can get the original filename extension by using `{extension}`, for example `custom-file-name.{extension}`. - -## 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. -* `enabled`: Allows enable/disable send emails. Default: `false`. - -An example for Sendgrid adapter: - -```elixir -config :pleroma, Pleroma.Emails.Mailer, - adapter: Swoosh.Adapters.Sendgrid, - api_key: "YOUR_API_KEY" -``` - -An example for SMTP adapter: - -```elixir -config :pleroma, Pleroma.Emails.Mailer, - adapter: Swoosh.Adapters.SMTP, - relay: "smtp.gmail.com", - username: "YOUR_USERNAME@gmail.com", - password: "YOUR_SMTP_PASSWORD", - port: 465, - ssl: true, - tls: :always, - auth: :always -``` - -## :uri_schemes -* `valid_schemes`: List of the scheme part that is considered valid to be an URL - -## :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. -* `upload_limit`: File size limit of uploads (except for avatar, background, banner) -* `avatar_upload_limit`: File size limit of user’s profile avatars -* `background_upload_limit`: File size limit of user’s profile backgrounds -* `banner_upload_limit`: File size limit of user’s profile banners -* `poll_limits`: A map with poll limits for **local** polls - * `max_options`: Maximum number of options - * `max_option_chars`: Maximum number of characters per option - * `min_expiration`: Minimum expiration time (in seconds) - * `max_expiration`: Maximum expiration time (in seconds) -* `registrations_open`: Enable registrations for anyone, invitations can be enabled when false. -* `invites_enabled`: Enable user invitations for admins (depends on `registrations_open: false`). -* `account_activation_required`: Require users to confirm their emails before signing in. -* `federating`: Enable federation with other instances -* `federation_incoming_replies_max_depth`: Max. depth of reply-to activities fetching on incoming federation, to prevent out-of-memory situations while fetching very long threads. If set to `nil`, threads of any depth will be fetched. Lower this value if you experience out-of-memory crashes. -* `federation_reachability_timeout_days`: Timeout (in days) of each external federation target being unreachable prior to pausing federating to it. -* `allow_relay`: Enable Pleroma’s Relay, which makes it possible to follow a whole instance -* `rewrite_policy`: Message Rewrite Policy, either one or a list. Here are the ones available by default: - * `Pleroma.Web.ActivityPub.MRF.NoOpPolicy`: Doesn’t modify activities (default) - * `Pleroma.Web.ActivityPub.MRF.DropPolicy`: Drops all activities. It generally doesn’t makes sense to use in production - * `Pleroma.Web.ActivityPub.MRF.SimplePolicy`: Restrict the visibility of activities from certains instances (See ``:mrf_simple`` section) - * `Pleroma.Web.ActivityPub.MRF.TagPolicy`: Applies policies to individual users based on tags, which can be set using pleroma-fe/admin-fe/any other app that supports Pleroma Admin API. For example it allows marking posts from individual users nsfw (sensitive) - * `Pleroma.Web.ActivityPub.MRF.SubchainPolicy`: Selectively runs other MRF policies when messages match (see ``:mrf_subchain`` section) - * `Pleroma.Web.ActivityPub.MRF.RejectNonPublic`: Drops posts with non-public visibility settings (See ``:mrf_rejectnonpublic`` section) - * `Pleroma.Web.ActivityPub.MRF.EnsureRePrepended`: Rewrites posts to ensure that replies to posts with subjects do not have an identical subject and instead begin with re:. - * `Pleroma.Web.ActivityPub.MRF.AntiLinkSpamPolicy`: Rejects posts from likely spambots by rejecting posts from new users that contain links. - * `Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy`: Crawls attachments using their MediaProxy URLs so that the MediaProxy cache is primed. - * `Pleroma.Web.ActivityPub.MRF.MentionPolicy`: Drops posts mentioning configurable users. (see `:mrf_mention` section) - * `Pleroma.Web.ActivityPub.MRF.VocabularyPolicy`: Restricts activities to a configured set of vocabulary. (see `:mrf_vocabulary` section) -* `public`: Makes the client API in authentificated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network. -* `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) -* `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). -* `mrf_transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. -* `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: - * "email": Copy and preprend re:, as in email. - * "masto": Copy verbatim, as in Mastodon. - * "noop": Don't copy the subject. -* `always_show_subject_input`: When set to false, auto-hide the subject field when it's empty. -* `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with - older software for theses nicknames. -* `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature. -* `autofollowed_nicknames`: Set to nicknames of (local) users that every new user should automatically follow. -* `no_attachment_links`: Set to true to disable automatically adding attachment link text to statuses -* `welcome_message`: A message that will be send to a newly registered users as a direct message. -* `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``. -* `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database. -* `user_bio_length`: A user bio maximum length (default: `5000`) -* `user_name_length`: A user name maximum length (default: `100`) -* `skip_thread_containment`: Skip filter out broken threads. The default is `false`. -* `limit_to_local_content`: Limit unauthenticated users to search for local statutes and users only. Possible values: `:unauthenticated`, `:all` and `false`. The default is `:unauthenticated`. -* `dynamic_configuration`: Allow transferring configuration to DB with the subsequent customization from Admin api. -* `max_account_fields`: The maximum number of custom fields in the user profile (default: `10`) -* `max_remote_account_fields`: The maximum number of custom fields in the remote user profile (default: `20`) -* `account_field_name_length`: An account field name maximum length (default: `512`) -* `account_field_value_length`: An account field value maximum length (default: `2048`) -* `external_user_synchronization`: Enabling following/followers counters synchronization for external users. - - - -## :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}] - -config :logger, :ex_syslogger, - level: :warn -``` - -Another example, keeping console output and adding the pid to syslog output: -```elixir -config :logger, - backends: [:console, {ExSyslogger, :ex_syslogger}] - -config :logger, :ex_syslogger, - level: :warn, - option: [:pid, :ndelay] -``` - -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 - -config :logger, :ex_syslogger, - level: :info, - ident: "pleroma", - format: "$metadata[$level] $message" - -config :quack, - level: :warn, - meta: [:all], - webhook_url: "https://hooks.slack.com/services/YOUR-API-KEY-HERE" -``` - -See the [Quack Github](https://github.com/azohra/quack) for more details - -## :frontend_configurations - -This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. - -Frontends can access these settings at `/api/pleroma/frontend_configurations` - -To add your own configuration for PleromaFE, use it like this: - -```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. - -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`](#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. - -* `theme`: Which theme to use, they are defined in ``styles.json`` -* `logo`: URL of the logo, defaults to Pleroma’s logo -* `logo_mask`: Whether to use only the logo's shape as a mask (true) or as a regular image (false) -* `logo_margin`: What margin to use around the logo -* `background`: URL of the background, unless viewing a user profile with a background that is set -* `redirect_root_no_login`: relative URL which indicates where to redirect when a user isn’t logged in. -* `redirect_root_login`: relative URL which indicates where to redirect when a user is logged in. -* `show_instance_panel`: Whenether to show the instance’s specific panel. -* `scope_options_enabled`: Enable setting an notice visibility and subject/CW when posting -* `formatting_options_enabled`: Enable setting a formatting different than plain-text (ie. HTML, Markdown) when posting, relates to ``:instance, allowed_post_formats`` -* `collapse_message_with_subjects`: When a message has a subject(aka Content Warning), collapse it by default -* `hide_post_stats`: Hide notices statistics(repeats, favorites, …) -* `hide_user_stats`: Hide profile statistics(posts, posts per day, followers, followings, …) - -## :assets - -This section configures assets to be used with various frontends. Currently the only option -relates to mascots on the mastodon frontend - -* `mascots`: KeywordList of mascots, each element __MUST__ contain both a `url` and a - `mime_type` key. -* `default_mascot`: An element from `mascots` - This will be used as the default mascot - on MastoFE (default: `:pleroma_fox_tan`) - -## :mrf_simple -* `media_removal`: List of instances to remove medias from -* `media_nsfw`: List of instances to put medias as NSFW(sensitive) from -* `federated_timeline_removal`: List of instances to remove from Federated (aka The Whole Known Network) Timeline -* `reject`: List of instances to reject any activities from -* `accept`: List of instances to accept any activities from -* `report_removal`: List of instances to reject reports from -* `avatar_removal`: List of instances to strip avatars from -* `banner_removal`: List of instances to strip banners from - -## :mrf_subchain -This policy processes messages through an alternate pipeline when a given message matches certain criteria. -All criteria are configured as a map of regular expressions to lists of policy modules. - -* `match_actor`: Matches a series of regular expressions against the actor field. - -Example: - -``` -config :pleroma, :mrf_subchain, - match_actor: %{ - ~r/https:\/\/example.com/s => [Pleroma.Web.ActivityPub.MRF.DropPolicy] - } -``` - -## :mrf_rejectnonpublic -* `allow_followersonly`: whether to allow followers-only posts -* `allow_direct`: whether to allow direct messages - -## :mrf_hellthread -* `delist_threshold`: Number of mentioned users after which the message gets delisted (the message can still be seen, but it will not show up in public timelines and mentioned users won't get notifications about it). Set to 0 to disable. -* `reject_threshold`: Number of mentioned users after which the messaged gets rejected. Set to 0 to disable. - -## :mrf_keyword -* `reject`: A list of patterns which result in message being rejected, each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) -* `federated_timeline_removal`: A list of patterns which result in message being removed from federated timelines (a.k.a unlisted), each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) -* `replace`: A list of tuples containing `{pattern, replacement}`, `pattern` can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) - -## :mrf_mention -* `actors`: A list of actors, for which to drop any posts mentioning. - -## :mrf_vocabulary -* `accept`: A list of ActivityStreams terms to accept. If empty, all supported messages are accepted. -* `reject`: A list of ActivityStreams terms to reject. If empty, no messages are rejected. - -## :media_proxy -* `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 -* `ip`: IP address to bind to -* `port`: Port to bind to -* `dstport`: Port advertised in urls (optional, defaults to `port`) - -## Pleroma.Web.Endpoint -`Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here -* `http` - a list containing http protocol configuration, all configuration options can be viewed [here](https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html#module-options), only common options are listed here. For deployment using docker, you need to set this to `[ip: {0,0,0,0}, port: 4000]` to make pleroma accessible from other containers (such as your nginx server). - - `ip` - a tuple consisting of 4 integers - - `port` -* `url` - a list containing the configuration for generating urls, accepts - - `host` - the host without the scheme and a post (e.g `example.com`, not `https://example.com:2020`) - - `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 - -Example: -```elixir -config :pleroma, Pleroma.Web.Endpoint, - url: [host: "example.com", port: 2020, scheme: "https"], - http: [ - # start copied from config.exs - dispatch: [ - {:_, - [ - {"/api/v1/streaming", Pleroma.Web.MastodonAPI.WebsocketHandler, []}, - {"/websocket", Phoenix.Endpoint.CowboyWebSocket, - {Phoenix.Transports.WebSocket, - {Pleroma.Web.Endpoint, Pleroma.Web.UserSocket, websocket_config}}}, - {:_, Phoenix.Endpoint.Cowboy2Handler, {Pleroma.Web.Endpoint, []}} - ]} - # end copied from config.exs - ], - port: 8080, - ip: {127, 0, 0, 1} - ] -``` - -This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls starting with `https://example.com:2020` - -## :activitypub -* ``unfollow_blocked``: Whether blocks result in people getting unfollowed -* ``outgoing_blocks``: Whether to federate blocks to other instances -* ``deny_follow_blocked``: Whether to disallow following an account that has blocked the user in question -* ``sign_object_fetches``: Sign object fetches with HTTP signatures - -## :http_security -* ``enabled``: Whether the managed content security policy is enabled -* ``sts``: Whether to additionally send a `Strict-Transport-Security` header -* ``sts_max_age``: The maximum age for the `Strict-Transport-Security` header if sent -* ``ct_max_age``: The maximum age for the `Expect-CT` header if sent -* ``referrer_policy``: The referrer policy to use, either `"same-origin"` or `"no-referrer"` -* ``report_uri``: Adds the specified url to `report-uri` and `report-to` group in CSP header. - -## :mrf_user_allowlist - -The keys in this section are the domain names that the policy should apply to. -Each key should be assigned a list of users that should be allowed through by -their ActivityPub ID. - -An example: - -```elixir -config :pleroma, :mrf_user_allowlist, - "example.org": ["https://example.org/users/admin"] -``` - -## :web_push_encryption, :vapid_details - -Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it. - -* ``subject``: a mailto link for the administrative contact. It’s best if this email is not a personal email address, but rather a group email so that if a person leaves an organization, is unavailable for an extended period, or otherwise can’t respond, someone else on the list can. -* ``public_key``: VAPID public key -* ``private_key``: VAPID private key - -## Pleroma.Captcha -* `enabled`: Whether the captcha should be shown on registration -* `method`: The method/service to use for captcha -* `seconds_valid`: The time in seconds for which the captcha is valid - -### Pleroma.Captcha.Kocaptcha -Kocaptcha is a very simple captcha service with a single API endpoint, -the source code is here: https://github.com/koto-bank/kocaptcha. The default endpoint -`https://captcha.kotobank.ch` is hosted by the developer. - -* `endpoint`: the kocaptcha endpoint to use - -## :admin_token - -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: - -```elixir -config :pleroma, :admin_token, "somerandomtoken" -``` - -You can then do - -```sh -curl "http://localhost:4000/api/pleroma/admin/invite_token?admin_token=somerandomtoken" -``` - -## Oban - -[Oban](https://github.com/sorentwo/oban) asynchronous job processor configuration. - -Configuration options described in [Oban readme](https://github.com/sorentwo/oban#usage): -* `repo` - app's Ecto repo (`Pleroma.Repo`) -* `verbose` - logs verbosity -* `prune` - non-retryable jobs [pruning settings](https://github.com/sorentwo/oban#pruning) (`:disabled` / `{:maxlen, value}` / `{:maxage, value}`) -* `queues` - job queues (see below) - -Pleroma has the following queues: - -* `activity_expiration` - Activity expiration -* `federator_outgoing` - Outgoing federation -* `federator_incoming` - Incoming federation -* `mailer` - Email sender, see [`Pleroma.Emails.Mailer`](#pleromaemailsmailer) -* `transmogrifier` - Transmogrifier -* `web_push` - Web push notifications -* `scheduled_activities` - Scheduled activities, see [`Pleroma.ScheduledActivity`](#pleromascheduledactivity) - -Example: - -```elixir -config :pleroma, Oban, - repo: Pleroma.Repo, - verbose: false, - prune: {:maxlen, 1500}, - queues: [ - federator_incoming: 50, - federator_outgoing: 50 - ] -``` - -This config contains two queues: `federator_incoming` and `federator_outgoing`. Both have the number of max concurrent jobs set to `50`. - -### Migrating `pleroma_job_queue` settings - -`config :pleroma_job_queue, :queues` is replaced by `config :pleroma, Oban, :queues` and uses the same format (keys are queues' names, values are max concurrent jobs numbers). - -### Note on running with PostgreSQL in silent mode - -If you are running PostgreSQL in [`silent_mode`](https://postgresqlco.nf/en/doc/param/silent_mode?version=9.1), it's advised to set [`log_destination`](https://postgresqlco.nf/en/doc/param/log_destination?version=9.1) to `syslog`, -otherwise `postmaster.log` file may grow because of "you don't own a lock of type ShareLock" warnings (see https://github.com/sorentwo/oban/issues/52). - -## :workers - -Includes custom worker options not interpretable directly by `Oban`. - -* `retries` — keyword lists where keys are `Oban` queues (see above) and values are numbers of max attempts for failed jobs. - -Example: - -```elixir -config :pleroma, :workers, - retries: [ - federator_incoming: 5, - federator_outgoing: 5 - ] -``` - -### Migrating `Pleroma.Web.Federator.RetryQueue` settings - -* `max_retries` is replaced with `config :pleroma, :workers, retries: [federator_outgoing: 5]` -* `enabled: false` corresponds to `config :pleroma, :workers, retries: [federator_outgoing: 1]` -* deprecated options: `max_jobs`, `initial_timeout` - -## Pleroma.Web.Metadata -* `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 `
` as `` -* `unfurl_nsfw`: If set to `true` nsfw attachments will be shown in previews - -## :rich_media -* `enabled`: if enabled the instance will parse metadata from attached links to generate link previews -* `ignore_hosts`: list of hosts which will be ignored by the metadata parser. For example `["accounts.google.com", "xss.website"]`, defaults to `[]`. -* `ignore_tld`: list TLDs (top-level domains) which will ignore for parse metadata. default is ["local", "localdomain", "lan"] -* `parsers`: list of Rich Media parsers - -## :fetch_initial_posts -* `enabled`: if enabled, when a new user is federated with, fetch some of their latest posts -* `pages`: the amount of pages to fetch - -## :hackney_pools - -Advanced. Tweaks Hackney (http client) connections pools. - -There's three pools used: - -* `:federation` for the federation jobs. - You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs. -* `:media` for rich media, media proxy -* `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`) - -For each pool, the options are: - -* `max_connections` - how much connections a pool can hold -* `timeout` - retention duration for connections - -## :auto_linker - -Configuration for the `auto_linker` library: - -* `class: "auto-linker"` - specify the class to be added to the generated link. false to clear -* `rel: "noopener noreferrer"` - override the rel attribute. false to clear -* `new_window: true` - set to false to remove `target='_blank'` attribute -* `scheme: false` - Set to true to link urls with schema `http://google.com` -* `truncate: false` - Set to a number to truncate urls longer then the number. Truncated urls will end in `..` -* `strip_prefix: true` - Strip the scheme prefix -* `extra: false` - link urls with rarely used schemes (magnet, ipfs, irc, etc.) - -Example: - -```elixir -config :auto_linker, - opts: [ - scheme: true, - extra: true, - class: false, - strip_prefix: false, - new_window: false, - rel: "ugc" - ] -``` - -## Pleroma.Scheduler - -Configuration for [Quantum](https://github.com/quantum-elixir/quantum-core) jobs scheduler. - -See [Quantum readme](https://github.com/quantum-elixir/quantum-core#usage) for the list of supported options. - -Example: - -```elixir -config :pleroma, Pleroma.Scheduler, - global: true, - overlap: true, - timezone: :utc, - jobs: [{"0 */6 * * * *", {Pleroma.Web.Websub, :refresh_subscriptions, []}}] -``` - -The above example defines a single job which invokes `Pleroma.Web.Websub.refresh_subscriptions()` every 6 hours ("0 */6 * * * *", [crontab format](https://en.wikipedia.org/wiki/Cron)). - -## Pleroma.ScheduledActivity - -* `daily_user_limit`: the number of scheduled activities a user is allowed to create in a single day (Default: `25`) -* `total_user_limit`: the number of scheduled activities a user is allowed to create in total (Default: `300`) -* `enabled`: whether scheduled activities are sent to the job queue to be executed - -## Pleroma.ActivityExpiration - -# `enabled`: whether expired activities will be sent to the job queue to be deleted - -## Pleroma.Web.Auth.Authenticator - -* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator -* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication - -## :ldap - -Use LDAP for user authentication. When a user logs in to the Pleroma -instance, the name and password will be verified by trying to authenticate -(bind) to an LDAP server. If a user exists in the LDAP directory but there -is no account with the same name yet on the Pleroma instance then a new -Pleroma account will be created with the same name as the LDAP user name. - -* `enabled`: enables LDAP authentication -* `host`: LDAP server hostname -* `port`: LDAP port, e.g. 389 or 636 -* `ssl`: true to use SSL, usually implies the port 636 -* `sslopts`: additional SSL options -* `tls`: true to start TLS, usually implies the port 389 -* `tlsopts`: additional TLS options -* `base`: LDAP base, e.g. "dc=example,dc=com" -* `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base" - -## BBS / SSH access - -To enable simple command line interface accessible over ssh, add a setting like this to your configuration file: - -```exs -app_dir = File.cwd! -priv_dir = Path.join([app_dir, "priv/ssh_keys"]) - -config :esshd, - enabled: true, - priv_dir: priv_dir, - handler: "Pleroma.BBS.Handler", - port: 10_022, - password_authenticator: "Pleroma.BBS.Authenticator" -``` - -Feel free to adjust the priv_dir and port number. Then you will have to create the key for the keys (in the example `priv/ssh_keys`) and create the host keys with `ssh-keygen -m PEM -N "" -b 2048 -t rsa -f ssh_host_rsa_key`. After restarting, you should be able to connect to your Pleroma instance with `ssh username@server -p $PORT` - -## :auth - -* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator -* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication - -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`. -* `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. Each entry in this space-delimited string should be of format `` or `:` (e.g. `twitter` or `keycloak:ueberauth_keycloak_strategy` in case dependency is named differently than `ueberauth_`). - -## :email_notifications - -Email notifications settings. - - - digest - emails of "what you've missed" for users who have been - inactive for a while. - - active: globally enable or disable digest emails - - schedule: When to send digest email, in [crontab format](https://en.wikipedia.org/wiki/Cron). - "0 0 * * 0" is the default, meaning "once a week at midnight on Sunday morning" - - interval: Minimum interval between digest emails to one user - - inactivity_threshold: Minimum user inactivity threshold - -## Pleroma.Emails.UserEmail - -- `:logo` - a path to a custom logo. Set it to `nil` to use the default Pleroma logo. -- `:styling` - a map with color settings for email templates. - -## OAuth consumer mode - -OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.). -Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies). - -Note: each strategy is shipped as a separate dependency; in order to get the strategies, run `OAUTH_CONSUMER_STRATEGIES="..." mix deps.get`, -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: 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:///oauth/twitter/callback - -* For Facebook, [register an app](https://developers.facebook.com/apps), configure callback URL to https:///oauth/facebook/callback, enable Facebook Login service at https://developers.facebook.com/apps//fb-login/settings/ - -* For Google, [register an app](https://console.developers.google.com), configure callback URL to https:///oauth/google/callback - -* For Microsoft, [register an app](https://portal.azure.com), configure callback URL to https:///oauth/microsoft/callback - -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"), - consumer_secret: System.get_env("TWITTER_CONSUMER_SECRET") - -# Facebook -config :ueberauth, Ueberauth.Strategy.Facebook.OAuth, - client_id: System.get_env("FACEBOOK_APP_ID"), - client_secret: System.get_env("FACEBOOK_APP_SECRET"), - redirect_uri: System.get_env("FACEBOOK_REDIRECT_URI") - -# Google -config :ueberauth, Ueberauth.Strategy.Google.OAuth, - client_id: System.get_env("GOOGLE_CLIENT_ID"), - client_secret: System.get_env("GOOGLE_CLIENT_SECRET"), - redirect_uri: System.get_env("GOOGLE_REDIRECT_URI") - -# Microsoft -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: []]} - ] - -# Keycloak -# Note: make sure to add `keycloak:ueberauth_keycloak_strategy` entry to `OAUTH_CONSUMER_STRATEGIES` environment variable -keycloak_url = "https://publicly-reachable-keycloak-instance.org:8080" - -config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth, - client_id: System.get_env("KEYCLOAK_CLIENT_ID"), - client_secret: System.get_env("KEYCLOAK_CLIENT_SECRET"), - site: keycloak_url, - authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth", - token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token", - userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo", - token_method: :post - -config :ueberauth, Ueberauth, - providers: [ - keycloak: {Ueberauth.Strategy.Keycloak, [uid_field: :email]} - ] -``` - -## OAuth 2.0 provider - :oauth2 - -Configure OAuth 2 provider capabilities: - -* `token_expires_in` - The lifetime in seconds of the access token. -* `issue_new_refresh_token` - Keeps old refresh token or generate new refresh token when to obtain an access token. -* `clean_expired_tokens` - Enable a background job to clean expired oauth tokens. Defaults to `false`. -* `clean_expired_tokens_interval` - Interval to run the job to clean expired tokens. Defaults to `86_400_000` (24 hours). - -## :emoji -* `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]` -* `pack_extensions`: A list of file extensions for emojis, when no emoji.txt for a pack is present. Example `[".png", ".gif"]` -* `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). -* `shared_pack_cache_seconds_per_file`: When an emoji pack is shared, the archive is created and cached in - memory for this amount of seconds multiplied by the number of files. - -## Database options - -### RUM indexing for full text search -* `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. - -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. - -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/` - -This will probably take a long time. - -## :rate_limit - -This is an advanced feature and disabled by default. - -If your instance is behind a reverse proxy you must enable and configure [`Pleroma.Plugs.RemoteIp`](#pleroma-plugs-remoteip). - -A keyword list of rate limiters where a key is a limiter name and value is the limiter configuration. The basic configuration is a tuple where: - -* The first element: `scale` (Integer). The time scale in milliseconds. -* The second element: `limit` (Integer). How many requests to limit in the time scale provided. - -It is also possible to have different limits for unauthenticated and authenticated users: the keyword value must be a list of two tuples where the first one is a config for unauthenticated users and the second one is for authenticated. - -See [`Pleroma.Plugs.RateLimiter`](Pleroma.Plugs.RateLimiter.html) documentation for examples. - -Supported rate limiters: - -* `:search` for the search requests (account & status search etc.) -* `:app_account_creation` for registering user accounts from the same IP address -* `:relations_actions` for actions on relations with all users (follow, unfollow) -* `:relation_id_action` for actions on relation with a specific user (follow, unfollow) -* `:statuses_actions` for create / delete / fav / unfav / reblog / unreblog actions on any statuses -* `:status_id_action` for fav / unfav or reblog / unreblog actions on the same status by the same user - -## :web_cache_ttl - -The expiration time for the web responses cache. Values should be in milliseconds or `nil` to disable expiration. - -Available caches: - -* `:activity_pub` - activity pub routes (except question activities). Defaults to `nil` (no expiration). -* `:activity_pub_question` - activity pub routes (question activities). Defaults to `30_000` (30 seconds). - -## Pleroma.Plugs.RemoteIp - -**If your instance is not behind at least one reverse proxy, you should not enable this plug.** - -`Pleroma.Plugs.RemoteIp` is a shim to call [`RemoteIp`](https://git.pleroma.social/pleroma/remote_ip) but with runtime configuration. - -Available options: - -* `enabled` - Enable/disable the plug. Defaults to `false`. -* `headers` - A list of strings naming the `req_headers` to use when deriving the `remote_ip`. Order does not matter. Defaults to `~w[forwarded x-forwarded-for x-client-ip x-real-ip]`. -* `proxies` - A list of strings in [CIDR](https://en.wikipedia.org/wiki/CIDR) notation specifying the IPs of known proxies. Defaults to `[]`. -* `reserved` - Defaults to [localhost](https://en.wikipedia.org/wiki/Localhost) and [private network](https://en.wikipedia.org/wiki/Private_network). diff --git a/docs/config/General-tips-for-customizing-Pleroma-FE.md b/docs/config/General-tips-for-customizing-Pleroma-FE.md deleted file mode 100644 index 15c4882dd..000000000 --- a/docs/config/General-tips-for-customizing-Pleroma-FE.md +++ /dev/null @@ -1,17 +0,0 @@ -# General tips for customizing Pleroma FE -There are some configuration scripts for Pleroma BE and FE: - -1. `config/prod.secret.exs` -1. `config/config.exs` -1. `priv/static/static/config.json` - -The `prod.secret.exs` affects first. `config.exs` is for fallback or default. `config.json` is for GNU-social-BE-Pleroma-FE instances. - -Usually all you have to do is: - -1. Copy the section in the `config/config.exs` which you want to activate. -1. Paste into `config/prod.secret.exs`. -1. Edit `config/prod.secret.exs`. -1. Restart the Pleroma daemon. - -`prod.secret.exs` is for the `MIX_ENV=prod` environment. `dev.secret.exs` is for the `MIX_ENV=dev` environment respectively. diff --git a/docs/config/custom_emoji.md b/docs/config/custom_emoji.md deleted file mode 100644 index f72c0edbc..000000000 --- a/docs/config/custom_emoji.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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: -* 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 `instance/static/emoji/custom`): `happy.png` and `sad.png` - -content of `emoji.txt`: -``` -happy, /emoji/custom/happy.png, Tag1,Tag2 -sad, /emoji/custom/sad.png, Tag1 -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`. 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"], - groups: [ - Finmoji: "/finmoji/128px/*-128.png", - Custom: ["/emoji/*.png", "/emoji/custom/*.png"] - ] -``` - -Order of the `groups` matters, so to override default tags just put your group on top of the list. E.g: -```elixir -config :pleroma, :emoji, - shortcode_globs: ["/emoji/custom/**/*.png"], - groups: [ - "Finmoji special": "/finmoji/128px/a_trusted_friend-128.png", # special file - "Cirno": "/emoji/custom/cirno*.png", # png files in /emoji/custom/ which start with `cirno` - "Special group": "/emoji/custom/special_folder/*.png", # png files in /emoji/custom/special_folder/ - "Another group": "/emoji/custom/special_folder/*/.png", # png files in /emoji/custom/special_folder/ subfolders - Finmoji: "/finmoji/128px/*-128.png", - Custom: ["/emoji/*.png", "/emoji/custom/*.png"] - ] -``` - -Priority of tags assigns in emoji.txt and custom.txt: - -`tag in file > special group setting in config.exs > default setting in config.exs` - -Priority for globs: - -`special group setting in config.exs > default setting in config.exs` diff --git a/docs/config/hardening.md b/docs/config/hardening.md deleted file mode 100644 index b54c28850..000000000 --- a/docs/config/hardening.md +++ /dev/null @@ -1,103 +0,0 @@ -# Hardening your instance -Here are some suggestions which improve the security of parts of your Pleroma instance. - -## Configuration file - -These changes should go into `prod.secret.exs` or `dev.secret.exs`, depending on your `MIX_ENV` value. - -### `http` - -> Recommended value: `[ip: {127, 0, 0, 1}]` - -This sets the Pleroma application server to only listen to the localhost interface. This way, you can only reach your server over the Internet by going through the reverse proxy. By default, Pleroma listens on all interfaces. - -### `secure_cookie_flag` - -> Recommended value: `true` - -This sets the `secure` flag on Pleroma’s session cookie. This makes sure, that the cookie is only accepted over encrypted HTTPs connections. This implicitly renames the cookie from `pleroma_key` to `__Host-pleroma-key` which enforces some restrictions. (see [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Cookie_prefixes)) - -### `:http_security` - -> Recommended value: `true` - -This will send additional HTTP security headers to the clients, including: - -* `X-XSS-Protection: "1; mode=block"` -* `X-Permitted-Cross-Domain-Policies: "none"` -* `X-Frame-Options: "DENY"` -* `X-Content-Type-Options: "nosniff"` -* `X-Download-Options: "noopen"` - -A content security policy (CSP) will also be set: - -```csp -content-security-policy: - default-src 'none'; - base-uri 'self'; - frame-ancestors 'none'; - img-src 'self' data: https:; - media-src 'self' https:; - style-src 'self' 'unsafe-inline'; - font-src 'self'; - script-src 'self'; - connect-src 'self' wss://example.tld; - manifest-src 'self'; - upgrade-insecure-requests; -``` - -#### `sts` - -> Recommended value: `true` - -An additional “Strict transport security” header will be sent with the configured `sts_max_age` parameter. This tells the browser, that the domain should only be accessed over a secure HTTPs connection. - -#### `ct_max_age` - -An additional “Expect-CT” header will be sent with the configured `ct_max_age` parameter. This enforces the use of TLS certificates that are published in the certificate transparency log. (see [Expect-CT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expect-CT)) - -#### `referrer_policy` - -> Recommended value: `same-origin` - -If you click on a link, your browser’s request to the other site will include from where it is coming from. The “Referrer policy” header tells the browser how and if it should send this information. (see [Referrer policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)) - -## systemd - -A systemd unit example is provided at `installation/pleroma.service`. - -### PrivateTmp - -> Recommended value: `true` - -Use private `/tmp` and `/var/tmp` folders inside a new file system namespace, which are discarded after the process stops. - -### ProtectHome - -> Recommended value: `true` - -The `/home`, `/root`, and `/run/user` folders can not be accessed by this service anymore. If your Pleroma user has its home folder in one of the restricted places, or use one of these folders as its working directory, you have to set this to `false`. - -### ProtectSystem - -> Recommended value: `full` - -Mount `/usr`, `/boot`, and `/etc` as read-only for processes invoked by this service. - -### PrivateDevices - -> Recommended value: `true` - -Sets up a new `/dev` mount for the process and only adds API pseudo devices like `/dev/null`, `/dev/zero` or `/dev/random` but not physical devices. This may not work on devices like the Raspberry Pi, where you need to set this to `false`. - -### NoNewPrivileges - -> Recommended value: `true` - -Ensures that the service process and all its children can never gain new privileges through `execve()`. - -### CapabilityBoundingSet - -> Recommended value: `~CAP_SYS_ADMIN` - -Drops the sysadmin capability from the daemon. diff --git a/docs/config/howto_mediaproxy.md b/docs/config/howto_mediaproxy.md deleted file mode 100644 index 16c40c5db..000000000 --- a/docs/config/howto_mediaproxy.md +++ /dev/null @@ -1,34 +0,0 @@ -# How to activate mediaproxy -## Explanation - -Without the `mediaproxy` function, Pleroma doesn't store any remote content like pictures, video etc. locally. So every time you open Pleroma, the content is loaded from the source server, from where the post is coming. This can result in slowly loading content or/and increased bandwidth usage on the source server. -With the `mediaproxy` function you can use nginx to cache this content, so users can access it faster, because it's loaded from your server. - -## Activate it - -* Edit your nginx config and add the following location: -``` -location /proxy { - proxy_cache pleroma_media_cache; - proxy_cache_lock on; - proxy_pass http://localhost:4000; -} -``` -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; -``` -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. - -* Append the following to your `prod.secret.exs` or `dev.secret.exs` (depends on which mode your instance is running): -``` -config :pleroma, :media_proxy, - enabled: true, - proxy_opts: [ - redirect_on_failure: true - ] - #base_url: "https://cache.pleroma.social" -``` -If you want to use a subdomain to serve the files, uncomment `base_url`, change the url and add a comma after `true` in the previous line. - -* Restart nginx and Pleroma diff --git a/docs/config/howto_mongooseim.md b/docs/config/howto_mongooseim.md deleted file mode 100644 index a33e590a1..000000000 --- a/docs/config/howto_mongooseim.md +++ /dev/null @@ -1,10 +0,0 @@ -# Configuring MongooseIM (XMPP Server) to use Pleroma for authentication - -If you want to give your Pleroma users an XMPP (chat) account, you can configure [MongooseIM](https://github.com/esl/MongooseIM) to use your Pleroma server for user authentication, automatically giving every local user an XMPP account. - -In general, you just have to follow the configuration described at [https://mongooseim.readthedocs.io/en/latest/authentication-backends/HTTP-authentication-module/](https://mongooseim.readthedocs.io/en/latest/authentication-backends/HTTP-authentication-module/) and do these changes to your mongooseim.cfg. - -1. Set the auth_method to `{auth_method, http}`. -2. Add the http auth pool like this: `{http, global, auth, [{workers, 50}], [{server, "https://yourpleromainstance.com"}]}` - -Restart your MongooseIM server, your users should now be able to connect with their Pleroma credentials. diff --git a/docs/config/howto_proxy.md b/docs/config/howto_proxy.md deleted file mode 100644 index 10a635266..000000000 --- a/docs/config/howto_proxy.md +++ /dev/null @@ -1,12 +0,0 @@ -# How to configure upstream proxy for federation -If you want to proxify all http requests (e.g. for TOR) that pleroma makes to an upstream proxy server, edit you config file (`dev.secret.exs` or `prod.secret.exs`) and add the following: - -``` -config :pleroma, :http, - proxy_url: "127.0.0.1:8123" -``` - -The other way to do it, for example, with Tor you would most likely add something like this: -``` -config :pleroma, :http, proxy_url: {:socks5, :localhost, 9050} -``` diff --git a/docs/config/howto_set_richmedia_cache_ttl_based_on_image.md b/docs/config/howto_set_richmedia_cache_ttl_based_on_image.md deleted file mode 100644 index bfee5a9e6..000000000 --- a/docs/config/howto_set_richmedia_cache_ttl_based_on_image.md +++ /dev/null @@ -1,33 +0,0 @@ -# How to set rich media cache ttl based on image ttl -## Explanation - -Richmedia are cached without the ttl but the rich media may have image which can expire, like aws signed url. -In such cases the old image url (expired) is returned from the media cache. - -So to avoid such situation we can define a module that will set ttl based on image. -The module must adopt behaviour `Pleroma.Web.RichMedia.Parser.TTL` - -### Example - -```exs -defmodule MyModule do - @behaviour Pleroma.Web.RichMedia.Parser.TTL - - @impl Pleroma.Web.RichMedia.Parser.TTL - def ttl(data, url) do - image_url = Map.get(data, :image) - # do some parsing in the url and get the ttl of the image - # return ttl is unix time - parse_ttl_from_url(image_url) - end -end -``` - -And update the config - -```exs -config :pleroma, :rich_media, - ttl_setters: [Pleroma.Web.RichMedia.Parser.TTL.AwsSignedUrl, MyModule] -``` - -> For reference there is a parser for AWS signed URL `Pleroma.Web.RichMedia.Parser.TTL.AwsSignedUrl`, it's enabled by default. diff --git a/docs/config/howto_user_recomendation.md b/docs/config/howto_user_recomendation.md deleted file mode 100644 index c4d749d0c..000000000 --- a/docs/config/howto_user_recomendation.md +++ /dev/null @@ -1,31 +0,0 @@ -# How to activate user recommendation (Who to follow panel) -![who-to-follow-panel-small](/uploads/9de1b1300436c32461d272945f1bc23e/who-to-follow-panel-small.png) - -To show the *who to follow* panel, edit `config/prod.secret.exs` in the Pleroma backend. Following code activates the *who to follow* panel: - -```elixir -config :pleroma, :suggestions, - enabled: true, - third_party_engine: - "http://vinayaka.distsn.org/cgi-bin/vinayaka-user-match-suggestions-api.cgi?{{host}}+{{user}}", - timeout: 300_000, - limit: 40, - web: "https://vinayaka.distsn.org" - -``` - -`config/config.exs` already includes this code, but `enabled:` is `false`. - -`/api/v1/suggestions` is also provided when *who to follow* panel is enabled. - -For advanced customization, following code shows the newcomers of the fediverse at the *who to follow* panel: - -```elixir -config :pleroma, :suggestions, - enabled: true, - third_party_engine: - "http://vinayaka.distsn.org/cgi-bin/vinayaka-user-new-suggestions-api.cgi?{{host}}+{{user}}", - timeout: 60_000, - limit: 40, - web: "https://vinayaka.distsn.org/user-new.html" -``` diff --git a/docs/config/i2p.md b/docs/config/i2p.md deleted file mode 100644 index 62ced8b7a..000000000 --- a/docs/config/i2p.md +++ /dev/null @@ -1,196 +0,0 @@ -# I2P Federation and Accessability - -This guide is going to focus on the Pleroma federation aspect. The actual installation is neatly explained in the official documentation, and more likely to remain up-to-date. -It might be added to this guide if there will be a need for that. - -We're going to use I2PD for its lightweightness over the official client. -Follow the documentation according to your distro: https://i2pd.readthedocs.io/en/latest/user-guide/install/#installing - -How to run it: https://i2pd.readthedocs.io/en/latest/user-guide/run/ - -## I2P Federation - -There are 2 ways to go about this. -One using the config, and one using external software (fedproxy). The external software works better so far. - -### Using the Config - -**Warning:** So far, everytime I followed this way of federating using I2P, the rest of my federation stopped working. I'm leaving this here in case it will help with making it work. - -Assuming you're running in prod, cd to your Pleroma folder and append the following to `config/prod.secret.exs`: -``` -config :pleroma, :http, proxy_url: {:socks5, :localhost, 4447} -``` -And then run the following: -``` -su pleroma -MIX_ENV=prod mix deps.get -MIX_ENV=prod mix ecto.migrate -exit -``` -You can restart I2PD here and finish if you don't wish to make your instance viewable or accessible over I2P. -``` -systemctl stop i2pd.service --no-block -systemctl start i2pd.service -``` -*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). - -You can change the socks proxy port in `/etc/i2pd/i2pd.conf`. - -### Using Fedproxy - -Fedproxy passes through clearnet requests direct to where they are going. It doesn't force anything over Tor. - -To use [fedproxy](https://github.com/majestrate/fedproxy) you'll need to install Golang. -``` -apt install golang -``` -Use a different user than pleroma or root. Run the following to add the Gopath to your ~/.bashrc. -``` -echo "export GOPATH=/home/ren/.go" >> ~/.bashrc -``` -Restart that bash session (you can exit and log back in). -Run the following to get fedproxy. -``` -go get -u github.com/majestrate/fedproxy$ -cp $(GOPATH)/bin/fedproxy /usr/local/bin/fedproxy -``` -And then the following to start it for I2P only. -``` -fedproxy 127.0.0.1:2000 127.0.0.1:4447 -``` -If you want to also use it for Tor, add `127.0.0.1:9050` to that command. -You'll also need to modify your Pleroma config. - -Assuming you're running in prod, cd to your Pleroma folder and append the following to `config/prod.secret.exs`: -``` -config :pleroma, :http, proxy_url: {:socks5, :localhost, 2000} -``` -And then run the following: -``` -su pleroma -MIX_ENV=prod mix deps.get -MIX_ENV=prod mix ecto.migrate -exit -``` -You can restart I2PD here and finish if you don't wish to make your instance viewable or accessible over I2P. - -``` -systemctl stop i2pd.service --no-block -systemctl start i2pd.service -``` -*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). - -You can change the socks proxy port in `/etc/i2pd/i2pd.conf`. - -## I2P Instance Access - -Make your instance accessible using I2P. - -Add the following to your I2PD config `/etc/i2pd/tunnels.conf`: -``` -[pleroma] -type = http -host = 127.0.0.1 -port = 14447 -keys = pleroma.dat -``` -Restart I2PD: -``` -systemctl stop i2pd.service --no-block -systemctl start i2pd.service -``` -*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). - -Now you'll have to find your address. -To do that you can download and use I2PD tools.[^1] -Or you'll need to access your web-console on localhost:7070. -If you don't have a GUI, you'll have to SSH tunnel into it like this: -`ssh -L 7070:127.0.0.1:7070 user@ip -p port`. -Now you can access it at localhost:7070. -Go to I2P tunnels page. Look for Server tunnels and you will see an address that ends with `.b32.i2p` next to "pleroma". -This is your site's address. - -### I2P-only Instance - -If creating an I2P-only instance, open `config/prod.secret.exs` and under "config :pleroma, Pleroma.Web.Endpoint," edit "https" and "port: 443" to the following: -``` - url: [host: "i2paddress", scheme: "http", port: 80], -``` -In addition to that, replace the existing nginx config's contents with the example below. - -### Existing Instance (Clearnet Instance) - -If not an I2P-only instance, add the nginx config below to your existing config at `/etc/nginx/sites-enabled/pleroma.nginx`. - -And for both cases, disable CSP in Pleroma's config (STS is disabled by default) so you can define those yourself seperately from the clearnet (if your instance is also on the clearnet). -Copy the following into the `config/prod.secret.exs` in your Pleroma folder (/home/pleroma/pleroma/): -``` -config :pleroma, :http_security, - enabled: false -``` - -Use this as the Nginx config: -``` -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; -# The above already exists in a clearnet instance's config. -# If not, add it. - -server { - listen 127.0.0.1:14447; - server_name youri2paddress; - - # Comment to enable logs - access_log /dev/null; - error_log /dev/null; - - gzip_vary on; - gzip_proxied any; - gzip_comp_level 6; - gzip_buffers 16 8k; - gzip_http_version 1.1; - gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml; - - client_max_body_size 16m; - - location / { - - add_header X-XSS-Protection "1; mode=block"; - add_header X-Permitted-Cross-Domain-Policies none; - add_header X-Frame-Options DENY; - add_header X-Content-Type-Options nosniff; - add_header Referrer-Policy same-origin; - add_header X-Download-Options noopen; - - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - - proxy_pass http://localhost:4000; - - client_max_body_size 16m; - } - - location /proxy { - proxy_cache pleroma_media_cache; - proxy_cache_lock on; - proxy_ignore_client_abort on; - proxy_pass http://localhost:4000; - } -} -``` -reload Nginx: -``` -systemctl stop i2pd.service --no-block -systemctl start i2pd.service -``` -*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). - -You should now be able to both access your instance using I2P and federate with other I2P instances! - -[^1]: [I2PD tools](https://github.com/purplei2p/i2pd-tools) to print information about a router info file or an I2P private key, generate an I2P private key, and generate vanity addresses. - -### Possible Issues - -Will be added when encountered. diff --git a/docs/config/mrf.md b/docs/config/mrf.md deleted file mode 100644 index 45be18fc5..000000000 --- a/docs/config/mrf.md +++ /dev/null @@ -1,122 +0,0 @@ -# Message Rewrite Facility -The Message Rewrite Facility (MRF) is a subsystem that is implemented as a series of hooks that allows the administrator to rewrite or discard messages. - -Possible uses include: - -* marking incoming messages with media from a given account or instance as sensitive -* rejecting messages from a specific instance -* rejecting reports (flags) from a specific instance -* removing/unlisting messages from the public timelines -* removing media from messages -* sending only public messages to a specific instance - -The MRF provides user-configurable policies. The default policy is `NoOpPolicy`, which disables the MRF functionality. Pleroma also includes an easy to use policy called `SimplePolicy` which maps messages matching certain pre-defined criterion to actions built into the policy module. -It is possible to use multiple, active MRF policies at the same time. - -## Quarantine Instances - -You have the ability to prevent from private / followers-only messages from federating with specific instances. Which means they will only get the public or unlisted messages from your instance. - -If, for example, you're using `MIX_ENV=prod` aka using production mode, you would open your configuration file located in `config/prod.secret.exs` and edit or add the option under your `:instance` config object. Then you would specify the instance within quotes. -``` -config :pleroma, :instance, - [...] - quarantined_instances: ["instance.example", "other.example"] -``` - -## Using `SimplePolicy` - -`SimplePolicy` is capable of handling most common admin tasks. - -To use `SimplePolicy`, you must enable it. Do so by adding the following to your `:instance` config object, so that it looks like this: - -``` -config :pleroma, :instance, - [...] - rewrite_policy: Pleroma.Web.ActivityPub.MRF.SimplePolicy -``` - -Once `SimplePolicy` is enabled, you can configure various groups in the `:mrf_simple` config object. These groups are: - -* `media_removal`: Servers in this group will have media stripped from incoming messages. -* `media_nsfw`: Servers in this group will have the #nsfw tag and sensitive setting injected into incoming messages which contain media. -* `reject`: Servers in this group will have their messages rejected. -* `federated_timeline_removal`: Servers in this group will have their messages unlisted from the public timelines by flipping the `to` and `cc` fields. -* `report_removal`: Servers in this group will have their reports (flags) rejected. - -Servers should be configured as lists. - -### Example - -This example will enable `SimplePolicy`, block media from `illegalporn.biz`, mark media as NSFW from `porn.biz` and `porn.business`, reject messages from `spam.com`, remove messages from `spam.university` from the federated timeline and block reports (flags) from `whiny.whiner`: - -``` -config :pleroma, :instance, - rewrite_policy: [Pleroma.Web.ActivityPub.MRF.SimplePolicy] - -config :pleroma, :mrf_simple, - media_removal: ["illegalporn.biz"], - media_nsfw: ["porn.biz", "porn.business"], - reject: ["spam.com"], - federated_timeline_removal: ["spam.university"], - report_removal: ["whiny.whiner"] - -``` - -### Use with Care - -The effects of MRF policies can be very drastic. It is important to use this functionality carefully. Always try to talk to an admin before writing an MRF policy concerning their instance. - -## Writing your own MRF Policy - -As discussed above, the MRF system is a modular system that supports pluggable policies. This means that an admin may write a custom MRF policy in Elixir or any other language that runs on the Erlang VM, by specifying the module name in the `rewrite_policy` config setting. - -For example, here is a sample policy module which rewrites all messages to "new message content": - -```elixir -# This is a sample MRF policy which rewrites all Notes to have "new message -# content." -defmodule Site.RewritePolicy do - @behavior Pleroma.Web.ActivityPub.MRF - - # Catch messages which contain Note objects with actual data to filter. - # Capture the object as `object`, the message content as `content` and the - # message itself as `message`. - @impl true - def filter(%{"type" => Create", "object" => {"type" => "Note", "content" => content} = object} = message) - when is_binary(content) do - # Subject / CW is stored as summary instead of `name` like other AS2 objects - # because of Mastodon doing it that way. - summary = object["summary"] - - # Message edits go here. - content = "new message content" - - # Assemble the mutated object. - object = - object - |> Map.put("content", content) - |> Map.put("summary", summary) - - # Assemble the mutated message. - message = Map.put(message, "object", object) - {:ok, message} - end - - # Let all other messages through without modifying them. - @impl true - def filter(message), do: {:ok, message} -end -``` - -If you save this file as `lib/site/mrf/rewrite_policy.ex`, it will be included when you next rebuild Pleroma. You can enable it in the configuration like so: - -``` -config :pleroma, :instance, - rewrite_policy: [ - Pleroma.Web.ActivityPub.MRF.SimplePolicy, - Site.RewritePolicy - ] -``` - -Please note that the Pleroma developers consider custom MRF policy modules to fall under the purview of the AGPL. As such, you are obligated to release the sources to your custom MRF policy modules upon request. diff --git a/docs/config/onion_federation.md b/docs/config/onion_federation.md deleted file mode 100644 index 99f104995..000000000 --- a/docs/config/onion_federation.md +++ /dev/null @@ -1,159 +0,0 @@ -# Easy Onion Federation (Tor) -Tor can free people from the necessity of a domain, in addition to helping protect their privacy. As Pleroma's goal is to empower the people and let as many as possible host an instance with as little resources as possible, the ability to host an instance with a small, cheap computer like a RaspberryPi along with Tor, would be a great way to achieve that. -In addition, federating with such instances will also help furthering that goal. - -This is a guide to show you how it can be easily done. - -This guide assumes you already got Pleroma working, and that it's running on the default port 4000. -Currently only has an Nginx example. - -To install Tor on Debian / Ubuntu: -``` -apt -yq install tor -``` -If using an old server version (older than Debian Stretch or Ubuntu 18.04), install from backports or PPA. -I recommend using a newer server version instead. - -To have the newest, V3 onion addresses (which I recommend) in Debian, install Tor from backports. -If you do not have backports, uncomment the stretch-backports links at the end of `/etc/apt/sources.list`. -Then install: -``` -apt update -apt -t stretch-backports -yq install tor -``` -**WARNING:** Onion instances not using a Tor version supporting V3 addresses will not be able to federate with you. - -Create the hidden service for your Pleroma instance in `/etc/tor/torrc`: -``` -HiddenServiceDir /var/lib/tor/pleroma_hidden_service/ -HiddenServicePort 80 127.0.0.1:8099 -HiddenServiceVersion 3 # Remove if Tor version is below 0.3 ( tor --version ) -``` -Restart Tor to generate an adress: -``` -systemctl restart tor@default.service -``` -Get the address: -``` -cat /var/lib/tor/pleroma_hidden_service/hostname -``` - -# Federation - -Next, edit your Pleroma config. -If running in prod, cd to your Pleroma directory, edit `config/prod.secret.exs` -and append this line: -``` -config :pleroma, :http, proxy_url: {:socks5, :localhost, 9050} -``` -In your Pleroma directory, assuming you're running prod, -run the following: -``` -su pleroma -MIX_ENV=prod mix deps.get -MIX_ENV=prod mix ecto.migrate -exit -``` -restart Pleroma (if using systemd): -``` -systemctl restart pleroma -``` - -# Tor Instance Access - -Make your instance accessible using Tor. - -## Tor-only Instance -If creating a Tor-only instance, open `config/prod.secret.exs` and under "config :pleroma, Pleroma.Web.Endpoint," edit "https" and "port: 443" to the following: -``` - url: [host: "onionaddress", scheme: "http", port: 80], -``` -In addition to that, replace the existing nginx config's contents with the example below. - -## Existing Instance (Clearnet Instance) -If not a Tor-only instance, -add the nginx config below to your existing config at `/etc/nginx/sites-enabled/pleroma.nginx`. - ---- -For both cases, disable CSP in Pleroma's config (STS is disabled by default) so you can define those yourself seperately from the clearnet (if your instance is also on the clearnet). -Copy the following into the `config/prod.secret.exs` in your Pleroma folder (/home/pleroma/pleroma/): -``` -config :pleroma, :http_security, - enabled: false -``` - -Use this as the Nginx config: -``` -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; -# The above already exists in a clearnet instance's config. -# If not, add it. - -server { - listen 127.0.0.1:8099; - server_name youronionaddress; - - # Comment to enable logs - access_log /dev/null; - error_log /dev/null; - - gzip_vary on; - gzip_proxied any; - gzip_comp_level 6; - gzip_buffers 16 8k; - gzip_http_version 1.1; - gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml; - - client_max_body_size 16m; - - location / { - - add_header X-XSS-Protection "1; mode=block"; - add_header X-Permitted-Cross-Domain-Policies none; - add_header X-Frame-Options DENY; - add_header X-Content-Type-Options nosniff; - add_header Referrer-Policy same-origin; - add_header X-Download-Options noopen; - - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - - proxy_pass http://localhost:4000; - - client_max_body_size 16m; - } - - location /proxy { - proxy_cache pleroma_media_cache; - proxy_cache_lock on; - proxy_ignore_client_abort on; - proxy_pass http://localhost:4000; - } -} -``` -reload Nginx: -``` -systemctl reload nginx -``` - -You should now be able to both access your instance using Tor and federate with other Tor instances! - ---- - -### Possible Issues - -* In Debian, make sure your hidden service folder `/var/lib/tor/pleroma_hidden_service/` and its contents, has debian-tor as both owner and group by using -``` -ls -la /var/lib/tor/ -``` -If it's not, run: -``` -chown -R debian-tor:debian-tor /var/lib/tor/pleroma_hidden_service/ -``` -* Make sure *only* the owner has *only* read and write permissions. -If not, run: -``` -chmod -R 600 /var/lib/tor/pleroma_hidden_service/ -``` -* If you have trouble logging in to the Mastodon Frontend when using Tor, use the Tor Browser Bundle. diff --git a/docs/config/small_customizations.md b/docs/config/small_customizations.md deleted file mode 100644 index f91657a4c..000000000 --- a/docs/config/small_customizations.md +++ /dev/null @@ -1,12 +0,0 @@ -# Small customizations - -See also static_dir.md for visual settings. - -## Theme - -All users of your instance will be able to change the theme they use by going to the settings (the cog in the top-right hand corner). However, if you wish to change the default theme, you can do so by editing `theme` in `config/dev.secret.exs` accordingly. - -## Message Visibility - -To enable message visibility options when posting like in the Mastodon frontend, set -`scope_options_enabled` to `true` in `config/dev.secret.exs`. diff --git a/docs/config/static_dir.md b/docs/config/static_dir.md deleted file mode 100644 index 5fb38c3de..000000000 --- a/docs/config/static_dir.md +++ /dev/null @@ -1,69 +0,0 @@ -# Static Directory - -Static frontend files are shipped in `priv/static/` and tracked by version control in this repository. If you want to overwrite or update these without the possibility of merge conflicts, you can write your custom versions to `instance/static/`. - -``` -config :pleroma, :instance, - static_dir: "instance/static/", -``` - -For example, edit `instance/static/instance/panel.html` . - -Alternatively, you can overwrite this value in your configuration to use a different static instance directory. - -This document is written assuming `instance/static/`. - -Or, if you want to manage your custom file in git repository, basically remove the `instance/` entry from `.gitignore`. - -## robots.txt - -By default, the `robots.txt` that ships in `priv/static/` is permissive. It allows well-behaved search engines to index all of your instance's URIs. - -If you want to generate a restrictive `robots.txt`, you can run the following mix task. The generated `robots.txt` will be written in your instance static directory. - -``` -mix pleroma.robots_txt disallow_all -``` - -## Thumbnail - -Put on `instance/static/instance/thumbnail.jpeg` with your selfie or other neat picture. It will appear in [Pleroma Instances](http://distsn.org/pleroma-instances.html). - -## Instance-specific panel - -![instance-specific panel demo](/uploads/296b19ec806b130e0b49b16bfe29ce8a/image.png) - -Create and Edit your file on `instance/static/instance/panel.html`. - -## Background - -You can change the background of your Pleroma instance by uploading it to `instance/static/`, and then changing `background` in `config/prod.secret.exs` accordingly. - -If you put `instance/static/images/background.jpg` - -``` -config :pleroma, :frontend_configurations, - pleroma_fe: %{ - background: "/images/background.jpg" - } -``` - -## Logo - -![logo modification demo](/uploads/c70b14de60fa74245e7f0dcfa695ebff/image.png) - -If you want to give a brand to your instance, You can change the logo of your instance by uploading it to `instance/static/`. - -Alternatively, you can specify the path with config. -If you put `instance/static/static/mylogo-file.png` - -``` -config :pleroma, :frontend_configurations, - pleroma_fe: %{ - logo: "/static/mylogo-file.png" - } -``` - -## Terms of Service - -Terms of Service will be shown to all users on the registration page. It's the best place where to write down the rules for your instance. You can modify the rules by changing `instance/static/static/terms-of-service.html`. diff --git a/docs/configuration/General-tips-for-customizing-Pleroma-FE.md b/docs/configuration/General-tips-for-customizing-Pleroma-FE.md new file mode 100644 index 000000000..15c4882dd --- /dev/null +++ b/docs/configuration/General-tips-for-customizing-Pleroma-FE.md @@ -0,0 +1,17 @@ +# General tips for customizing Pleroma FE +There are some configuration scripts for Pleroma BE and FE: + +1. `config/prod.secret.exs` +1. `config/config.exs` +1. `priv/static/static/config.json` + +The `prod.secret.exs` affects first. `config.exs` is for fallback or default. `config.json` is for GNU-social-BE-Pleroma-FE instances. + +Usually all you have to do is: + +1. Copy the section in the `config/config.exs` which you want to activate. +1. Paste into `config/prod.secret.exs`. +1. Edit `config/prod.secret.exs`. +1. Restart the Pleroma daemon. + +`prod.secret.exs` is for the `MIX_ENV=prod` environment. `dev.secret.exs` is for the `MIX_ENV=dev` environment respectively. diff --git a/docs/configuration/config.md b/docs/configuration/config.md new file mode 100644 index 000000000..262d15bba --- /dev/null +++ b/docs/configuration/config.md @@ -0,0 +1,773 @@ +# Configuration + +This file describe the configuration, it is recommended to edit the relevant *.secret.exs file instead of the others founds in the ``config`` directory. +If you run Pleroma with ``MIX_ENV=prod`` the file is ``prod.secret.exs``, otherwise it is ``dev.secret.exs``. + +## Pleroma.Upload +* `uploader`: Select which `Pleroma.Uploaders` to use +* `filters`: List of `Pleroma.Upload.Filter` to use. +* `link_name`: When enabled Pleroma will add a `name` parameter to the url of the upload, for example `https://instance.tld/media/corndog.png?name=corndog.png`. This is needed to provide the correct filename in Content-Disposition headers when using filters like `Pleroma.Upload.Filter.Dedupe` +* `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host. +* `proxy_remote`: If you're using a remote uploader, Pleroma will proxy media requests instead of redirecting to it. +* `proxy_opts`: Proxy options, see `Pleroma.ReverseProxy` documentation. + +Note: `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`. + +## Pleroma.Uploaders.Local +* `uploads`: Which directory to store the user-uploads in, relative to pleroma’s working directory + +## Pleroma.Uploaders.S3 +* `bucket`: S3 bucket name +* `bucket_namespace`: S3 bucket namespace +* `public_endpoint`: S3 endpoint that the user finally accesses(ex. "https://s3.dualstack.ap-northeast-1.amazonaws.com") +* `truncated_namespace`: If you use S3 compatible service such as Digital Ocean Spaces or CDN, set folder name or "" etc. +For example, when using CDN to S3 virtual host format, set "". +At this time, write CNAME to CDN in public_endpoint. +* `streaming_enabled`: Enable streaming uploads, when enabled the file will be sent to the server in chunks as it's being read. This may be unsupported by some providers, try disabling this if you have upload problems. + +## Pleroma.Upload.Filter.Mogrify + +* `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"implode", "1"}]`. + +## Pleroma.Upload.Filter.Dedupe + +No specific configuration. + +## Pleroma.Upload.Filter.AnonymizeFilename + +This filter replaces the filename (not the path) of an upload. For complete obfuscation, add +`Pleroma.Upload.Filter.Dedupe` before AnonymizeFilename. + +* `text`: Text to replace filenames in links. If empty, `{random}.extension` will be used. You can get the original filename extension by using `{extension}`, for example `custom-file-name.{extension}`. + +## 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. +* `enabled`: Allows enable/disable send emails. Default: `false`. + +An example for Sendgrid adapter: + +```elixir +config :pleroma, Pleroma.Emails.Mailer, + adapter: Swoosh.Adapters.Sendgrid, + api_key: "YOUR_API_KEY" +``` + +An example for SMTP adapter: + +```elixir +config :pleroma, Pleroma.Emails.Mailer, + adapter: Swoosh.Adapters.SMTP, + relay: "smtp.gmail.com", + username: "YOUR_USERNAME@gmail.com", + password: "YOUR_SMTP_PASSWORD", + port: 465, + ssl: true, + tls: :always, + auth: :always +``` + +## :uri_schemes +* `valid_schemes`: List of the scheme part that is considered valid to be an URL + +## :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. +* `upload_limit`: File size limit of uploads (except for avatar, background, banner) +* `avatar_upload_limit`: File size limit of user’s profile avatars +* `background_upload_limit`: File size limit of user’s profile backgrounds +* `banner_upload_limit`: File size limit of user’s profile banners +* `poll_limits`: A map with poll limits for **local** polls + * `max_options`: Maximum number of options + * `max_option_chars`: Maximum number of characters per option + * `min_expiration`: Minimum expiration time (in seconds) + * `max_expiration`: Maximum expiration time (in seconds) +* `registrations_open`: Enable registrations for anyone, invitations can be enabled when false. +* `invites_enabled`: Enable user invitations for admins (depends on `registrations_open: false`). +* `account_activation_required`: Require users to confirm their emails before signing in. +* `federating`: Enable federation with other instances +* `federation_incoming_replies_max_depth`: Max. depth of reply-to activities fetching on incoming federation, to prevent out-of-memory situations while fetching very long threads. If set to `nil`, threads of any depth will be fetched. Lower this value if you experience out-of-memory crashes. +* `federation_reachability_timeout_days`: Timeout (in days) of each external federation target being unreachable prior to pausing federating to it. +* `allow_relay`: Enable Pleroma’s Relay, which makes it possible to follow a whole instance +* `rewrite_policy`: Message Rewrite Policy, either one or a list. Here are the ones available by default: + * `Pleroma.Web.ActivityPub.MRF.NoOpPolicy`: Doesn’t modify activities (default) + * `Pleroma.Web.ActivityPub.MRF.DropPolicy`: Drops all activities. It generally doesn’t makes sense to use in production + * `Pleroma.Web.ActivityPub.MRF.SimplePolicy`: Restrict the visibility of activities from certains instances (See ``:mrf_simple`` section) + * `Pleroma.Web.ActivityPub.MRF.TagPolicy`: Applies policies to individual users based on tags, which can be set using pleroma-fe/admin-fe/any other app that supports Pleroma Admin API. For example it allows marking posts from individual users nsfw (sensitive) + * `Pleroma.Web.ActivityPub.MRF.SubchainPolicy`: Selectively runs other MRF policies when messages match (see ``:mrf_subchain`` section) + * `Pleroma.Web.ActivityPub.MRF.RejectNonPublic`: Drops posts with non-public visibility settings (See ``:mrf_rejectnonpublic`` section) + * `Pleroma.Web.ActivityPub.MRF.EnsureRePrepended`: Rewrites posts to ensure that replies to posts with subjects do not have an identical subject and instead begin with re:. + * `Pleroma.Web.ActivityPub.MRF.AntiLinkSpamPolicy`: Rejects posts from likely spambots by rejecting posts from new users that contain links. + * `Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy`: Crawls attachments using their MediaProxy URLs so that the MediaProxy cache is primed. + * `Pleroma.Web.ActivityPub.MRF.MentionPolicy`: Drops posts mentioning configurable users. (see `:mrf_mention` section) + * `Pleroma.Web.ActivityPub.MRF.VocabularyPolicy`: Restricts activities to a configured set of vocabulary. (see `:mrf_vocabulary` section) +* `public`: Makes the client API in authentificated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network. +* `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) +* `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). +* `mrf_transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. +* `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: + * "email": Copy and preprend re:, as in email. + * "masto": Copy verbatim, as in Mastodon. + * "noop": Don't copy the subject. +* `always_show_subject_input`: When set to false, auto-hide the subject field when it's empty. +* `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with + older software for theses nicknames. +* `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature. +* `autofollowed_nicknames`: Set to nicknames of (local) users that every new user should automatically follow. +* `no_attachment_links`: Set to true to disable automatically adding attachment link text to statuses +* `welcome_message`: A message that will be send to a newly registered users as a direct message. +* `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``. +* `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database. +* `user_bio_length`: A user bio maximum length (default: `5000`) +* `user_name_length`: A user name maximum length (default: `100`) +* `skip_thread_containment`: Skip filter out broken threads. The default is `false`. +* `limit_to_local_content`: Limit unauthenticated users to search for local statutes and users only. Possible values: `:unauthenticated`, `:all` and `false`. The default is `:unauthenticated`. +* `dynamic_configuration`: Allow transferring configuration to DB with the subsequent customization from Admin api. +* `max_account_fields`: The maximum number of custom fields in the user profile (default: `10`) +* `max_remote_account_fields`: The maximum number of custom fields in the remote user profile (default: `20`) +* `account_field_name_length`: An account field name maximum length (default: `512`) +* `account_field_value_length`: An account field value maximum length (default: `2048`) +* `external_user_synchronization`: Enabling following/followers counters synchronization for external users. + + + +## :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}] + +config :logger, :ex_syslogger, + level: :warn +``` + +Another example, keeping console output and adding the pid to syslog output: +```elixir +config :logger, + backends: [:console, {ExSyslogger, :ex_syslogger}] + +config :logger, :ex_syslogger, + level: :warn, + option: [:pid, :ndelay] +``` + +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 + +config :logger, :ex_syslogger, + level: :info, + ident: "pleroma", + format: "$metadata[$level] $message" + +config :quack, + level: :warn, + meta: [:all], + webhook_url: "https://hooks.slack.com/services/YOUR-API-KEY-HERE" +``` + +See the [Quack Github](https://github.com/azohra/quack) for more details + +## :frontend_configurations + +This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. + +Frontends can access these settings at `/api/pleroma/frontend_configurations` + +To add your own configuration for PleromaFE, use it like this: + +```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. + +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`](#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. + +* `theme`: Which theme to use, they are defined in ``styles.json`` +* `logo`: URL of the logo, defaults to Pleroma’s logo +* `logo_mask`: Whether to use only the logo's shape as a mask (true) or as a regular image (false) +* `logo_margin`: What margin to use around the logo +* `background`: URL of the background, unless viewing a user profile with a background that is set +* `redirect_root_no_login`: relative URL which indicates where to redirect when a user isn’t logged in. +* `redirect_root_login`: relative URL which indicates where to redirect when a user is logged in. +* `show_instance_panel`: Whenether to show the instance’s specific panel. +* `scope_options_enabled`: Enable setting an notice visibility and subject/CW when posting +* `formatting_options_enabled`: Enable setting a formatting different than plain-text (ie. HTML, Markdown) when posting, relates to ``:instance, allowed_post_formats`` +* `collapse_message_with_subjects`: When a message has a subject(aka Content Warning), collapse it by default +* `hide_post_stats`: Hide notices statistics(repeats, favorites, …) +* `hide_user_stats`: Hide profile statistics(posts, posts per day, followers, followings, …) + +## :assets + +This section configures assets to be used with various frontends. Currently the only option +relates to mascots on the mastodon frontend + +* `mascots`: KeywordList of mascots, each element __MUST__ contain both a `url` and a + `mime_type` key. +* `default_mascot`: An element from `mascots` - This will be used as the default mascot + on MastoFE (default: `:pleroma_fox_tan`) + +## :mrf_simple +* `media_removal`: List of instances to remove medias from +* `media_nsfw`: List of instances to put medias as NSFW(sensitive) from +* `federated_timeline_removal`: List of instances to remove from Federated (aka The Whole Known Network) Timeline +* `reject`: List of instances to reject any activities from +* `accept`: List of instances to accept any activities from +* `report_removal`: List of instances to reject reports from +* `avatar_removal`: List of instances to strip avatars from +* `banner_removal`: List of instances to strip banners from + +## :mrf_subchain +This policy processes messages through an alternate pipeline when a given message matches certain criteria. +All criteria are configured as a map of regular expressions to lists of policy modules. + +* `match_actor`: Matches a series of regular expressions against the actor field. + +Example: + +``` +config :pleroma, :mrf_subchain, + match_actor: %{ + ~r/https:\/\/example.com/s => [Pleroma.Web.ActivityPub.MRF.DropPolicy] + } +``` + +## :mrf_rejectnonpublic +* `allow_followersonly`: whether to allow followers-only posts +* `allow_direct`: whether to allow direct messages + +## :mrf_hellthread +* `delist_threshold`: Number of mentioned users after which the message gets delisted (the message can still be seen, but it will not show up in public timelines and mentioned users won't get notifications about it). Set to 0 to disable. +* `reject_threshold`: Number of mentioned users after which the messaged gets rejected. Set to 0 to disable. + +## :mrf_keyword +* `reject`: A list of patterns which result in message being rejected, each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) +* `federated_timeline_removal`: A list of patterns which result in message being removed from federated timelines (a.k.a unlisted), each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) +* `replace`: A list of tuples containing `{pattern, replacement}`, `pattern` can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) + +## :mrf_mention +* `actors`: A list of actors, for which to drop any posts mentioning. + +## :mrf_vocabulary +* `accept`: A list of ActivityStreams terms to accept. If empty, all supported messages are accepted. +* `reject`: A list of ActivityStreams terms to reject. If empty, no messages are rejected. + +## :media_proxy +* `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 +* `ip`: IP address to bind to +* `port`: Port to bind to +* `dstport`: Port advertised in urls (optional, defaults to `port`) + +## Pleroma.Web.Endpoint +`Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here +* `http` - a list containing http protocol configuration, all configuration options can be viewed [here](https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html#module-options), only common options are listed here. For deployment using docker, you need to set this to `[ip: {0,0,0,0}, port: 4000]` to make pleroma accessible from other containers (such as your nginx server). + - `ip` - a tuple consisting of 4 integers + - `port` +* `url` - a list containing the configuration for generating urls, accepts + - `host` - the host without the scheme and a post (e.g `example.com`, not `https://example.com:2020`) + - `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 + +Example: +```elixir +config :pleroma, Pleroma.Web.Endpoint, + url: [host: "example.com", port: 2020, scheme: "https"], + http: [ + # start copied from config.exs + dispatch: [ + {:_, + [ + {"/api/v1/streaming", Pleroma.Web.MastodonAPI.WebsocketHandler, []}, + {"/websocket", Phoenix.Endpoint.CowboyWebSocket, + {Phoenix.Transports.WebSocket, + {Pleroma.Web.Endpoint, Pleroma.Web.UserSocket, websocket_config}}}, + {:_, Phoenix.Endpoint.Cowboy2Handler, {Pleroma.Web.Endpoint, []}} + ]} + # end copied from config.exs + ], + port: 8080, + ip: {127, 0, 0, 1} + ] +``` + +This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls starting with `https://example.com:2020` + +## :activitypub +* ``unfollow_blocked``: Whether blocks result in people getting unfollowed +* ``outgoing_blocks``: Whether to federate blocks to other instances +* ``deny_follow_blocked``: Whether to disallow following an account that has blocked the user in question +* ``sign_object_fetches``: Sign object fetches with HTTP signatures + +## :http_security +* ``enabled``: Whether the managed content security policy is enabled +* ``sts``: Whether to additionally send a `Strict-Transport-Security` header +* ``sts_max_age``: The maximum age for the `Strict-Transport-Security` header if sent +* ``ct_max_age``: The maximum age for the `Expect-CT` header if sent +* ``referrer_policy``: The referrer policy to use, either `"same-origin"` or `"no-referrer"` +* ``report_uri``: Adds the specified url to `report-uri` and `report-to` group in CSP header. + +## :mrf_user_allowlist + +The keys in this section are the domain names that the policy should apply to. +Each key should be assigned a list of users that should be allowed through by +their ActivityPub ID. + +An example: + +```elixir +config :pleroma, :mrf_user_allowlist, + "example.org": ["https://example.org/users/admin"] +``` + +## :web_push_encryption, :vapid_details + +Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it. + +* ``subject``: a mailto link for the administrative contact. It’s best if this email is not a personal email address, but rather a group email so that if a person leaves an organization, is unavailable for an extended period, or otherwise can’t respond, someone else on the list can. +* ``public_key``: VAPID public key +* ``private_key``: VAPID private key + +## Pleroma.Captcha +* `enabled`: Whether the captcha should be shown on registration +* `method`: The method/service to use for captcha +* `seconds_valid`: The time in seconds for which the captcha is valid + +### Pleroma.Captcha.Kocaptcha +Kocaptcha is a very simple captcha service with a single API endpoint, +the source code is here: https://github.com/koto-bank/kocaptcha. The default endpoint +`https://captcha.kotobank.ch` is hosted by the developer. + +* `endpoint`: the kocaptcha endpoint to use + +## :admin_token + +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: + +```elixir +config :pleroma, :admin_token, "somerandomtoken" +``` + +You can then do + +```sh +curl "http://localhost:4000/api/pleroma/admin/invite_token?admin_token=somerandomtoken" +``` + +## Oban + +[Oban](https://github.com/sorentwo/oban) asynchronous job processor configuration. + +Configuration options described in [Oban readme](https://github.com/sorentwo/oban#usage): +* `repo` - app's Ecto repo (`Pleroma.Repo`) +* `verbose` - logs verbosity +* `prune` - non-retryable jobs [pruning settings](https://github.com/sorentwo/oban#pruning) (`:disabled` / `{:maxlen, value}` / `{:maxage, value}`) +* `queues` - job queues (see below) + +Pleroma has the following queues: + +* `activity_expiration` - Activity expiration +* `federator_outgoing` - Outgoing federation +* `federator_incoming` - Incoming federation +* `mailer` - Email sender, see [`Pleroma.Emails.Mailer`](#pleromaemailsmailer) +* `transmogrifier` - Transmogrifier +* `web_push` - Web push notifications +* `scheduled_activities` - Scheduled activities, see [`Pleroma.ScheduledActivity`](#pleromascheduledactivity) + +Example: + +```elixir +config :pleroma, Oban, + repo: Pleroma.Repo, + verbose: false, + prune: {:maxlen, 1500}, + queues: [ + federator_incoming: 50, + federator_outgoing: 50 + ] +``` + +This config contains two queues: `federator_incoming` and `federator_outgoing`. Both have the number of max concurrent jobs set to `50`. + +### Migrating `pleroma_job_queue` settings + +`config :pleroma_job_queue, :queues` is replaced by `config :pleroma, Oban, :queues` and uses the same format (keys are queues' names, values are max concurrent jobs numbers). + +### Note on running with PostgreSQL in silent mode + +If you are running PostgreSQL in [`silent_mode`](https://postgresqlco.nf/en/doc/param/silent_mode?version=9.1), it's advised to set [`log_destination`](https://postgresqlco.nf/en/doc/param/log_destination?version=9.1) to `syslog`, +otherwise `postmaster.log` file may grow because of "you don't own a lock of type ShareLock" warnings (see https://github.com/sorentwo/oban/issues/52). + +## :workers + +Includes custom worker options not interpretable directly by `Oban`. + +* `retries` — keyword lists where keys are `Oban` queues (see above) and values are numbers of max attempts for failed jobs. + +Example: + +```elixir +config :pleroma, :workers, + retries: [ + federator_incoming: 5, + federator_outgoing: 5 + ] +``` + +### Migrating `Pleroma.Web.Federator.RetryQueue` settings + +* `max_retries` is replaced with `config :pleroma, :workers, retries: [federator_outgoing: 5]` +* `enabled: false` corresponds to `config :pleroma, :workers, retries: [federator_outgoing: 1]` +* deprecated options: `max_jobs`, `initial_timeout` + +## Pleroma.Web.Metadata +* `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 `
` as `` +* `unfurl_nsfw`: If set to `true` nsfw attachments will be shown in previews + +## :rich_media +* `enabled`: if enabled the instance will parse metadata from attached links to generate link previews +* `ignore_hosts`: list of hosts which will be ignored by the metadata parser. For example `["accounts.google.com", "xss.website"]`, defaults to `[]`. +* `ignore_tld`: list TLDs (top-level domains) which will ignore for parse metadata. default is ["local", "localdomain", "lan"] +* `parsers`: list of Rich Media parsers + +## :fetch_initial_posts +* `enabled`: if enabled, when a new user is federated with, fetch some of their latest posts +* `pages`: the amount of pages to fetch + +## :hackney_pools + +Advanced. Tweaks Hackney (http client) connections pools. + +There's three pools used: + +* `:federation` for the federation jobs. + You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs. +* `:media` for rich media, media proxy +* `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`) + +For each pool, the options are: + +* `max_connections` - how much connections a pool can hold +* `timeout` - retention duration for connections + +## :auto_linker + +Configuration for the `auto_linker` library: + +* `class: "auto-linker"` - specify the class to be added to the generated link. false to clear +* `rel: "noopener noreferrer"` - override the rel attribute. false to clear +* `new_window: true` - set to false to remove `target='_blank'` attribute +* `scheme: false` - Set to true to link urls with schema `http://google.com` +* `truncate: false` - Set to a number to truncate urls longer then the number. Truncated urls will end in `..` +* `strip_prefix: true` - Strip the scheme prefix +* `extra: false` - link urls with rarely used schemes (magnet, ipfs, irc, etc.) + +Example: + +```elixir +config :auto_linker, + opts: [ + scheme: true, + extra: true, + class: false, + strip_prefix: false, + new_window: false, + rel: "ugc" + ] +``` + +## Pleroma.Scheduler + +Configuration for [Quantum](https://github.com/quantum-elixir/quantum-core) jobs scheduler. + +See [Quantum readme](https://github.com/quantum-elixir/quantum-core#usage) for the list of supported options. + +Example: + +```elixir +config :pleroma, Pleroma.Scheduler, + global: true, + overlap: true, + timezone: :utc, + jobs: [{"0 */6 * * * *", {Pleroma.Web.Websub, :refresh_subscriptions, []}}] +``` + +The above example defines a single job which invokes `Pleroma.Web.Websub.refresh_subscriptions()` every 6 hours ("0 */6 * * * *", [crontab format](https://en.wikipedia.org/wiki/Cron)). + +## Pleroma.ScheduledActivity + +* `daily_user_limit`: the number of scheduled activities a user is allowed to create in a single day (Default: `25`) +* `total_user_limit`: the number of scheduled activities a user is allowed to create in total (Default: `300`) +* `enabled`: whether scheduled activities are sent to the job queue to be executed + +## Pleroma.ActivityExpiration + +# `enabled`: whether expired activities will be sent to the job queue to be deleted + +## Pleroma.Web.Auth.Authenticator + +* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator +* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication + +## :ldap + +Use LDAP for user authentication. When a user logs in to the Pleroma +instance, the name and password will be verified by trying to authenticate +(bind) to an LDAP server. If a user exists in the LDAP directory but there +is no account with the same name yet on the Pleroma instance then a new +Pleroma account will be created with the same name as the LDAP user name. + +* `enabled`: enables LDAP authentication +* `host`: LDAP server hostname +* `port`: LDAP port, e.g. 389 or 636 +* `ssl`: true to use SSL, usually implies the port 636 +* `sslopts`: additional SSL options +* `tls`: true to start TLS, usually implies the port 389 +* `tlsopts`: additional TLS options +* `base`: LDAP base, e.g. "dc=example,dc=com" +* `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base" + +## BBS / SSH access + +To enable simple command line interface accessible over ssh, add a setting like this to your configuration file: + +```exs +app_dir = File.cwd! +priv_dir = Path.join([app_dir, "priv/ssh_keys"]) + +config :esshd, + enabled: true, + priv_dir: priv_dir, + handler: "Pleroma.BBS.Handler", + port: 10_022, + password_authenticator: "Pleroma.BBS.Authenticator" +``` + +Feel free to adjust the priv_dir and port number. Then you will have to create the key for the keys (in the example `priv/ssh_keys`) and create the host keys with `ssh-keygen -m PEM -N "" -b 2048 -t rsa -f ssh_host_rsa_key`. After restarting, you should be able to connect to your Pleroma instance with `ssh username@server -p $PORT` + +## :auth + +* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator +* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication + +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`. +* `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. Each entry in this space-delimited string should be of format `` or `:` (e.g. `twitter` or `keycloak:ueberauth_keycloak_strategy` in case dependency is named differently than `ueberauth_`). + +## :email_notifications + +Email notifications settings. + + - digest - emails of "what you've missed" for users who have been + inactive for a while. + - active: globally enable or disable digest emails + - schedule: When to send digest email, in [crontab format](https://en.wikipedia.org/wiki/Cron). + "0 0 * * 0" is the default, meaning "once a week at midnight on Sunday morning" + - interval: Minimum interval between digest emails to one user + - inactivity_threshold: Minimum user inactivity threshold + +## Pleroma.Emails.UserEmail + +- `:logo` - a path to a custom logo. Set it to `nil` to use the default Pleroma logo. +- `:styling` - a map with color settings for email templates. + +## OAuth consumer mode + +OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.). +Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies). + +Note: each strategy is shipped as a separate dependency; in order to get the strategies, run `OAUTH_CONSUMER_STRATEGIES="..." mix deps.get`, +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: 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:///oauth/twitter/callback + +* For Facebook, [register an app](https://developers.facebook.com/apps), configure callback URL to https:///oauth/facebook/callback, enable Facebook Login service at https://developers.facebook.com/apps//fb-login/settings/ + +* For Google, [register an app](https://console.developers.google.com), configure callback URL to https:///oauth/google/callback + +* For Microsoft, [register an app](https://portal.azure.com), configure callback URL to https:///oauth/microsoft/callback + +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"), + consumer_secret: System.get_env("TWITTER_CONSUMER_SECRET") + +# Facebook +config :ueberauth, Ueberauth.Strategy.Facebook.OAuth, + client_id: System.get_env("FACEBOOK_APP_ID"), + client_secret: System.get_env("FACEBOOK_APP_SECRET"), + redirect_uri: System.get_env("FACEBOOK_REDIRECT_URI") + +# Google +config :ueberauth, Ueberauth.Strategy.Google.OAuth, + client_id: System.get_env("GOOGLE_CLIENT_ID"), + client_secret: System.get_env("GOOGLE_CLIENT_SECRET"), + redirect_uri: System.get_env("GOOGLE_REDIRECT_URI") + +# Microsoft +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: []]} + ] + +# Keycloak +# Note: make sure to add `keycloak:ueberauth_keycloak_strategy` entry to `OAUTH_CONSUMER_STRATEGIES` environment variable +keycloak_url = "https://publicly-reachable-keycloak-instance.org:8080" + +config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth, + client_id: System.get_env("KEYCLOAK_CLIENT_ID"), + client_secret: System.get_env("KEYCLOAK_CLIENT_SECRET"), + site: keycloak_url, + authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth", + token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token", + userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo", + token_method: :post + +config :ueberauth, Ueberauth, + providers: [ + keycloak: {Ueberauth.Strategy.Keycloak, [uid_field: :email]} + ] +``` + +## OAuth 2.0 provider - :oauth2 + +Configure OAuth 2 provider capabilities: + +* `token_expires_in` - The lifetime in seconds of the access token. +* `issue_new_refresh_token` - Keeps old refresh token or generate new refresh token when to obtain an access token. +* `clean_expired_tokens` - Enable a background job to clean expired oauth tokens. Defaults to `false`. +* `clean_expired_tokens_interval` - Interval to run the job to clean expired tokens. Defaults to `86_400_000` (24 hours). + +## :emoji +* `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]` +* `pack_extensions`: A list of file extensions for emojis, when no emoji.txt for a pack is present. Example `[".png", ".gif"]` +* `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). +* `shared_pack_cache_seconds_per_file`: When an emoji pack is shared, the archive is created and cached in + memory for this amount of seconds multiplied by the number of files. + +## Database options + +### RUM indexing for full text search +* `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. + +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. + +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/` + +This will probably take a long time. + +## :rate_limit + +This is an advanced feature and disabled by default. + +If your instance is behind a reverse proxy you must enable and configure [`Pleroma.Plugs.RemoteIp`](#pleroma-plugs-remoteip). + +A keyword list of rate limiters where a key is a limiter name and value is the limiter configuration. The basic configuration is a tuple where: + +* The first element: `scale` (Integer). The time scale in milliseconds. +* The second element: `limit` (Integer). How many requests to limit in the time scale provided. + +It is also possible to have different limits for unauthenticated and authenticated users: the keyword value must be a list of two tuples where the first one is a config for unauthenticated users and the second one is for authenticated. + +See [`Pleroma.Plugs.RateLimiter`](Pleroma.Plugs.RateLimiter.html) documentation for examples. + +Supported rate limiters: + +* `:search` for the search requests (account & status search etc.) +* `:app_account_creation` for registering user accounts from the same IP address +* `:relations_actions` for actions on relations with all users (follow, unfollow) +* `:relation_id_action` for actions on relation with a specific user (follow, unfollow) +* `:statuses_actions` for create / delete / fav / unfav / reblog / unreblog actions on any statuses +* `:status_id_action` for fav / unfav or reblog / unreblog actions on the same status by the same user + +## :web_cache_ttl + +The expiration time for the web responses cache. Values should be in milliseconds or `nil` to disable expiration. + +Available caches: + +* `:activity_pub` - activity pub routes (except question activities). Defaults to `nil` (no expiration). +* `:activity_pub_question` - activity pub routes (question activities). Defaults to `30_000` (30 seconds). + +## Pleroma.Plugs.RemoteIp + +**If your instance is not behind at least one reverse proxy, you should not enable this plug.** + +`Pleroma.Plugs.RemoteIp` is a shim to call [`RemoteIp`](https://git.pleroma.social/pleroma/remote_ip) but with runtime configuration. + +Available options: + +* `enabled` - Enable/disable the plug. Defaults to `false`. +* `headers` - A list of strings naming the `req_headers` to use when deriving the `remote_ip`. Order does not matter. Defaults to `~w[forwarded x-forwarded-for x-client-ip x-real-ip]`. +* `proxies` - A list of strings in [CIDR](https://en.wikipedia.org/wiki/CIDR) notation specifying the IPs of known proxies. Defaults to `[]`. +* `reserved` - Defaults to [localhost](https://en.wikipedia.org/wiki/Localhost) and [private network](https://en.wikipedia.org/wiki/Private_network). diff --git a/docs/configuration/custom_emoji.md b/docs/configuration/custom_emoji.md new file mode 100644 index 000000000..f72c0edbc --- /dev/null +++ b/docs/configuration/custom_emoji.md @@ -0,0 +1,68 @@ +# 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: +* 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 `instance/static/emoji/custom`): `happy.png` and `sad.png` + +content of `emoji.txt`: +``` +happy, /emoji/custom/happy.png, Tag1,Tag2 +sad, /emoji/custom/sad.png, Tag1 +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`. 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"], + groups: [ + Finmoji: "/finmoji/128px/*-128.png", + Custom: ["/emoji/*.png", "/emoji/custom/*.png"] + ] +``` + +Order of the `groups` matters, so to override default tags just put your group on top of the list. E.g: +```elixir +config :pleroma, :emoji, + shortcode_globs: ["/emoji/custom/**/*.png"], + groups: [ + "Finmoji special": "/finmoji/128px/a_trusted_friend-128.png", # special file + "Cirno": "/emoji/custom/cirno*.png", # png files in /emoji/custom/ which start with `cirno` + "Special group": "/emoji/custom/special_folder/*.png", # png files in /emoji/custom/special_folder/ + "Another group": "/emoji/custom/special_folder/*/.png", # png files in /emoji/custom/special_folder/ subfolders + Finmoji: "/finmoji/128px/*-128.png", + Custom: ["/emoji/*.png", "/emoji/custom/*.png"] + ] +``` + +Priority of tags assigns in emoji.txt and custom.txt: + +`tag in file > special group setting in config.exs > default setting in config.exs` + +Priority for globs: + +`special group setting in config.exs > default setting in config.exs` diff --git a/docs/configuration/hardening.md b/docs/configuration/hardening.md new file mode 100644 index 000000000..b54c28850 --- /dev/null +++ b/docs/configuration/hardening.md @@ -0,0 +1,103 @@ +# Hardening your instance +Here are some suggestions which improve the security of parts of your Pleroma instance. + +## Configuration file + +These changes should go into `prod.secret.exs` or `dev.secret.exs`, depending on your `MIX_ENV` value. + +### `http` + +> Recommended value: `[ip: {127, 0, 0, 1}]` + +This sets the Pleroma application server to only listen to the localhost interface. This way, you can only reach your server over the Internet by going through the reverse proxy. By default, Pleroma listens on all interfaces. + +### `secure_cookie_flag` + +> Recommended value: `true` + +This sets the `secure` flag on Pleroma’s session cookie. This makes sure, that the cookie is only accepted over encrypted HTTPs connections. This implicitly renames the cookie from `pleroma_key` to `__Host-pleroma-key` which enforces some restrictions. (see [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Cookie_prefixes)) + +### `:http_security` + +> Recommended value: `true` + +This will send additional HTTP security headers to the clients, including: + +* `X-XSS-Protection: "1; mode=block"` +* `X-Permitted-Cross-Domain-Policies: "none"` +* `X-Frame-Options: "DENY"` +* `X-Content-Type-Options: "nosniff"` +* `X-Download-Options: "noopen"` + +A content security policy (CSP) will also be set: + +```csp +content-security-policy: + default-src 'none'; + base-uri 'self'; + frame-ancestors 'none'; + img-src 'self' data: https:; + media-src 'self' https:; + style-src 'self' 'unsafe-inline'; + font-src 'self'; + script-src 'self'; + connect-src 'self' wss://example.tld; + manifest-src 'self'; + upgrade-insecure-requests; +``` + +#### `sts` + +> Recommended value: `true` + +An additional “Strict transport security” header will be sent with the configured `sts_max_age` parameter. This tells the browser, that the domain should only be accessed over a secure HTTPs connection. + +#### `ct_max_age` + +An additional “Expect-CT” header will be sent with the configured `ct_max_age` parameter. This enforces the use of TLS certificates that are published in the certificate transparency log. (see [Expect-CT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expect-CT)) + +#### `referrer_policy` + +> Recommended value: `same-origin` + +If you click on a link, your browser’s request to the other site will include from where it is coming from. The “Referrer policy” header tells the browser how and if it should send this information. (see [Referrer policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)) + +## systemd + +A systemd unit example is provided at `installation/pleroma.service`. + +### PrivateTmp + +> Recommended value: `true` + +Use private `/tmp` and `/var/tmp` folders inside a new file system namespace, which are discarded after the process stops. + +### ProtectHome + +> Recommended value: `true` + +The `/home`, `/root`, and `/run/user` folders can not be accessed by this service anymore. If your Pleroma user has its home folder in one of the restricted places, or use one of these folders as its working directory, you have to set this to `false`. + +### ProtectSystem + +> Recommended value: `full` + +Mount `/usr`, `/boot`, and `/etc` as read-only for processes invoked by this service. + +### PrivateDevices + +> Recommended value: `true` + +Sets up a new `/dev` mount for the process and only adds API pseudo devices like `/dev/null`, `/dev/zero` or `/dev/random` but not physical devices. This may not work on devices like the Raspberry Pi, where you need to set this to `false`. + +### NoNewPrivileges + +> Recommended value: `true` + +Ensures that the service process and all its children can never gain new privileges through `execve()`. + +### CapabilityBoundingSet + +> Recommended value: `~CAP_SYS_ADMIN` + +Drops the sysadmin capability from the daemon. diff --git a/docs/configuration/howto_mediaproxy.md b/docs/configuration/howto_mediaproxy.md new file mode 100644 index 000000000..16c40c5db --- /dev/null +++ b/docs/configuration/howto_mediaproxy.md @@ -0,0 +1,34 @@ +# How to activate mediaproxy +## Explanation + +Without the `mediaproxy` function, Pleroma doesn't store any remote content like pictures, video etc. locally. So every time you open Pleroma, the content is loaded from the source server, from where the post is coming. This can result in slowly loading content or/and increased bandwidth usage on the source server. +With the `mediaproxy` function you can use nginx to cache this content, so users can access it faster, because it's loaded from your server. + +## Activate it + +* Edit your nginx config and add the following location: +``` +location /proxy { + proxy_cache pleroma_media_cache; + proxy_cache_lock on; + proxy_pass http://localhost:4000; +} +``` +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; +``` +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. + +* Append the following to your `prod.secret.exs` or `dev.secret.exs` (depends on which mode your instance is running): +``` +config :pleroma, :media_proxy, + enabled: true, + proxy_opts: [ + redirect_on_failure: true + ] + #base_url: "https://cache.pleroma.social" +``` +If you want to use a subdomain to serve the files, uncomment `base_url`, change the url and add a comma after `true` in the previous line. + +* Restart nginx and Pleroma diff --git a/docs/configuration/howto_mongooseim.md b/docs/configuration/howto_mongooseim.md new file mode 100644 index 000000000..a33e590a1 --- /dev/null +++ b/docs/configuration/howto_mongooseim.md @@ -0,0 +1,10 @@ +# Configuring MongooseIM (XMPP Server) to use Pleroma for authentication + +If you want to give your Pleroma users an XMPP (chat) account, you can configure [MongooseIM](https://github.com/esl/MongooseIM) to use your Pleroma server for user authentication, automatically giving every local user an XMPP account. + +In general, you just have to follow the configuration described at [https://mongooseim.readthedocs.io/en/latest/authentication-backends/HTTP-authentication-module/](https://mongooseim.readthedocs.io/en/latest/authentication-backends/HTTP-authentication-module/) and do these changes to your mongooseim.cfg. + +1. Set the auth_method to `{auth_method, http}`. +2. Add the http auth pool like this: `{http, global, auth, [{workers, 50}], [{server, "https://yourpleromainstance.com"}]}` + +Restart your MongooseIM server, your users should now be able to connect with their Pleroma credentials. diff --git a/docs/configuration/howto_proxy.md b/docs/configuration/howto_proxy.md new file mode 100644 index 000000000..10a635266 --- /dev/null +++ b/docs/configuration/howto_proxy.md @@ -0,0 +1,12 @@ +# How to configure upstream proxy for federation +If you want to proxify all http requests (e.g. for TOR) that pleroma makes to an upstream proxy server, edit you config file (`dev.secret.exs` or `prod.secret.exs`) and add the following: + +``` +config :pleroma, :http, + proxy_url: "127.0.0.1:8123" +``` + +The other way to do it, for example, with Tor you would most likely add something like this: +``` +config :pleroma, :http, proxy_url: {:socks5, :localhost, 9050} +``` diff --git a/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md b/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md new file mode 100644 index 000000000..bfee5a9e6 --- /dev/null +++ b/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md @@ -0,0 +1,33 @@ +# How to set rich media cache ttl based on image ttl +## Explanation + +Richmedia are cached without the ttl but the rich media may have image which can expire, like aws signed url. +In such cases the old image url (expired) is returned from the media cache. + +So to avoid such situation we can define a module that will set ttl based on image. +The module must adopt behaviour `Pleroma.Web.RichMedia.Parser.TTL` + +### Example + +```exs +defmodule MyModule do + @behaviour Pleroma.Web.RichMedia.Parser.TTL + + @impl Pleroma.Web.RichMedia.Parser.TTL + def ttl(data, url) do + image_url = Map.get(data, :image) + # do some parsing in the url and get the ttl of the image + # return ttl is unix time + parse_ttl_from_url(image_url) + end +end +``` + +And update the config + +```exs +config :pleroma, :rich_media, + ttl_setters: [Pleroma.Web.RichMedia.Parser.TTL.AwsSignedUrl, MyModule] +``` + +> For reference there is a parser for AWS signed URL `Pleroma.Web.RichMedia.Parser.TTL.AwsSignedUrl`, it's enabled by default. diff --git a/docs/configuration/howto_user_recomendation.md b/docs/configuration/howto_user_recomendation.md new file mode 100644 index 000000000..c4d749d0c --- /dev/null +++ b/docs/configuration/howto_user_recomendation.md @@ -0,0 +1,31 @@ +# How to activate user recommendation (Who to follow panel) +![who-to-follow-panel-small](/uploads/9de1b1300436c32461d272945f1bc23e/who-to-follow-panel-small.png) + +To show the *who to follow* panel, edit `config/prod.secret.exs` in the Pleroma backend. Following code activates the *who to follow* panel: + +```elixir +config :pleroma, :suggestions, + enabled: true, + third_party_engine: + "http://vinayaka.distsn.org/cgi-bin/vinayaka-user-match-suggestions-api.cgi?{{host}}+{{user}}", + timeout: 300_000, + limit: 40, + web: "https://vinayaka.distsn.org" + +``` + +`config/config.exs` already includes this code, but `enabled:` is `false`. + +`/api/v1/suggestions` is also provided when *who to follow* panel is enabled. + +For advanced customization, following code shows the newcomers of the fediverse at the *who to follow* panel: + +```elixir +config :pleroma, :suggestions, + enabled: true, + third_party_engine: + "http://vinayaka.distsn.org/cgi-bin/vinayaka-user-new-suggestions-api.cgi?{{host}}+{{user}}", + timeout: 60_000, + limit: 40, + web: "https://vinayaka.distsn.org/user-new.html" +``` diff --git a/docs/configuration/i2p.md b/docs/configuration/i2p.md new file mode 100644 index 000000000..62ced8b7a --- /dev/null +++ b/docs/configuration/i2p.md @@ -0,0 +1,196 @@ +# I2P Federation and Accessability + +This guide is going to focus on the Pleroma federation aspect. The actual installation is neatly explained in the official documentation, and more likely to remain up-to-date. +It might be added to this guide if there will be a need for that. + +We're going to use I2PD for its lightweightness over the official client. +Follow the documentation according to your distro: https://i2pd.readthedocs.io/en/latest/user-guide/install/#installing + +How to run it: https://i2pd.readthedocs.io/en/latest/user-guide/run/ + +## I2P Federation + +There are 2 ways to go about this. +One using the config, and one using external software (fedproxy). The external software works better so far. + +### Using the Config + +**Warning:** So far, everytime I followed this way of federating using I2P, the rest of my federation stopped working. I'm leaving this here in case it will help with making it work. + +Assuming you're running in prod, cd to your Pleroma folder and append the following to `config/prod.secret.exs`: +``` +config :pleroma, :http, proxy_url: {:socks5, :localhost, 4447} +``` +And then run the following: +``` +su pleroma +MIX_ENV=prod mix deps.get +MIX_ENV=prod mix ecto.migrate +exit +``` +You can restart I2PD here and finish if you don't wish to make your instance viewable or accessible over I2P. +``` +systemctl stop i2pd.service --no-block +systemctl start i2pd.service +``` +*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). + +You can change the socks proxy port in `/etc/i2pd/i2pd.conf`. + +### Using Fedproxy + +Fedproxy passes through clearnet requests direct to where they are going. It doesn't force anything over Tor. + +To use [fedproxy](https://github.com/majestrate/fedproxy) you'll need to install Golang. +``` +apt install golang +``` +Use a different user than pleroma or root. Run the following to add the Gopath to your ~/.bashrc. +``` +echo "export GOPATH=/home/ren/.go" >> ~/.bashrc +``` +Restart that bash session (you can exit and log back in). +Run the following to get fedproxy. +``` +go get -u github.com/majestrate/fedproxy$ +cp $(GOPATH)/bin/fedproxy /usr/local/bin/fedproxy +``` +And then the following to start it for I2P only. +``` +fedproxy 127.0.0.1:2000 127.0.0.1:4447 +``` +If you want to also use it for Tor, add `127.0.0.1:9050` to that command. +You'll also need to modify your Pleroma config. + +Assuming you're running in prod, cd to your Pleroma folder and append the following to `config/prod.secret.exs`: +``` +config :pleroma, :http, proxy_url: {:socks5, :localhost, 2000} +``` +And then run the following: +``` +su pleroma +MIX_ENV=prod mix deps.get +MIX_ENV=prod mix ecto.migrate +exit +``` +You can restart I2PD here and finish if you don't wish to make your instance viewable or accessible over I2P. + +``` +systemctl stop i2pd.service --no-block +systemctl start i2pd.service +``` +*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). + +You can change the socks proxy port in `/etc/i2pd/i2pd.conf`. + +## I2P Instance Access + +Make your instance accessible using I2P. + +Add the following to your I2PD config `/etc/i2pd/tunnels.conf`: +``` +[pleroma] +type = http +host = 127.0.0.1 +port = 14447 +keys = pleroma.dat +``` +Restart I2PD: +``` +systemctl stop i2pd.service --no-block +systemctl start i2pd.service +``` +*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). + +Now you'll have to find your address. +To do that you can download and use I2PD tools.[^1] +Or you'll need to access your web-console on localhost:7070. +If you don't have a GUI, you'll have to SSH tunnel into it like this: +`ssh -L 7070:127.0.0.1:7070 user@ip -p port`. +Now you can access it at localhost:7070. +Go to I2P tunnels page. Look for Server tunnels and you will see an address that ends with `.b32.i2p` next to "pleroma". +This is your site's address. + +### I2P-only Instance + +If creating an I2P-only instance, open `config/prod.secret.exs` and under "config :pleroma, Pleroma.Web.Endpoint," edit "https" and "port: 443" to the following: +``` + url: [host: "i2paddress", scheme: "http", port: 80], +``` +In addition to that, replace the existing nginx config's contents with the example below. + +### Existing Instance (Clearnet Instance) + +If not an I2P-only instance, add the nginx config below to your existing config at `/etc/nginx/sites-enabled/pleroma.nginx`. + +And for both cases, disable CSP in Pleroma's config (STS is disabled by default) so you can define those yourself seperately from the clearnet (if your instance is also on the clearnet). +Copy the following into the `config/prod.secret.exs` in your Pleroma folder (/home/pleroma/pleroma/): +``` +config :pleroma, :http_security, + enabled: false +``` + +Use this as the Nginx config: +``` +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; +# The above already exists in a clearnet instance's config. +# If not, add it. + +server { + listen 127.0.0.1:14447; + server_name youri2paddress; + + # Comment to enable logs + access_log /dev/null; + error_log /dev/null; + + gzip_vary on; + gzip_proxied any; + gzip_comp_level 6; + gzip_buffers 16 8k; + gzip_http_version 1.1; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml; + + client_max_body_size 16m; + + location / { + + add_header X-XSS-Protection "1; mode=block"; + add_header X-Permitted-Cross-Domain-Policies none; + add_header X-Frame-Options DENY; + add_header X-Content-Type-Options nosniff; + add_header Referrer-Policy same-origin; + add_header X-Download-Options noopen; + + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $http_host; + + proxy_pass http://localhost:4000; + + client_max_body_size 16m; + } + + location /proxy { + proxy_cache pleroma_media_cache; + proxy_cache_lock on; + proxy_ignore_client_abort on; + proxy_pass http://localhost:4000; + } +} +``` +reload Nginx: +``` +systemctl stop i2pd.service --no-block +systemctl start i2pd.service +``` +*Notice:* The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes). + +You should now be able to both access your instance using I2P and federate with other I2P instances! + +[^1]: [I2PD tools](https://github.com/purplei2p/i2pd-tools) to print information about a router info file or an I2P private key, generate an I2P private key, and generate vanity addresses. + +### Possible Issues + +Will be added when encountered. diff --git a/docs/configuration/mrf.md b/docs/configuration/mrf.md new file mode 100644 index 000000000..45be18fc5 --- /dev/null +++ b/docs/configuration/mrf.md @@ -0,0 +1,122 @@ +# Message Rewrite Facility +The Message Rewrite Facility (MRF) is a subsystem that is implemented as a series of hooks that allows the administrator to rewrite or discard messages. + +Possible uses include: + +* marking incoming messages with media from a given account or instance as sensitive +* rejecting messages from a specific instance +* rejecting reports (flags) from a specific instance +* removing/unlisting messages from the public timelines +* removing media from messages +* sending only public messages to a specific instance + +The MRF provides user-configurable policies. The default policy is `NoOpPolicy`, which disables the MRF functionality. Pleroma also includes an easy to use policy called `SimplePolicy` which maps messages matching certain pre-defined criterion to actions built into the policy module. +It is possible to use multiple, active MRF policies at the same time. + +## Quarantine Instances + +You have the ability to prevent from private / followers-only messages from federating with specific instances. Which means they will only get the public or unlisted messages from your instance. + +If, for example, you're using `MIX_ENV=prod` aka using production mode, you would open your configuration file located in `config/prod.secret.exs` and edit or add the option under your `:instance` config object. Then you would specify the instance within quotes. +``` +config :pleroma, :instance, + [...] + quarantined_instances: ["instance.example", "other.example"] +``` + +## Using `SimplePolicy` + +`SimplePolicy` is capable of handling most common admin tasks. + +To use `SimplePolicy`, you must enable it. Do so by adding the following to your `:instance` config object, so that it looks like this: + +``` +config :pleroma, :instance, + [...] + rewrite_policy: Pleroma.Web.ActivityPub.MRF.SimplePolicy +``` + +Once `SimplePolicy` is enabled, you can configure various groups in the `:mrf_simple` config object. These groups are: + +* `media_removal`: Servers in this group will have media stripped from incoming messages. +* `media_nsfw`: Servers in this group will have the #nsfw tag and sensitive setting injected into incoming messages which contain media. +* `reject`: Servers in this group will have their messages rejected. +* `federated_timeline_removal`: Servers in this group will have their messages unlisted from the public timelines by flipping the `to` and `cc` fields. +* `report_removal`: Servers in this group will have their reports (flags) rejected. + +Servers should be configured as lists. + +### Example + +This example will enable `SimplePolicy`, block media from `illegalporn.biz`, mark media as NSFW from `porn.biz` and `porn.business`, reject messages from `spam.com`, remove messages from `spam.university` from the federated timeline and block reports (flags) from `whiny.whiner`: + +``` +config :pleroma, :instance, + rewrite_policy: [Pleroma.Web.ActivityPub.MRF.SimplePolicy] + +config :pleroma, :mrf_simple, + media_removal: ["illegalporn.biz"], + media_nsfw: ["porn.biz", "porn.business"], + reject: ["spam.com"], + federated_timeline_removal: ["spam.university"], + report_removal: ["whiny.whiner"] + +``` + +### Use with Care + +The effects of MRF policies can be very drastic. It is important to use this functionality carefully. Always try to talk to an admin before writing an MRF policy concerning their instance. + +## Writing your own MRF Policy + +As discussed above, the MRF system is a modular system that supports pluggable policies. This means that an admin may write a custom MRF policy in Elixir or any other language that runs on the Erlang VM, by specifying the module name in the `rewrite_policy` config setting. + +For example, here is a sample policy module which rewrites all messages to "new message content": + +```elixir +# This is a sample MRF policy which rewrites all Notes to have "new message +# content." +defmodule Site.RewritePolicy do + @behavior Pleroma.Web.ActivityPub.MRF + + # Catch messages which contain Note objects with actual data to filter. + # Capture the object as `object`, the message content as `content` and the + # message itself as `message`. + @impl true + def filter(%{"type" => Create", "object" => {"type" => "Note", "content" => content} = object} = message) + when is_binary(content) do + # Subject / CW is stored as summary instead of `name` like other AS2 objects + # because of Mastodon doing it that way. + summary = object["summary"] + + # Message edits go here. + content = "new message content" + + # Assemble the mutated object. + object = + object + |> Map.put("content", content) + |> Map.put("summary", summary) + + # Assemble the mutated message. + message = Map.put(message, "object", object) + {:ok, message} + end + + # Let all other messages through without modifying them. + @impl true + def filter(message), do: {:ok, message} +end +``` + +If you save this file as `lib/site/mrf/rewrite_policy.ex`, it will be included when you next rebuild Pleroma. You can enable it in the configuration like so: + +``` +config :pleroma, :instance, + rewrite_policy: [ + Pleroma.Web.ActivityPub.MRF.SimplePolicy, + Site.RewritePolicy + ] +``` + +Please note that the Pleroma developers consider custom MRF policy modules to fall under the purview of the AGPL. As such, you are obligated to release the sources to your custom MRF policy modules upon request. diff --git a/docs/configuration/onion_federation.md b/docs/configuration/onion_federation.md new file mode 100644 index 000000000..99f104995 --- /dev/null +++ b/docs/configuration/onion_federation.md @@ -0,0 +1,159 @@ +# Easy Onion Federation (Tor) +Tor can free people from the necessity of a domain, in addition to helping protect their privacy. As Pleroma's goal is to empower the people and let as many as possible host an instance with as little resources as possible, the ability to host an instance with a small, cheap computer like a RaspberryPi along with Tor, would be a great way to achieve that. +In addition, federating with such instances will also help furthering that goal. + +This is a guide to show you how it can be easily done. + +This guide assumes you already got Pleroma working, and that it's running on the default port 4000. +Currently only has an Nginx example. + +To install Tor on Debian / Ubuntu: +``` +apt -yq install tor +``` +If using an old server version (older than Debian Stretch or Ubuntu 18.04), install from backports or PPA. +I recommend using a newer server version instead. + +To have the newest, V3 onion addresses (which I recommend) in Debian, install Tor from backports. +If you do not have backports, uncomment the stretch-backports links at the end of `/etc/apt/sources.list`. +Then install: +``` +apt update +apt -t stretch-backports -yq install tor +``` +**WARNING:** Onion instances not using a Tor version supporting V3 addresses will not be able to federate with you. + +Create the hidden service for your Pleroma instance in `/etc/tor/torrc`: +``` +HiddenServiceDir /var/lib/tor/pleroma_hidden_service/ +HiddenServicePort 80 127.0.0.1:8099 +HiddenServiceVersion 3 # Remove if Tor version is below 0.3 ( tor --version ) +``` +Restart Tor to generate an adress: +``` +systemctl restart tor@default.service +``` +Get the address: +``` +cat /var/lib/tor/pleroma_hidden_service/hostname +``` + +# Federation + +Next, edit your Pleroma config. +If running in prod, cd to your Pleroma directory, edit `config/prod.secret.exs` +and append this line: +``` +config :pleroma, :http, proxy_url: {:socks5, :localhost, 9050} +``` +In your Pleroma directory, assuming you're running prod, +run the following: +``` +su pleroma +MIX_ENV=prod mix deps.get +MIX_ENV=prod mix ecto.migrate +exit +``` +restart Pleroma (if using systemd): +``` +systemctl restart pleroma +``` + +# Tor Instance Access + +Make your instance accessible using Tor. + +## Tor-only Instance +If creating a Tor-only instance, open `config/prod.secret.exs` and under "config :pleroma, Pleroma.Web.Endpoint," edit "https" and "port: 443" to the following: +``` + url: [host: "onionaddress", scheme: "http", port: 80], +``` +In addition to that, replace the existing nginx config's contents with the example below. + +## Existing Instance (Clearnet Instance) +If not a Tor-only instance, +add the nginx config below to your existing config at `/etc/nginx/sites-enabled/pleroma.nginx`. + +--- +For both cases, disable CSP in Pleroma's config (STS is disabled by default) so you can define those yourself seperately from the clearnet (if your instance is also on the clearnet). +Copy the following into the `config/prod.secret.exs` in your Pleroma folder (/home/pleroma/pleroma/): +``` +config :pleroma, :http_security, + enabled: false +``` + +Use this as the Nginx config: +``` +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; +# The above already exists in a clearnet instance's config. +# If not, add it. + +server { + listen 127.0.0.1:8099; + server_name youronionaddress; + + # Comment to enable logs + access_log /dev/null; + error_log /dev/null; + + gzip_vary on; + gzip_proxied any; + gzip_comp_level 6; + gzip_buffers 16 8k; + gzip_http_version 1.1; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml; + + client_max_body_size 16m; + + location / { + + add_header X-XSS-Protection "1; mode=block"; + add_header X-Permitted-Cross-Domain-Policies none; + add_header X-Frame-Options DENY; + add_header X-Content-Type-Options nosniff; + add_header Referrer-Policy same-origin; + add_header X-Download-Options noopen; + + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $http_host; + + proxy_pass http://localhost:4000; + + client_max_body_size 16m; + } + + location /proxy { + proxy_cache pleroma_media_cache; + proxy_cache_lock on; + proxy_ignore_client_abort on; + proxy_pass http://localhost:4000; + } +} +``` +reload Nginx: +``` +systemctl reload nginx +``` + +You should now be able to both access your instance using Tor and federate with other Tor instances! + +--- + +### Possible Issues + +* In Debian, make sure your hidden service folder `/var/lib/tor/pleroma_hidden_service/` and its contents, has debian-tor as both owner and group by using +``` +ls -la /var/lib/tor/ +``` +If it's not, run: +``` +chown -R debian-tor:debian-tor /var/lib/tor/pleroma_hidden_service/ +``` +* Make sure *only* the owner has *only* read and write permissions. +If not, run: +``` +chmod -R 600 /var/lib/tor/pleroma_hidden_service/ +``` +* If you have trouble logging in to the Mastodon Frontend when using Tor, use the Tor Browser Bundle. diff --git a/docs/configuration/small_customizations.md b/docs/configuration/small_customizations.md new file mode 100644 index 000000000..f91657a4c --- /dev/null +++ b/docs/configuration/small_customizations.md @@ -0,0 +1,12 @@ +# Small customizations + +See also static_dir.md for visual settings. + +## Theme + +All users of your instance will be able to change the theme they use by going to the settings (the cog in the top-right hand corner). However, if you wish to change the default theme, you can do so by editing `theme` in `config/dev.secret.exs` accordingly. + +## Message Visibility + +To enable message visibility options when posting like in the Mastodon frontend, set +`scope_options_enabled` to `true` in `config/dev.secret.exs`. diff --git a/docs/configuration/static_dir.md b/docs/configuration/static_dir.md new file mode 100644 index 000000000..5fb38c3de --- /dev/null +++ b/docs/configuration/static_dir.md @@ -0,0 +1,69 @@ +# Static Directory + +Static frontend files are shipped in `priv/static/` and tracked by version control in this repository. If you want to overwrite or update these without the possibility of merge conflicts, you can write your custom versions to `instance/static/`. + +``` +config :pleroma, :instance, + static_dir: "instance/static/", +``` + +For example, edit `instance/static/instance/panel.html` . + +Alternatively, you can overwrite this value in your configuration to use a different static instance directory. + +This document is written assuming `instance/static/`. + +Or, if you want to manage your custom file in git repository, basically remove the `instance/` entry from `.gitignore`. + +## robots.txt + +By default, the `robots.txt` that ships in `priv/static/` is permissive. It allows well-behaved search engines to index all of your instance's URIs. + +If you want to generate a restrictive `robots.txt`, you can run the following mix task. The generated `robots.txt` will be written in your instance static directory. + +``` +mix pleroma.robots_txt disallow_all +``` + +## Thumbnail + +Put on `instance/static/instance/thumbnail.jpeg` with your selfie or other neat picture. It will appear in [Pleroma Instances](http://distsn.org/pleroma-instances.html). + +## Instance-specific panel + +![instance-specific panel demo](/uploads/296b19ec806b130e0b49b16bfe29ce8a/image.png) + +Create and Edit your file on `instance/static/instance/panel.html`. + +## Background + +You can change the background of your Pleroma instance by uploading it to `instance/static/`, and then changing `background` in `config/prod.secret.exs` accordingly. + +If you put `instance/static/images/background.jpg` + +``` +config :pleroma, :frontend_configurations, + pleroma_fe: %{ + background: "/images/background.jpg" + } +``` + +## Logo + +![logo modification demo](/uploads/c70b14de60fa74245e7f0dcfa695ebff/image.png) + +If you want to give a brand to your instance, You can change the logo of your instance by uploading it to `instance/static/`. + +Alternatively, you can specify the path with config. +If you put `instance/static/static/mylogo-file.png` + +``` +config :pleroma, :frontend_configurations, + pleroma_fe: %{ + logo: "/static/mylogo-file.png" + } +``` + +## Terms of Service + +Terms of Service will be shown to all users on the registration page. It's the best place where to write down the rules for your instance. You can modify the rules by changing `instance/static/static/terms-of-service.html`. -- cgit v1.2.3 From 03e1898917d161c2682ded202d335de582c04989 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Wed, 2 Oct 2019 23:54:55 +0300 Subject: Rename "Configuration" to "Configuration Cheat Sheet" and explain a bit about how Pleroma Configuration works --- docs/configuration/cheatsheet.md | 777 +++++++++++++++++++++++++++++++++++++++ docs/configuration/config.md | 773 -------------------------------------- 2 files changed, 777 insertions(+), 773 deletions(-) create mode 100644 docs/configuration/cheatsheet.md delete mode 100644 docs/configuration/config.md diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md new file mode 100644 index 000000000..fd936aed7 --- /dev/null +++ b/docs/configuration/cheatsheet.md @@ -0,0 +1,777 @@ +# Configuration Cheat Sheet + +This is a cheat sheet for Pleroma configuration file, any setting possible to configure should be listed here. + +Pleroma configuration works by first importing the base config (`config/config.exs` on source installs, compiled-in on OTP releases), then overriding it by the environment config (`config/$MIX_ENV.exs` on source installs, N/A to OTP releases) and then overriding it by user config (`config/$MIX_ENV.secret.exs` on source installs, typically `/etc/pleroma/config.exs` on OTP releases). + +You shouldn't edit the base config directly to avoid breakages and merge conflicts, but it can be used as a reference if you don't understand how an option is supposed to be formatted, the latest version of it can be viewed [here](https://git.pleroma.social/pleroma/pleroma/blob/develop/config/config.exs). + + +## Pleroma.Upload +* `uploader`: Select which `Pleroma.Uploaders` to use +* `filters`: List of `Pleroma.Upload.Filter` to use. +* `link_name`: When enabled Pleroma will add a `name` parameter to the url of the upload, for example `https://instance.tld/media/corndog.png?name=corndog.png`. This is needed to provide the correct filename in Content-Disposition headers when using filters like `Pleroma.Upload.Filter.Dedupe` +* `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host. +* `proxy_remote`: If you're using a remote uploader, Pleroma will proxy media requests instead of redirecting to it. +* `proxy_opts`: Proxy options, see `Pleroma.ReverseProxy` documentation. + +Note: `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`. + +## Pleroma.Uploaders.Local +* `uploads`: Which directory to store the user-uploads in, relative to pleroma’s working directory + +## Pleroma.Uploaders.S3 +* `bucket`: S3 bucket name +* `bucket_namespace`: S3 bucket namespace +* `public_endpoint`: S3 endpoint that the user finally accesses(ex. "https://s3.dualstack.ap-northeast-1.amazonaws.com") +* `truncated_namespace`: If you use S3 compatible service such as Digital Ocean Spaces or CDN, set folder name or "" etc. +For example, when using CDN to S3 virtual host format, set "". +At this time, write CNAME to CDN in public_endpoint. +* `streaming_enabled`: Enable streaming uploads, when enabled the file will be sent to the server in chunks as it's being read. This may be unsupported by some providers, try disabling this if you have upload problems. + +## Pleroma.Upload.Filter.Mogrify + +* `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"implode", "1"}]`. + +## Pleroma.Upload.Filter.Dedupe + +No specific configuration. + +## Pleroma.Upload.Filter.AnonymizeFilename + +This filter replaces the filename (not the path) of an upload. For complete obfuscation, add +`Pleroma.Upload.Filter.Dedupe` before AnonymizeFilename. + +* `text`: Text to replace filenames in links. If empty, `{random}.extension` will be used. You can get the original filename extension by using `{extension}`, for example `custom-file-name.{extension}`. + +## 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. +* `enabled`: Allows enable/disable send emails. Default: `false`. + +An example for Sendgrid adapter: + +```elixir +config :pleroma, Pleroma.Emails.Mailer, + adapter: Swoosh.Adapters.Sendgrid, + api_key: "YOUR_API_KEY" +``` + +An example for SMTP adapter: + +```elixir +config :pleroma, Pleroma.Emails.Mailer, + adapter: Swoosh.Adapters.SMTP, + relay: "smtp.gmail.com", + username: "YOUR_USERNAME@gmail.com", + password: "YOUR_SMTP_PASSWORD", + port: 465, + ssl: true, + tls: :always, + auth: :always +``` + +## :uri_schemes +* `valid_schemes`: List of the scheme part that is considered valid to be an URL + +## :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. +* `upload_limit`: File size limit of uploads (except for avatar, background, banner) +* `avatar_upload_limit`: File size limit of user’s profile avatars +* `background_upload_limit`: File size limit of user’s profile backgrounds +* `banner_upload_limit`: File size limit of user’s profile banners +* `poll_limits`: A map with poll limits for **local** polls + * `max_options`: Maximum number of options + * `max_option_chars`: Maximum number of characters per option + * `min_expiration`: Minimum expiration time (in seconds) + * `max_expiration`: Maximum expiration time (in seconds) +* `registrations_open`: Enable registrations for anyone, invitations can be enabled when false. +* `invites_enabled`: Enable user invitations for admins (depends on `registrations_open: false`). +* `account_activation_required`: Require users to confirm their emails before signing in. +* `federating`: Enable federation with other instances +* `federation_incoming_replies_max_depth`: Max. depth of reply-to activities fetching on incoming federation, to prevent out-of-memory situations while fetching very long threads. If set to `nil`, threads of any depth will be fetched. Lower this value if you experience out-of-memory crashes. +* `federation_reachability_timeout_days`: Timeout (in days) of each external federation target being unreachable prior to pausing federating to it. +* `allow_relay`: Enable Pleroma’s Relay, which makes it possible to follow a whole instance +* `rewrite_policy`: Message Rewrite Policy, either one or a list. Here are the ones available by default: + * `Pleroma.Web.ActivityPub.MRF.NoOpPolicy`: Doesn’t modify activities (default) + * `Pleroma.Web.ActivityPub.MRF.DropPolicy`: Drops all activities. It generally doesn’t makes sense to use in production + * `Pleroma.Web.ActivityPub.MRF.SimplePolicy`: Restrict the visibility of activities from certains instances (See ``:mrf_simple`` section) + * `Pleroma.Web.ActivityPub.MRF.TagPolicy`: Applies policies to individual users based on tags, which can be set using pleroma-fe/admin-fe/any other app that supports Pleroma Admin API. For example it allows marking posts from individual users nsfw (sensitive) + * `Pleroma.Web.ActivityPub.MRF.SubchainPolicy`: Selectively runs other MRF policies when messages match (see ``:mrf_subchain`` section) + * `Pleroma.Web.ActivityPub.MRF.RejectNonPublic`: Drops posts with non-public visibility settings (See ``:mrf_rejectnonpublic`` section) + * `Pleroma.Web.ActivityPub.MRF.EnsureRePrepended`: Rewrites posts to ensure that replies to posts with subjects do not have an identical subject and instead begin with re:. + * `Pleroma.Web.ActivityPub.MRF.AntiLinkSpamPolicy`: Rejects posts from likely spambots by rejecting posts from new users that contain links. + * `Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy`: Crawls attachments using their MediaProxy URLs so that the MediaProxy cache is primed. + * `Pleroma.Web.ActivityPub.MRF.MentionPolicy`: Drops posts mentioning configurable users. (see `:mrf_mention` section) + * `Pleroma.Web.ActivityPub.MRF.VocabularyPolicy`: Restricts activities to a configured set of vocabulary. (see `:mrf_vocabulary` section) +* `public`: Makes the client API in authentificated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network. +* `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) +* `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). +* `mrf_transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. +* `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: + * "email": Copy and preprend re:, as in email. + * "masto": Copy verbatim, as in Mastodon. + * "noop": Don't copy the subject. +* `always_show_subject_input`: When set to false, auto-hide the subject field when it's empty. +* `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with + older software for theses nicknames. +* `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature. +* `autofollowed_nicknames`: Set to nicknames of (local) users that every new user should automatically follow. +* `no_attachment_links`: Set to true to disable automatically adding attachment link text to statuses +* `welcome_message`: A message that will be send to a newly registered users as a direct message. +* `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``. +* `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database. +* `user_bio_length`: A user bio maximum length (default: `5000`) +* `user_name_length`: A user name maximum length (default: `100`) +* `skip_thread_containment`: Skip filter out broken threads. The default is `false`. +* `limit_to_local_content`: Limit unauthenticated users to search for local statutes and users only. Possible values: `:unauthenticated`, `:all` and `false`. The default is `:unauthenticated`. +* `dynamic_configuration`: Allow transferring configuration to DB with the subsequent customization from Admin api. +* `max_account_fields`: The maximum number of custom fields in the user profile (default: `10`) +* `max_remote_account_fields`: The maximum number of custom fields in the remote user profile (default: `20`) +* `account_field_name_length`: An account field name maximum length (default: `512`) +* `account_field_value_length`: An account field value maximum length (default: `2048`) +* `external_user_synchronization`: Enabling following/followers counters synchronization for external users. + + + +## :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}] + +config :logger, :ex_syslogger, + level: :warn +``` + +Another example, keeping console output and adding the pid to syslog output: +```elixir +config :logger, + backends: [:console, {ExSyslogger, :ex_syslogger}] + +config :logger, :ex_syslogger, + level: :warn, + option: [:pid, :ndelay] +``` + +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 + +config :logger, :ex_syslogger, + level: :info, + ident: "pleroma", + format: "$metadata[$level] $message" + +config :quack, + level: :warn, + meta: [:all], + webhook_url: "https://hooks.slack.com/services/YOUR-API-KEY-HERE" +``` + +See the [Quack Github](https://github.com/azohra/quack) for more details + +## :frontend_configurations + +This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. + +Frontends can access these settings at `/api/pleroma/frontend_configurations` + +To add your own configuration for PleromaFE, use it like this: + +```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. + +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`](#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. + +* `theme`: Which theme to use, they are defined in ``styles.json`` +* `logo`: URL of the logo, defaults to Pleroma’s logo +* `logo_mask`: Whether to use only the logo's shape as a mask (true) or as a regular image (false) +* `logo_margin`: What margin to use around the logo +* `background`: URL of the background, unless viewing a user profile with a background that is set +* `redirect_root_no_login`: relative URL which indicates where to redirect when a user isn’t logged in. +* `redirect_root_login`: relative URL which indicates where to redirect when a user is logged in. +* `show_instance_panel`: Whenether to show the instance’s specific panel. +* `scope_options_enabled`: Enable setting an notice visibility and subject/CW when posting +* `formatting_options_enabled`: Enable setting a formatting different than plain-text (ie. HTML, Markdown) when posting, relates to ``:instance, allowed_post_formats`` +* `collapse_message_with_subjects`: When a message has a subject(aka Content Warning), collapse it by default +* `hide_post_stats`: Hide notices statistics(repeats, favorites, …) +* `hide_user_stats`: Hide profile statistics(posts, posts per day, followers, followings, …) + +## :assets + +This section configures assets to be used with various frontends. Currently the only option +relates to mascots on the mastodon frontend + +* `mascots`: KeywordList of mascots, each element __MUST__ contain both a `url` and a + `mime_type` key. +* `default_mascot`: An element from `mascots` - This will be used as the default mascot + on MastoFE (default: `:pleroma_fox_tan`) + +## :mrf_simple +* `media_removal`: List of instances to remove medias from +* `media_nsfw`: List of instances to put medias as NSFW(sensitive) from +* `federated_timeline_removal`: List of instances to remove from Federated (aka The Whole Known Network) Timeline +* `reject`: List of instances to reject any activities from +* `accept`: List of instances to accept any activities from +* `report_removal`: List of instances to reject reports from +* `avatar_removal`: List of instances to strip avatars from +* `banner_removal`: List of instances to strip banners from + +## :mrf_subchain +This policy processes messages through an alternate pipeline when a given message matches certain criteria. +All criteria are configured as a map of regular expressions to lists of policy modules. + +* `match_actor`: Matches a series of regular expressions against the actor field. + +Example: + +``` +config :pleroma, :mrf_subchain, + match_actor: %{ + ~r/https:\/\/example.com/s => [Pleroma.Web.ActivityPub.MRF.DropPolicy] + } +``` + +## :mrf_rejectnonpublic +* `allow_followersonly`: whether to allow followers-only posts +* `allow_direct`: whether to allow direct messages + +## :mrf_hellthread +* `delist_threshold`: Number of mentioned users after which the message gets delisted (the message can still be seen, but it will not show up in public timelines and mentioned users won't get notifications about it). Set to 0 to disable. +* `reject_threshold`: Number of mentioned users after which the messaged gets rejected. Set to 0 to disable. + +## :mrf_keyword +* `reject`: A list of patterns which result in message being rejected, each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) +* `federated_timeline_removal`: A list of patterns which result in message being removed from federated timelines (a.k.a unlisted), each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) +* `replace`: A list of tuples containing `{pattern, replacement}`, `pattern` can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) + +## :mrf_mention +* `actors`: A list of actors, for which to drop any posts mentioning. + +## :mrf_vocabulary +* `accept`: A list of ActivityStreams terms to accept. If empty, all supported messages are accepted. +* `reject`: A list of ActivityStreams terms to reject. If empty, no messages are rejected. + +## :media_proxy +* `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 +* `ip`: IP address to bind to +* `port`: Port to bind to +* `dstport`: Port advertised in urls (optional, defaults to `port`) + +## Pleroma.Web.Endpoint +`Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here +* `http` - a list containing http protocol configuration, all configuration options can be viewed [here](https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html#module-options), only common options are listed here. For deployment using docker, you need to set this to `[ip: {0,0,0,0}, port: 4000]` to make pleroma accessible from other containers (such as your nginx server). + - `ip` - a tuple consisting of 4 integers + - `port` +* `url` - a list containing the configuration for generating urls, accepts + - `host` - the host without the scheme and a post (e.g `example.com`, not `https://example.com:2020`) + - `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 + +Example: +```elixir +config :pleroma, Pleroma.Web.Endpoint, + url: [host: "example.com", port: 2020, scheme: "https"], + http: [ + # start copied from config.exs + dispatch: [ + {:_, + [ + {"/api/v1/streaming", Pleroma.Web.MastodonAPI.WebsocketHandler, []}, + {"/websocket", Phoenix.Endpoint.CowboyWebSocket, + {Phoenix.Transports.WebSocket, + {Pleroma.Web.Endpoint, Pleroma.Web.UserSocket, websocket_config}}}, + {:_, Phoenix.Endpoint.Cowboy2Handler, {Pleroma.Web.Endpoint, []}} + ]} + # end copied from config.exs + ], + port: 8080, + ip: {127, 0, 0, 1} + ] +``` + +This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls starting with `https://example.com:2020` + +## :activitypub +* ``unfollow_blocked``: Whether blocks result in people getting unfollowed +* ``outgoing_blocks``: Whether to federate blocks to other instances +* ``deny_follow_blocked``: Whether to disallow following an account that has blocked the user in question +* ``sign_object_fetches``: Sign object fetches with HTTP signatures + +## :http_security +* ``enabled``: Whether the managed content security policy is enabled +* ``sts``: Whether to additionally send a `Strict-Transport-Security` header +* ``sts_max_age``: The maximum age for the `Strict-Transport-Security` header if sent +* ``ct_max_age``: The maximum age for the `Expect-CT` header if sent +* ``referrer_policy``: The referrer policy to use, either `"same-origin"` or `"no-referrer"` +* ``report_uri``: Adds the specified url to `report-uri` and `report-to` group in CSP header. + +## :mrf_user_allowlist + +The keys in this section are the domain names that the policy should apply to. +Each key should be assigned a list of users that should be allowed through by +their ActivityPub ID. + +An example: + +```elixir +config :pleroma, :mrf_user_allowlist, + "example.org": ["https://example.org/users/admin"] +``` + +## :web_push_encryption, :vapid_details + +Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it. + +* ``subject``: a mailto link for the administrative contact. It’s best if this email is not a personal email address, but rather a group email so that if a person leaves an organization, is unavailable for an extended period, or otherwise can’t respond, someone else on the list can. +* ``public_key``: VAPID public key +* ``private_key``: VAPID private key + +## Pleroma.Captcha +* `enabled`: Whether the captcha should be shown on registration +* `method`: The method/service to use for captcha +* `seconds_valid`: The time in seconds for which the captcha is valid + +### Pleroma.Captcha.Kocaptcha +Kocaptcha is a very simple captcha service with a single API endpoint, +the source code is here: https://github.com/koto-bank/kocaptcha. The default endpoint +`https://captcha.kotobank.ch` is hosted by the developer. + +* `endpoint`: the kocaptcha endpoint to use + +## :admin_token + +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: + +```elixir +config :pleroma, :admin_token, "somerandomtoken" +``` + +You can then do + +```sh +curl "http://localhost:4000/api/pleroma/admin/invite_token?admin_token=somerandomtoken" +``` + +## Oban + +[Oban](https://github.com/sorentwo/oban) asynchronous job processor configuration. + +Configuration options described in [Oban readme](https://github.com/sorentwo/oban#usage): +* `repo` - app's Ecto repo (`Pleroma.Repo`) +* `verbose` - logs verbosity +* `prune` - non-retryable jobs [pruning settings](https://github.com/sorentwo/oban#pruning) (`:disabled` / `{:maxlen, value}` / `{:maxage, value}`) +* `queues` - job queues (see below) + +Pleroma has the following queues: + +* `activity_expiration` - Activity expiration +* `federator_outgoing` - Outgoing federation +* `federator_incoming` - Incoming federation +* `mailer` - Email sender, see [`Pleroma.Emails.Mailer`](#pleromaemailsmailer) +* `transmogrifier` - Transmogrifier +* `web_push` - Web push notifications +* `scheduled_activities` - Scheduled activities, see [`Pleroma.ScheduledActivity`](#pleromascheduledactivity) + +Example: + +```elixir +config :pleroma, Oban, + repo: Pleroma.Repo, + verbose: false, + prune: {:maxlen, 1500}, + queues: [ + federator_incoming: 50, + federator_outgoing: 50 + ] +``` + +This config contains two queues: `federator_incoming` and `federator_outgoing`. Both have the number of max concurrent jobs set to `50`. + +### Migrating `pleroma_job_queue` settings + +`config :pleroma_job_queue, :queues` is replaced by `config :pleroma, Oban, :queues` and uses the same format (keys are queues' names, values are max concurrent jobs numbers). + +### Note on running with PostgreSQL in silent mode + +If you are running PostgreSQL in [`silent_mode`](https://postgresqlco.nf/en/doc/param/silent_mode?version=9.1), it's advised to set [`log_destination`](https://postgresqlco.nf/en/doc/param/log_destination?version=9.1) to `syslog`, +otherwise `postmaster.log` file may grow because of "you don't own a lock of type ShareLock" warnings (see https://github.com/sorentwo/oban/issues/52). + +## :workers + +Includes custom worker options not interpretable directly by `Oban`. + +* `retries` — keyword lists where keys are `Oban` queues (see above) and values are numbers of max attempts for failed jobs. + +Example: + +```elixir +config :pleroma, :workers, + retries: [ + federator_incoming: 5, + federator_outgoing: 5 + ] +``` + +### Migrating `Pleroma.Web.Federator.RetryQueue` settings + +* `max_retries` is replaced with `config :pleroma, :workers, retries: [federator_outgoing: 5]` +* `enabled: false` corresponds to `config :pleroma, :workers, retries: [federator_outgoing: 1]` +* deprecated options: `max_jobs`, `initial_timeout` + +## Pleroma.Web.Metadata +* `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 `
` as `` +* `unfurl_nsfw`: If set to `true` nsfw attachments will be shown in previews + +## :rich_media +* `enabled`: if enabled the instance will parse metadata from attached links to generate link previews +* `ignore_hosts`: list of hosts which will be ignored by the metadata parser. For example `["accounts.google.com", "xss.website"]`, defaults to `[]`. +* `ignore_tld`: list TLDs (top-level domains) which will ignore for parse metadata. default is ["local", "localdomain", "lan"] +* `parsers`: list of Rich Media parsers + +## :fetch_initial_posts +* `enabled`: if enabled, when a new user is federated with, fetch some of their latest posts +* `pages`: the amount of pages to fetch + +## :hackney_pools + +Advanced. Tweaks Hackney (http client) connections pools. + +There's three pools used: + +* `:federation` for the federation jobs. + You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs. +* `:media` for rich media, media proxy +* `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`) + +For each pool, the options are: + +* `max_connections` - how much connections a pool can hold +* `timeout` - retention duration for connections + +## :auto_linker + +Configuration for the `auto_linker` library: + +* `class: "auto-linker"` - specify the class to be added to the generated link. false to clear +* `rel: "noopener noreferrer"` - override the rel attribute. false to clear +* `new_window: true` - set to false to remove `target='_blank'` attribute +* `scheme: false` - Set to true to link urls with schema `http://google.com` +* `truncate: false` - Set to a number to truncate urls longer then the number. Truncated urls will end in `..` +* `strip_prefix: true` - Strip the scheme prefix +* `extra: false` - link urls with rarely used schemes (magnet, ipfs, irc, etc.) + +Example: + +```elixir +config :auto_linker, + opts: [ + scheme: true, + extra: true, + class: false, + strip_prefix: false, + new_window: false, + rel: "ugc" + ] +``` + +## Pleroma.Scheduler + +Configuration for [Quantum](https://github.com/quantum-elixir/quantum-core) jobs scheduler. + +See [Quantum readme](https://github.com/quantum-elixir/quantum-core#usage) for the list of supported options. + +Example: + +```elixir +config :pleroma, Pleroma.Scheduler, + global: true, + overlap: true, + timezone: :utc, + jobs: [{"0 */6 * * * *", {Pleroma.Web.Websub, :refresh_subscriptions, []}}] +``` + +The above example defines a single job which invokes `Pleroma.Web.Websub.refresh_subscriptions()` every 6 hours ("0 */6 * * * *", [crontab format](https://en.wikipedia.org/wiki/Cron)). + +## Pleroma.ScheduledActivity + +* `daily_user_limit`: the number of scheduled activities a user is allowed to create in a single day (Default: `25`) +* `total_user_limit`: the number of scheduled activities a user is allowed to create in total (Default: `300`) +* `enabled`: whether scheduled activities are sent to the job queue to be executed + +## Pleroma.ActivityExpiration + +# `enabled`: whether expired activities will be sent to the job queue to be deleted + +## Pleroma.Web.Auth.Authenticator + +* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator +* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication + +## :ldap + +Use LDAP for user authentication. When a user logs in to the Pleroma +instance, the name and password will be verified by trying to authenticate +(bind) to an LDAP server. If a user exists in the LDAP directory but there +is no account with the same name yet on the Pleroma instance then a new +Pleroma account will be created with the same name as the LDAP user name. + +* `enabled`: enables LDAP authentication +* `host`: LDAP server hostname +* `port`: LDAP port, e.g. 389 or 636 +* `ssl`: true to use SSL, usually implies the port 636 +* `sslopts`: additional SSL options +* `tls`: true to start TLS, usually implies the port 389 +* `tlsopts`: additional TLS options +* `base`: LDAP base, e.g. "dc=example,dc=com" +* `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base" + +## BBS / SSH access + +To enable simple command line interface accessible over ssh, add a setting like this to your configuration file: + +```exs +app_dir = File.cwd! +priv_dir = Path.join([app_dir, "priv/ssh_keys"]) + +config :esshd, + enabled: true, + priv_dir: priv_dir, + handler: "Pleroma.BBS.Handler", + port: 10_022, + password_authenticator: "Pleroma.BBS.Authenticator" +``` + +Feel free to adjust the priv_dir and port number. Then you will have to create the key for the keys (in the example `priv/ssh_keys`) and create the host keys with `ssh-keygen -m PEM -N "" -b 2048 -t rsa -f ssh_host_rsa_key`. After restarting, you should be able to connect to your Pleroma instance with `ssh username@server -p $PORT` + +## :auth + +* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator +* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication + +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`. +* `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. Each entry in this space-delimited string should be of format `` or `:` (e.g. `twitter` or `keycloak:ueberauth_keycloak_strategy` in case dependency is named differently than `ueberauth_`). + +## :email_notifications + +Email notifications settings. + + - digest - emails of "what you've missed" for users who have been + inactive for a while. + - active: globally enable or disable digest emails + - schedule: When to send digest email, in [crontab format](https://en.wikipedia.org/wiki/Cron). + "0 0 * * 0" is the default, meaning "once a week at midnight on Sunday morning" + - interval: Minimum interval between digest emails to one user + - inactivity_threshold: Minimum user inactivity threshold + +## Pleroma.Emails.UserEmail + +- `:logo` - a path to a custom logo. Set it to `nil` to use the default Pleroma logo. +- `:styling` - a map with color settings for email templates. + +## OAuth consumer mode + +OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.). +Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies). + +Note: each strategy is shipped as a separate dependency; in order to get the strategies, run `OAUTH_CONSUMER_STRATEGIES="..." mix deps.get`, +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: 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:///oauth/twitter/callback + +* For Facebook, [register an app](https://developers.facebook.com/apps), configure callback URL to https:///oauth/facebook/callback, enable Facebook Login service at https://developers.facebook.com/apps//fb-login/settings/ + +* For Google, [register an app](https://console.developers.google.com), configure callback URL to https:///oauth/google/callback + +* For Microsoft, [register an app](https://portal.azure.com), configure callback URL to https:///oauth/microsoft/callback + +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"), + consumer_secret: System.get_env("TWITTER_CONSUMER_SECRET") + +# Facebook +config :ueberauth, Ueberauth.Strategy.Facebook.OAuth, + client_id: System.get_env("FACEBOOK_APP_ID"), + client_secret: System.get_env("FACEBOOK_APP_SECRET"), + redirect_uri: System.get_env("FACEBOOK_REDIRECT_URI") + +# Google +config :ueberauth, Ueberauth.Strategy.Google.OAuth, + client_id: System.get_env("GOOGLE_CLIENT_ID"), + client_secret: System.get_env("GOOGLE_CLIENT_SECRET"), + redirect_uri: System.get_env("GOOGLE_REDIRECT_URI") + +# Microsoft +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: []]} + ] + +# Keycloak +# Note: make sure to add `keycloak:ueberauth_keycloak_strategy` entry to `OAUTH_CONSUMER_STRATEGIES` environment variable +keycloak_url = "https://publicly-reachable-keycloak-instance.org:8080" + +config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth, + client_id: System.get_env("KEYCLOAK_CLIENT_ID"), + client_secret: System.get_env("KEYCLOAK_CLIENT_SECRET"), + site: keycloak_url, + authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth", + token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token", + userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo", + token_method: :post + +config :ueberauth, Ueberauth, + providers: [ + keycloak: {Ueberauth.Strategy.Keycloak, [uid_field: :email]} + ] +``` + +## OAuth 2.0 provider - :oauth2 + +Configure OAuth 2 provider capabilities: + +* `token_expires_in` - The lifetime in seconds of the access token. +* `issue_new_refresh_token` - Keeps old refresh token or generate new refresh token when to obtain an access token. +* `clean_expired_tokens` - Enable a background job to clean expired oauth tokens. Defaults to `false`. +* `clean_expired_tokens_interval` - Interval to run the job to clean expired tokens. Defaults to `86_400_000` (24 hours). + +## :emoji +* `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]` +* `pack_extensions`: A list of file extensions for emojis, when no emoji.txt for a pack is present. Example `[".png", ".gif"]` +* `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). +* `shared_pack_cache_seconds_per_file`: When an emoji pack is shared, the archive is created and cached in + memory for this amount of seconds multiplied by the number of files. + +## Database options + +### RUM indexing for full text search +* `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. + +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. + +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/` + +This will probably take a long time. + +## :rate_limit + +This is an advanced feature and disabled by default. + +If your instance is behind a reverse proxy you must enable and configure [`Pleroma.Plugs.RemoteIp`](#pleroma-plugs-remoteip). + +A keyword list of rate limiters where a key is a limiter name and value is the limiter configuration. The basic configuration is a tuple where: + +* The first element: `scale` (Integer). The time scale in milliseconds. +* The second element: `limit` (Integer). How many requests to limit in the time scale provided. + +It is also possible to have different limits for unauthenticated and authenticated users: the keyword value must be a list of two tuples where the first one is a config for unauthenticated users and the second one is for authenticated. + +See [`Pleroma.Plugs.RateLimiter`](Pleroma.Plugs.RateLimiter.html) documentation for examples. + +Supported rate limiters: + +* `:search` for the search requests (account & status search etc.) +* `:app_account_creation` for registering user accounts from the same IP address +* `:relations_actions` for actions on relations with all users (follow, unfollow) +* `:relation_id_action` for actions on relation with a specific user (follow, unfollow) +* `:statuses_actions` for create / delete / fav / unfav / reblog / unreblog actions on any statuses +* `:status_id_action` for fav / unfav or reblog / unreblog actions on the same status by the same user + +## :web_cache_ttl + +The expiration time for the web responses cache. Values should be in milliseconds or `nil` to disable expiration. + +Available caches: + +* `:activity_pub` - activity pub routes (except question activities). Defaults to `nil` (no expiration). +* `:activity_pub_question` - activity pub routes (question activities). Defaults to `30_000` (30 seconds). + +## Pleroma.Plugs.RemoteIp + +**If your instance is not behind at least one reverse proxy, you should not enable this plug.** + +`Pleroma.Plugs.RemoteIp` is a shim to call [`RemoteIp`](https://git.pleroma.social/pleroma/remote_ip) but with runtime configuration. + +Available options: + +* `enabled` - Enable/disable the plug. Defaults to `false`. +* `headers` - A list of strings naming the `req_headers` to use when deriving the `remote_ip`. Order does not matter. Defaults to `~w[forwarded x-forwarded-for x-client-ip x-real-ip]`. +* `proxies` - A list of strings in [CIDR](https://en.wikipedia.org/wiki/CIDR) notation specifying the IPs of known proxies. Defaults to `[]`. +* `reserved` - Defaults to [localhost](https://en.wikipedia.org/wiki/Localhost) and [private network](https://en.wikipedia.org/wiki/Private_network). diff --git a/docs/configuration/config.md b/docs/configuration/config.md deleted file mode 100644 index 262d15bba..000000000 --- a/docs/configuration/config.md +++ /dev/null @@ -1,773 +0,0 @@ -# Configuration - -This file describe the configuration, it is recommended to edit the relevant *.secret.exs file instead of the others founds in the ``config`` directory. -If you run Pleroma with ``MIX_ENV=prod`` the file is ``prod.secret.exs``, otherwise it is ``dev.secret.exs``. - -## Pleroma.Upload -* `uploader`: Select which `Pleroma.Uploaders` to use -* `filters`: List of `Pleroma.Upload.Filter` to use. -* `link_name`: When enabled Pleroma will add a `name` parameter to the url of the upload, for example `https://instance.tld/media/corndog.png?name=corndog.png`. This is needed to provide the correct filename in Content-Disposition headers when using filters like `Pleroma.Upload.Filter.Dedupe` -* `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host. -* `proxy_remote`: If you're using a remote uploader, Pleroma will proxy media requests instead of redirecting to it. -* `proxy_opts`: Proxy options, see `Pleroma.ReverseProxy` documentation. - -Note: `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`. - -## Pleroma.Uploaders.Local -* `uploads`: Which directory to store the user-uploads in, relative to pleroma’s working directory - -## Pleroma.Uploaders.S3 -* `bucket`: S3 bucket name -* `bucket_namespace`: S3 bucket namespace -* `public_endpoint`: S3 endpoint that the user finally accesses(ex. "https://s3.dualstack.ap-northeast-1.amazonaws.com") -* `truncated_namespace`: If you use S3 compatible service such as Digital Ocean Spaces or CDN, set folder name or "" etc. -For example, when using CDN to S3 virtual host format, set "". -At this time, write CNAME to CDN in public_endpoint. -* `streaming_enabled`: Enable streaming uploads, when enabled the file will be sent to the server in chunks as it's being read. This may be unsupported by some providers, try disabling this if you have upload problems. - -## Pleroma.Upload.Filter.Mogrify - -* `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"implode", "1"}]`. - -## Pleroma.Upload.Filter.Dedupe - -No specific configuration. - -## Pleroma.Upload.Filter.AnonymizeFilename - -This filter replaces the filename (not the path) of an upload. For complete obfuscation, add -`Pleroma.Upload.Filter.Dedupe` before AnonymizeFilename. - -* `text`: Text to replace filenames in links. If empty, `{random}.extension` will be used. You can get the original filename extension by using `{extension}`, for example `custom-file-name.{extension}`. - -## 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. -* `enabled`: Allows enable/disable send emails. Default: `false`. - -An example for Sendgrid adapter: - -```elixir -config :pleroma, Pleroma.Emails.Mailer, - adapter: Swoosh.Adapters.Sendgrid, - api_key: "YOUR_API_KEY" -``` - -An example for SMTP adapter: - -```elixir -config :pleroma, Pleroma.Emails.Mailer, - adapter: Swoosh.Adapters.SMTP, - relay: "smtp.gmail.com", - username: "YOUR_USERNAME@gmail.com", - password: "YOUR_SMTP_PASSWORD", - port: 465, - ssl: true, - tls: :always, - auth: :always -``` - -## :uri_schemes -* `valid_schemes`: List of the scheme part that is considered valid to be an URL - -## :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. -* `upload_limit`: File size limit of uploads (except for avatar, background, banner) -* `avatar_upload_limit`: File size limit of user’s profile avatars -* `background_upload_limit`: File size limit of user’s profile backgrounds -* `banner_upload_limit`: File size limit of user’s profile banners -* `poll_limits`: A map with poll limits for **local** polls - * `max_options`: Maximum number of options - * `max_option_chars`: Maximum number of characters per option - * `min_expiration`: Minimum expiration time (in seconds) - * `max_expiration`: Maximum expiration time (in seconds) -* `registrations_open`: Enable registrations for anyone, invitations can be enabled when false. -* `invites_enabled`: Enable user invitations for admins (depends on `registrations_open: false`). -* `account_activation_required`: Require users to confirm their emails before signing in. -* `federating`: Enable federation with other instances -* `federation_incoming_replies_max_depth`: Max. depth of reply-to activities fetching on incoming federation, to prevent out-of-memory situations while fetching very long threads. If set to `nil`, threads of any depth will be fetched. Lower this value if you experience out-of-memory crashes. -* `federation_reachability_timeout_days`: Timeout (in days) of each external federation target being unreachable prior to pausing federating to it. -* `allow_relay`: Enable Pleroma’s Relay, which makes it possible to follow a whole instance -* `rewrite_policy`: Message Rewrite Policy, either one or a list. Here are the ones available by default: - * `Pleroma.Web.ActivityPub.MRF.NoOpPolicy`: Doesn’t modify activities (default) - * `Pleroma.Web.ActivityPub.MRF.DropPolicy`: Drops all activities. It generally doesn’t makes sense to use in production - * `Pleroma.Web.ActivityPub.MRF.SimplePolicy`: Restrict the visibility of activities from certains instances (See ``:mrf_simple`` section) - * `Pleroma.Web.ActivityPub.MRF.TagPolicy`: Applies policies to individual users based on tags, which can be set using pleroma-fe/admin-fe/any other app that supports Pleroma Admin API. For example it allows marking posts from individual users nsfw (sensitive) - * `Pleroma.Web.ActivityPub.MRF.SubchainPolicy`: Selectively runs other MRF policies when messages match (see ``:mrf_subchain`` section) - * `Pleroma.Web.ActivityPub.MRF.RejectNonPublic`: Drops posts with non-public visibility settings (See ``:mrf_rejectnonpublic`` section) - * `Pleroma.Web.ActivityPub.MRF.EnsureRePrepended`: Rewrites posts to ensure that replies to posts with subjects do not have an identical subject and instead begin with re:. - * `Pleroma.Web.ActivityPub.MRF.AntiLinkSpamPolicy`: Rejects posts from likely spambots by rejecting posts from new users that contain links. - * `Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy`: Crawls attachments using their MediaProxy URLs so that the MediaProxy cache is primed. - * `Pleroma.Web.ActivityPub.MRF.MentionPolicy`: Drops posts mentioning configurable users. (see `:mrf_mention` section) - * `Pleroma.Web.ActivityPub.MRF.VocabularyPolicy`: Restricts activities to a configured set of vocabulary. (see `:mrf_vocabulary` section) -* `public`: Makes the client API in authentificated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network. -* `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) -* `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). -* `mrf_transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. -* `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: - * "email": Copy and preprend re:, as in email. - * "masto": Copy verbatim, as in Mastodon. - * "noop": Don't copy the subject. -* `always_show_subject_input`: When set to false, auto-hide the subject field when it's empty. -* `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with - older software for theses nicknames. -* `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature. -* `autofollowed_nicknames`: Set to nicknames of (local) users that every new user should automatically follow. -* `no_attachment_links`: Set to true to disable automatically adding attachment link text to statuses -* `welcome_message`: A message that will be send to a newly registered users as a direct message. -* `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``. -* `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database. -* `user_bio_length`: A user bio maximum length (default: `5000`) -* `user_name_length`: A user name maximum length (default: `100`) -* `skip_thread_containment`: Skip filter out broken threads. The default is `false`. -* `limit_to_local_content`: Limit unauthenticated users to search for local statutes and users only. Possible values: `:unauthenticated`, `:all` and `false`. The default is `:unauthenticated`. -* `dynamic_configuration`: Allow transferring configuration to DB with the subsequent customization from Admin api. -* `max_account_fields`: The maximum number of custom fields in the user profile (default: `10`) -* `max_remote_account_fields`: The maximum number of custom fields in the remote user profile (default: `20`) -* `account_field_name_length`: An account field name maximum length (default: `512`) -* `account_field_value_length`: An account field value maximum length (default: `2048`) -* `external_user_synchronization`: Enabling following/followers counters synchronization for external users. - - - -## :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}] - -config :logger, :ex_syslogger, - level: :warn -``` - -Another example, keeping console output and adding the pid to syslog output: -```elixir -config :logger, - backends: [:console, {ExSyslogger, :ex_syslogger}] - -config :logger, :ex_syslogger, - level: :warn, - option: [:pid, :ndelay] -``` - -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 - -config :logger, :ex_syslogger, - level: :info, - ident: "pleroma", - format: "$metadata[$level] $message" - -config :quack, - level: :warn, - meta: [:all], - webhook_url: "https://hooks.slack.com/services/YOUR-API-KEY-HERE" -``` - -See the [Quack Github](https://github.com/azohra/quack) for more details - -## :frontend_configurations - -This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. - -Frontends can access these settings at `/api/pleroma/frontend_configurations` - -To add your own configuration for PleromaFE, use it like this: - -```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. - -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`](#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. - -* `theme`: Which theme to use, they are defined in ``styles.json`` -* `logo`: URL of the logo, defaults to Pleroma’s logo -* `logo_mask`: Whether to use only the logo's shape as a mask (true) or as a regular image (false) -* `logo_margin`: What margin to use around the logo -* `background`: URL of the background, unless viewing a user profile with a background that is set -* `redirect_root_no_login`: relative URL which indicates where to redirect when a user isn’t logged in. -* `redirect_root_login`: relative URL which indicates where to redirect when a user is logged in. -* `show_instance_panel`: Whenether to show the instance’s specific panel. -* `scope_options_enabled`: Enable setting an notice visibility and subject/CW when posting -* `formatting_options_enabled`: Enable setting a formatting different than plain-text (ie. HTML, Markdown) when posting, relates to ``:instance, allowed_post_formats`` -* `collapse_message_with_subjects`: When a message has a subject(aka Content Warning), collapse it by default -* `hide_post_stats`: Hide notices statistics(repeats, favorites, …) -* `hide_user_stats`: Hide profile statistics(posts, posts per day, followers, followings, …) - -## :assets - -This section configures assets to be used with various frontends. Currently the only option -relates to mascots on the mastodon frontend - -* `mascots`: KeywordList of mascots, each element __MUST__ contain both a `url` and a - `mime_type` key. -* `default_mascot`: An element from `mascots` - This will be used as the default mascot - on MastoFE (default: `:pleroma_fox_tan`) - -## :mrf_simple -* `media_removal`: List of instances to remove medias from -* `media_nsfw`: List of instances to put medias as NSFW(sensitive) from -* `federated_timeline_removal`: List of instances to remove from Federated (aka The Whole Known Network) Timeline -* `reject`: List of instances to reject any activities from -* `accept`: List of instances to accept any activities from -* `report_removal`: List of instances to reject reports from -* `avatar_removal`: List of instances to strip avatars from -* `banner_removal`: List of instances to strip banners from - -## :mrf_subchain -This policy processes messages through an alternate pipeline when a given message matches certain criteria. -All criteria are configured as a map of regular expressions to lists of policy modules. - -* `match_actor`: Matches a series of regular expressions against the actor field. - -Example: - -``` -config :pleroma, :mrf_subchain, - match_actor: %{ - ~r/https:\/\/example.com/s => [Pleroma.Web.ActivityPub.MRF.DropPolicy] - } -``` - -## :mrf_rejectnonpublic -* `allow_followersonly`: whether to allow followers-only posts -* `allow_direct`: whether to allow direct messages - -## :mrf_hellthread -* `delist_threshold`: Number of mentioned users after which the message gets delisted (the message can still be seen, but it will not show up in public timelines and mentioned users won't get notifications about it). Set to 0 to disable. -* `reject_threshold`: Number of mentioned users after which the messaged gets rejected. Set to 0 to disable. - -## :mrf_keyword -* `reject`: A list of patterns which result in message being rejected, each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) -* `federated_timeline_removal`: A list of patterns which result in message being removed from federated timelines (a.k.a unlisted), each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) -* `replace`: A list of tuples containing `{pattern, replacement}`, `pattern` can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html) - -## :mrf_mention -* `actors`: A list of actors, for which to drop any posts mentioning. - -## :mrf_vocabulary -* `accept`: A list of ActivityStreams terms to accept. If empty, all supported messages are accepted. -* `reject`: A list of ActivityStreams terms to reject. If empty, no messages are rejected. - -## :media_proxy -* `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 -* `ip`: IP address to bind to -* `port`: Port to bind to -* `dstport`: Port advertised in urls (optional, defaults to `port`) - -## Pleroma.Web.Endpoint -`Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here -* `http` - a list containing http protocol configuration, all configuration options can be viewed [here](https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html#module-options), only common options are listed here. For deployment using docker, you need to set this to `[ip: {0,0,0,0}, port: 4000]` to make pleroma accessible from other containers (such as your nginx server). - - `ip` - a tuple consisting of 4 integers - - `port` -* `url` - a list containing the configuration for generating urls, accepts - - `host` - the host without the scheme and a post (e.g `example.com`, not `https://example.com:2020`) - - `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 - -Example: -```elixir -config :pleroma, Pleroma.Web.Endpoint, - url: [host: "example.com", port: 2020, scheme: "https"], - http: [ - # start copied from config.exs - dispatch: [ - {:_, - [ - {"/api/v1/streaming", Pleroma.Web.MastodonAPI.WebsocketHandler, []}, - {"/websocket", Phoenix.Endpoint.CowboyWebSocket, - {Phoenix.Transports.WebSocket, - {Pleroma.Web.Endpoint, Pleroma.Web.UserSocket, websocket_config}}}, - {:_, Phoenix.Endpoint.Cowboy2Handler, {Pleroma.Web.Endpoint, []}} - ]} - # end copied from config.exs - ], - port: 8080, - ip: {127, 0, 0, 1} - ] -``` - -This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls starting with `https://example.com:2020` - -## :activitypub -* ``unfollow_blocked``: Whether blocks result in people getting unfollowed -* ``outgoing_blocks``: Whether to federate blocks to other instances -* ``deny_follow_blocked``: Whether to disallow following an account that has blocked the user in question -* ``sign_object_fetches``: Sign object fetches with HTTP signatures - -## :http_security -* ``enabled``: Whether the managed content security policy is enabled -* ``sts``: Whether to additionally send a `Strict-Transport-Security` header -* ``sts_max_age``: The maximum age for the `Strict-Transport-Security` header if sent -* ``ct_max_age``: The maximum age for the `Expect-CT` header if sent -* ``referrer_policy``: The referrer policy to use, either `"same-origin"` or `"no-referrer"` -* ``report_uri``: Adds the specified url to `report-uri` and `report-to` group in CSP header. - -## :mrf_user_allowlist - -The keys in this section are the domain names that the policy should apply to. -Each key should be assigned a list of users that should be allowed through by -their ActivityPub ID. - -An example: - -```elixir -config :pleroma, :mrf_user_allowlist, - "example.org": ["https://example.org/users/admin"] -``` - -## :web_push_encryption, :vapid_details - -Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it. - -* ``subject``: a mailto link for the administrative contact. It’s best if this email is not a personal email address, but rather a group email so that if a person leaves an organization, is unavailable for an extended period, or otherwise can’t respond, someone else on the list can. -* ``public_key``: VAPID public key -* ``private_key``: VAPID private key - -## Pleroma.Captcha -* `enabled`: Whether the captcha should be shown on registration -* `method`: The method/service to use for captcha -* `seconds_valid`: The time in seconds for which the captcha is valid - -### Pleroma.Captcha.Kocaptcha -Kocaptcha is a very simple captcha service with a single API endpoint, -the source code is here: https://github.com/koto-bank/kocaptcha. The default endpoint -`https://captcha.kotobank.ch` is hosted by the developer. - -* `endpoint`: the kocaptcha endpoint to use - -## :admin_token - -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: - -```elixir -config :pleroma, :admin_token, "somerandomtoken" -``` - -You can then do - -```sh -curl "http://localhost:4000/api/pleroma/admin/invite_token?admin_token=somerandomtoken" -``` - -## Oban - -[Oban](https://github.com/sorentwo/oban) asynchronous job processor configuration. - -Configuration options described in [Oban readme](https://github.com/sorentwo/oban#usage): -* `repo` - app's Ecto repo (`Pleroma.Repo`) -* `verbose` - logs verbosity -* `prune` - non-retryable jobs [pruning settings](https://github.com/sorentwo/oban#pruning) (`:disabled` / `{:maxlen, value}` / `{:maxage, value}`) -* `queues` - job queues (see below) - -Pleroma has the following queues: - -* `activity_expiration` - Activity expiration -* `federator_outgoing` - Outgoing federation -* `federator_incoming` - Incoming federation -* `mailer` - Email sender, see [`Pleroma.Emails.Mailer`](#pleromaemailsmailer) -* `transmogrifier` - Transmogrifier -* `web_push` - Web push notifications -* `scheduled_activities` - Scheduled activities, see [`Pleroma.ScheduledActivity`](#pleromascheduledactivity) - -Example: - -```elixir -config :pleroma, Oban, - repo: Pleroma.Repo, - verbose: false, - prune: {:maxlen, 1500}, - queues: [ - federator_incoming: 50, - federator_outgoing: 50 - ] -``` - -This config contains two queues: `federator_incoming` and `federator_outgoing`. Both have the number of max concurrent jobs set to `50`. - -### Migrating `pleroma_job_queue` settings - -`config :pleroma_job_queue, :queues` is replaced by `config :pleroma, Oban, :queues` and uses the same format (keys are queues' names, values are max concurrent jobs numbers). - -### Note on running with PostgreSQL in silent mode - -If you are running PostgreSQL in [`silent_mode`](https://postgresqlco.nf/en/doc/param/silent_mode?version=9.1), it's advised to set [`log_destination`](https://postgresqlco.nf/en/doc/param/log_destination?version=9.1) to `syslog`, -otherwise `postmaster.log` file may grow because of "you don't own a lock of type ShareLock" warnings (see https://github.com/sorentwo/oban/issues/52). - -## :workers - -Includes custom worker options not interpretable directly by `Oban`. - -* `retries` — keyword lists where keys are `Oban` queues (see above) and values are numbers of max attempts for failed jobs. - -Example: - -```elixir -config :pleroma, :workers, - retries: [ - federator_incoming: 5, - federator_outgoing: 5 - ] -``` - -### Migrating `Pleroma.Web.Federator.RetryQueue` settings - -* `max_retries` is replaced with `config :pleroma, :workers, retries: [federator_outgoing: 5]` -* `enabled: false` corresponds to `config :pleroma, :workers, retries: [federator_outgoing: 1]` -* deprecated options: `max_jobs`, `initial_timeout` - -## Pleroma.Web.Metadata -* `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 `
` as `` -* `unfurl_nsfw`: If set to `true` nsfw attachments will be shown in previews - -## :rich_media -* `enabled`: if enabled the instance will parse metadata from attached links to generate link previews -* `ignore_hosts`: list of hosts which will be ignored by the metadata parser. For example `["accounts.google.com", "xss.website"]`, defaults to `[]`. -* `ignore_tld`: list TLDs (top-level domains) which will ignore for parse metadata. default is ["local", "localdomain", "lan"] -* `parsers`: list of Rich Media parsers - -## :fetch_initial_posts -* `enabled`: if enabled, when a new user is federated with, fetch some of their latest posts -* `pages`: the amount of pages to fetch - -## :hackney_pools - -Advanced. Tweaks Hackney (http client) connections pools. - -There's three pools used: - -* `:federation` for the federation jobs. - You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs. -* `:media` for rich media, media proxy -* `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`) - -For each pool, the options are: - -* `max_connections` - how much connections a pool can hold -* `timeout` - retention duration for connections - -## :auto_linker - -Configuration for the `auto_linker` library: - -* `class: "auto-linker"` - specify the class to be added to the generated link. false to clear -* `rel: "noopener noreferrer"` - override the rel attribute. false to clear -* `new_window: true` - set to false to remove `target='_blank'` attribute -* `scheme: false` - Set to true to link urls with schema `http://google.com` -* `truncate: false` - Set to a number to truncate urls longer then the number. Truncated urls will end in `..` -* `strip_prefix: true` - Strip the scheme prefix -* `extra: false` - link urls with rarely used schemes (magnet, ipfs, irc, etc.) - -Example: - -```elixir -config :auto_linker, - opts: [ - scheme: true, - extra: true, - class: false, - strip_prefix: false, - new_window: false, - rel: "ugc" - ] -``` - -## Pleroma.Scheduler - -Configuration for [Quantum](https://github.com/quantum-elixir/quantum-core) jobs scheduler. - -See [Quantum readme](https://github.com/quantum-elixir/quantum-core#usage) for the list of supported options. - -Example: - -```elixir -config :pleroma, Pleroma.Scheduler, - global: true, - overlap: true, - timezone: :utc, - jobs: [{"0 */6 * * * *", {Pleroma.Web.Websub, :refresh_subscriptions, []}}] -``` - -The above example defines a single job which invokes `Pleroma.Web.Websub.refresh_subscriptions()` every 6 hours ("0 */6 * * * *", [crontab format](https://en.wikipedia.org/wiki/Cron)). - -## Pleroma.ScheduledActivity - -* `daily_user_limit`: the number of scheduled activities a user is allowed to create in a single day (Default: `25`) -* `total_user_limit`: the number of scheduled activities a user is allowed to create in total (Default: `300`) -* `enabled`: whether scheduled activities are sent to the job queue to be executed - -## Pleroma.ActivityExpiration - -# `enabled`: whether expired activities will be sent to the job queue to be deleted - -## Pleroma.Web.Auth.Authenticator - -* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator -* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication - -## :ldap - -Use LDAP for user authentication. When a user logs in to the Pleroma -instance, the name and password will be verified by trying to authenticate -(bind) to an LDAP server. If a user exists in the LDAP directory but there -is no account with the same name yet on the Pleroma instance then a new -Pleroma account will be created with the same name as the LDAP user name. - -* `enabled`: enables LDAP authentication -* `host`: LDAP server hostname -* `port`: LDAP port, e.g. 389 or 636 -* `ssl`: true to use SSL, usually implies the port 636 -* `sslopts`: additional SSL options -* `tls`: true to start TLS, usually implies the port 389 -* `tlsopts`: additional TLS options -* `base`: LDAP base, e.g. "dc=example,dc=com" -* `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base" - -## BBS / SSH access - -To enable simple command line interface accessible over ssh, add a setting like this to your configuration file: - -```exs -app_dir = File.cwd! -priv_dir = Path.join([app_dir, "priv/ssh_keys"]) - -config :esshd, - enabled: true, - priv_dir: priv_dir, - handler: "Pleroma.BBS.Handler", - port: 10_022, - password_authenticator: "Pleroma.BBS.Authenticator" -``` - -Feel free to adjust the priv_dir and port number. Then you will have to create the key for the keys (in the example `priv/ssh_keys`) and create the host keys with `ssh-keygen -m PEM -N "" -b 2048 -t rsa -f ssh_host_rsa_key`. After restarting, you should be able to connect to your Pleroma instance with `ssh username@server -p $PORT` - -## :auth - -* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator -* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication - -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`. -* `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. Each entry in this space-delimited string should be of format `` or `:` (e.g. `twitter` or `keycloak:ueberauth_keycloak_strategy` in case dependency is named differently than `ueberauth_`). - -## :email_notifications - -Email notifications settings. - - - digest - emails of "what you've missed" for users who have been - inactive for a while. - - active: globally enable or disable digest emails - - schedule: When to send digest email, in [crontab format](https://en.wikipedia.org/wiki/Cron). - "0 0 * * 0" is the default, meaning "once a week at midnight on Sunday morning" - - interval: Minimum interval between digest emails to one user - - inactivity_threshold: Minimum user inactivity threshold - -## Pleroma.Emails.UserEmail - -- `:logo` - a path to a custom logo. Set it to `nil` to use the default Pleroma logo. -- `:styling` - a map with color settings for email templates. - -## OAuth consumer mode - -OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.). -Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies). - -Note: each strategy is shipped as a separate dependency; in order to get the strategies, run `OAUTH_CONSUMER_STRATEGIES="..." mix deps.get`, -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: 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:///oauth/twitter/callback - -* For Facebook, [register an app](https://developers.facebook.com/apps), configure callback URL to https:///oauth/facebook/callback, enable Facebook Login service at https://developers.facebook.com/apps//fb-login/settings/ - -* For Google, [register an app](https://console.developers.google.com), configure callback URL to https:///oauth/google/callback - -* For Microsoft, [register an app](https://portal.azure.com), configure callback URL to https:///oauth/microsoft/callback - -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"), - consumer_secret: System.get_env("TWITTER_CONSUMER_SECRET") - -# Facebook -config :ueberauth, Ueberauth.Strategy.Facebook.OAuth, - client_id: System.get_env("FACEBOOK_APP_ID"), - client_secret: System.get_env("FACEBOOK_APP_SECRET"), - redirect_uri: System.get_env("FACEBOOK_REDIRECT_URI") - -# Google -config :ueberauth, Ueberauth.Strategy.Google.OAuth, - client_id: System.get_env("GOOGLE_CLIENT_ID"), - client_secret: System.get_env("GOOGLE_CLIENT_SECRET"), - redirect_uri: System.get_env("GOOGLE_REDIRECT_URI") - -# Microsoft -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: []]} - ] - -# Keycloak -# Note: make sure to add `keycloak:ueberauth_keycloak_strategy` entry to `OAUTH_CONSUMER_STRATEGIES` environment variable -keycloak_url = "https://publicly-reachable-keycloak-instance.org:8080" - -config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth, - client_id: System.get_env("KEYCLOAK_CLIENT_ID"), - client_secret: System.get_env("KEYCLOAK_CLIENT_SECRET"), - site: keycloak_url, - authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth", - token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token", - userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo", - token_method: :post - -config :ueberauth, Ueberauth, - providers: [ - keycloak: {Ueberauth.Strategy.Keycloak, [uid_field: :email]} - ] -``` - -## OAuth 2.0 provider - :oauth2 - -Configure OAuth 2 provider capabilities: - -* `token_expires_in` - The lifetime in seconds of the access token. -* `issue_new_refresh_token` - Keeps old refresh token or generate new refresh token when to obtain an access token. -* `clean_expired_tokens` - Enable a background job to clean expired oauth tokens. Defaults to `false`. -* `clean_expired_tokens_interval` - Interval to run the job to clean expired tokens. Defaults to `86_400_000` (24 hours). - -## :emoji -* `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]` -* `pack_extensions`: A list of file extensions for emojis, when no emoji.txt for a pack is present. Example `[".png", ".gif"]` -* `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). -* `shared_pack_cache_seconds_per_file`: When an emoji pack is shared, the archive is created and cached in - memory for this amount of seconds multiplied by the number of files. - -## Database options - -### RUM indexing for full text search -* `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. - -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. - -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/` - -This will probably take a long time. - -## :rate_limit - -This is an advanced feature and disabled by default. - -If your instance is behind a reverse proxy you must enable and configure [`Pleroma.Plugs.RemoteIp`](#pleroma-plugs-remoteip). - -A keyword list of rate limiters where a key is a limiter name and value is the limiter configuration. The basic configuration is a tuple where: - -* The first element: `scale` (Integer). The time scale in milliseconds. -* The second element: `limit` (Integer). How many requests to limit in the time scale provided. - -It is also possible to have different limits for unauthenticated and authenticated users: the keyword value must be a list of two tuples where the first one is a config for unauthenticated users and the second one is for authenticated. - -See [`Pleroma.Plugs.RateLimiter`](Pleroma.Plugs.RateLimiter.html) documentation for examples. - -Supported rate limiters: - -* `:search` for the search requests (account & status search etc.) -* `:app_account_creation` for registering user accounts from the same IP address -* `:relations_actions` for actions on relations with all users (follow, unfollow) -* `:relation_id_action` for actions on relation with a specific user (follow, unfollow) -* `:statuses_actions` for create / delete / fav / unfav / reblog / unreblog actions on any statuses -* `:status_id_action` for fav / unfav or reblog / unreblog actions on the same status by the same user - -## :web_cache_ttl - -The expiration time for the web responses cache. Values should be in milliseconds or `nil` to disable expiration. - -Available caches: - -* `:activity_pub` - activity pub routes (except question activities). Defaults to `nil` (no expiration). -* `:activity_pub_question` - activity pub routes (question activities). Defaults to `30_000` (30 seconds). - -## Pleroma.Plugs.RemoteIp - -**If your instance is not behind at least one reverse proxy, you should not enable this plug.** - -`Pleroma.Plugs.RemoteIp` is a shim to call [`RemoteIp`](https://git.pleroma.social/pleroma/remote_ip) but with runtime configuration. - -Available options: - -* `enabled` - Enable/disable the plug. Defaults to `false`. -* `headers` - A list of strings naming the `req_headers` to use when deriving the `remote_ip`. Order does not matter. Defaults to `~w[forwarded x-forwarded-for x-client-ip x-real-ip]`. -* `proxies` - A list of strings in [CIDR](https://en.wikipedia.org/wiki/CIDR) notation specifying the IPs of known proxies. Defaults to `[]`. -* `reserved` - Defaults to [localhost](https://en.wikipedia.org/wiki/Localhost) and [private network](https://en.wikipedia.org/wiki/Private_network). -- cgit v1.2.3 From 838ff12ec5d930bbd0caa472ea602ce665370bbc Mon Sep 17 00:00:00 2001 From: rinpatch Date: Wed, 2 Oct 2019 23:58:57 +0300 Subject: Remove "General tips for customizing Pleroma FE" because it's no longer relevant and we have actual fe docs now --- .../General-tips-for-customizing-Pleroma-FE.md | 17 ----------------- 1 file changed, 17 deletions(-) delete mode 100644 docs/configuration/General-tips-for-customizing-Pleroma-FE.md diff --git a/docs/configuration/General-tips-for-customizing-Pleroma-FE.md b/docs/configuration/General-tips-for-customizing-Pleroma-FE.md deleted file mode 100644 index 15c4882dd..000000000 --- a/docs/configuration/General-tips-for-customizing-Pleroma-FE.md +++ /dev/null @@ -1,17 +0,0 @@ -# General tips for customizing Pleroma FE -There are some configuration scripts for Pleroma BE and FE: - -1. `config/prod.secret.exs` -1. `config/config.exs` -1. `priv/static/static/config.json` - -The `prod.secret.exs` affects first. `config.exs` is for fallback or default. `config.json` is for GNU-social-BE-Pleroma-FE instances. - -Usually all you have to do is: - -1. Copy the section in the `config/config.exs` which you want to activate. -1. Paste into `config/prod.secret.exs`. -1. Edit `config/prod.secret.exs`. -1. Restart the Pleroma daemon. - -`prod.secret.exs` is for the `MIX_ENV=prod` environment. `dev.secret.exs` is for the `MIX_ENV=dev` environment respectively. -- cgit v1.2.3 From 74d682a09ecaacb9f784e27cf0e815ddf81511f6 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 00:00:53 +0300 Subject: Remove Small customizations as it's contents have been integrated into static_dir.md --- docs/configuration/small_customizations.md | 12 ------------ 1 file changed, 12 deletions(-) delete mode 100644 docs/configuration/small_customizations.md diff --git a/docs/configuration/small_customizations.md b/docs/configuration/small_customizations.md deleted file mode 100644 index f91657a4c..000000000 --- a/docs/configuration/small_customizations.md +++ /dev/null @@ -1,12 +0,0 @@ -# Small customizations - -See also static_dir.md for visual settings. - -## Theme - -All users of your instance will be able to change the theme they use by going to the settings (the cog in the top-right hand corner). However, if you wish to change the default theme, you can do so by editing `theme` in `config/dev.secret.exs` accordingly. - -## Message Visibility - -To enable message visibility options when posting like in the Mastodon frontend, set -`scope_options_enabled` to `true` in `config/dev.secret.exs`. -- cgit v1.2.3 From b8e5e46fa8c15d0bf3f98c5704e994ffe82be35c Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 00:18:32 +0300 Subject: Fix references to other pages --- docs/installation/alpine_linux_en.md | 10 ++++------ docs/installation/arch_linux_en.md | 10 ++++------ docs/installation/centos7_en.md | 10 ++++------ docs/installation/debian_based_en.md | 10 ++++------ docs/installation/debian_based_jp.md | 10 ++++------ docs/installation/gentoo_en.md | 10 ++++------ docs/installation/migrating_from_source_otp_en.md | 10 +++++----- docs/installation/otp_en.md | 10 +++++----- 8 files changed, 34 insertions(+), 46 deletions(-) diff --git a/docs/installation/alpine_linux_en.md b/docs/installation/alpine_linux_en.md index f200362ca..f5d1fade1 100644 --- a/docs/installation/alpine_linux_en.md +++ b/docs/installation/alpine_linux_en.md @@ -225,12 +225,10 @@ sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new Date: Thu, 3 Oct 2019 00:22:14 +0300 Subject: Fix more links --- docs/API/pleroma_api.md | 2 +- docs/installation/otp_en.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index 41889a0ef..3a8ef4e2c 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -124,7 +124,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi ``` ## `/api/pleroma/admin/`… -See [Admin-API](Admin-API.md) +See [Admin-API](admin_api.md) ## `/api/v1/pleroma/notifications/read` ### Mark notifications as read diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index f192c0cb1..b4e5254cd 100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -42,7 +42,7 @@ apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot ## Setup ### Configuring PostgreSQL #### (Optional) Installing RUM indexes -RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. You can read more about them on the [Configuration page](config.html#rum-indexing-for-full-text-search). They are completely optional and most of the time are not worth it, especially if you are running a single user instance (unless you absolutely need ordered search results). +RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. You can read more about them on the [Configuration page](../configuration/cheatsheet.md#rum-indexing-for-full-text-search). They are completely optional and most of the time are not worth it, especially if you are running a single user instance (unless you absolutely need ordered search results). Debian/Ubuntu (available only on Buster/19.04): ```sh -- cgit v1.2.3 From 2767c413fb385580acc010dafa9282e4dcaecb60 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 00:36:18 +0300 Subject: Remove a reference to inline docs since everything it describes is described in the cheatsheet already and add A TODO --- docs/configuration/cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index fd936aed7..35274c61b 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -743,7 +743,7 @@ A keyword list of rate limiters where a key is a limiter name and value is the l It is also possible to have different limits for unauthenticated and authenticated users: the keyword value must be a list of two tuples where the first one is a config for unauthenticated users and the second one is for authenticated. -See [`Pleroma.Plugs.RateLimiter`](Pleroma.Plugs.RateLimiter.html) documentation for examples. +TODO: Add a list of available limiters Supported rate limiters: -- cgit v1.2.3 From bd9c7807fbf21402cc0444c711c40677ca5de2a0 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 01:03:47 +0300 Subject: Move emoji task docs to a separate file --- docs/administration/CLI_tasks/emoji.md | 33 +++++++++++++++++++++++ lib/mix/tasks/pleroma/emoji.ex | 48 ---------------------------------- 2 files changed, 33 insertions(+), 48 deletions(-) create mode 100644 docs/administration/CLI_tasks/emoji.md diff --git a/docs/administration/CLI_tasks/emoji.md b/docs/administration/CLI_tasks/emoji.md new file mode 100644 index 000000000..5b8dc11ab --- /dev/null +++ b/docs/administration/CLI_tasks/emoji.md @@ -0,0 +1,33 @@ +# Managing emoji packs + +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl emoji` and in case of source installs it's `mix pleroma.emoji`. + +## ls-packs + +```sh +$PREFIX ls-packs [OPTION...] +``` + +Lists the emoji packs and metadata specified in the manifest. + +### Options +- `-m, --manifest PATH/URL` - path to a custom manifest, it can either be an URL starting with `http`, in that case the manifest will be fetched from that address, or a local path + +## get-packs +```sh +$PREFIX get-packs [OPTION...] PACKS +``` +Fetches, verifies and installs the specified PACKS from the manifest into the `STATIC-DIR/emoji/PACK-NAME` + +### Options +- `-m, --manifest PATH/URL` - same as [`ls-packs`](#ls-packs) + +## gen-pack +```sh +$PREFIX gen-pack PACK-URL +``` +Creates a new manifest entry and a file list from the specified remote pack file. Currently, only .zip archives are recognized as remote pack files and packs are therefore assumed to be zip archives. This command is intended to run interactively and will first ask you some basic questions about the pack, then download the remote file and generate an SHA256 checksum for it, then generate an emoji file list for you. + + The manifest entry will either be written to a newly created `index.json` file or appended to the existing one, *replacing* the old pack with the same name if it was in the file previously. + + The file list will be written to the file specified previously, *replacing* that file. You _should_ check that the file list doesn't contain anything you don't need in the pack, that is, anything that is not an emoji (the whole pack is downloaded, but only emoji files are extracted). diff --git a/lib/mix/tasks/pleroma/emoji.ex b/lib/mix/tasks/pleroma/emoji.ex index 881a6f725..32b92e6af 100644 --- a/lib/mix/tasks/pleroma/emoji.ex +++ b/lib/mix/tasks/pleroma/emoji.ex @@ -6,54 +6,6 @@ defmodule Mix.Tasks.Pleroma.Emoji do use Mix.Task @shortdoc "Manages emoji packs" - @moduledoc """ - Manages emoji packs - - ## ls-packs - - mix pleroma.emoji ls-packs [OPTION...] - - Lists the emoji packs and metadata specified in the manifest. - - ### Options - - - `-m, --manifest PATH/URL` - path to a custom manifest, it can - either be an URL starting with `http`, in that case the - manifest will be fetched from that address, or a local path - - ## get-packs - - mix pleroma.emoji get-packs [OPTION...] PACKS - - Fetches, verifies and installs the specified PACKS from the - manifest into the `STATIC-DIR/emoji/PACK-NAME` - - ### Options - - - `-m, --manifest PATH/URL` - same as ls-packs - - ## gen-pack - - mix pleroma.emoji gen-pack PACK-URL - - Creates a new manifest entry and a file list from the specified - remote pack file. Currently, only .zip archives are recognized - as remote pack files and packs are therefore assumed to be zip - archives. This command is intended to run interactively and will - first ask you some basic questions about the pack, then download - the remote file and generate an SHA256 checksum for it, then - generate an emoji file list for you. - - The manifest entry will either be written to a newly created - `index.json` file or appended to the existing one, *replacing* - the old pack with the same name if it was in the file previously. - - The file list will be written to the file specified previously, - *replacing* that file. You _should_ check that the file list doesn't - contain anything you don't need in the pack, that is, anything that is - not an emoji (the whole pack is downloaded, but only emoji files - are extracted). - """ def run(["ls-packs" | args]) do Application.ensure_all_started(:hackney) -- cgit v1.2.3 From 869ea2ab90bb461ad3dd06ac974f227da369fcf8 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 01:09:51 +0300 Subject: Move digest email docs to a separate file and improve styling --- docs/administration/CLI_tasks/digest.md | 15 +++++++++++++++ docs/administration/CLI_tasks/emoji.md | 6 +++--- lib/mix/tasks/pleroma/digest.ex | 9 --------- 3 files changed, 18 insertions(+), 12 deletions(-) create mode 100644 docs/administration/CLI_tasks/digest.md diff --git a/docs/administration/CLI_tasks/digest.md b/docs/administration/CLI_tasks/digest.md new file mode 100644 index 000000000..89b3ed237 --- /dev/null +++ b/docs/administration/CLI_tasks/digest.md @@ -0,0 +1,15 @@ +# Managing digest emails +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl digest` and in case of source installs it's `mix pleroma.digest`. + +## `test` + +```sh +$PREFIX test +``` + +Send digest email since given date (user registration date by default) ignoring user activity status. + +Example: +```sh +$PREFIX test donaldtheduck 2019-05-20 +``` diff --git a/docs/administration/CLI_tasks/emoji.md b/docs/administration/CLI_tasks/emoji.md index 5b8dc11ab..39216a897 100644 --- a/docs/administration/CLI_tasks/emoji.md +++ b/docs/administration/CLI_tasks/emoji.md @@ -2,7 +2,7 @@ Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl emoji` and in case of source installs it's `mix pleroma.emoji`. -## ls-packs +## `ls-packs` ```sh $PREFIX ls-packs [OPTION...] @@ -13,7 +13,7 @@ Lists the emoji packs and metadata specified in the manifest. ### Options - `-m, --manifest PATH/URL` - path to a custom manifest, it can either be an URL starting with `http`, in that case the manifest will be fetched from that address, or a local path -## get-packs +## `get-packs` ```sh $PREFIX get-packs [OPTION...] PACKS ``` @@ -22,7 +22,7 @@ Fetches, verifies and installs the specified PACKS from the manifest into the `S ### Options - `-m, --manifest PATH/URL` - same as [`ls-packs`](#ls-packs) -## gen-pack +## `gen-pack` ```sh $PREFIX gen-pack PACK-URL ``` diff --git a/lib/mix/tasks/pleroma/digest.ex b/lib/mix/tasks/pleroma/digest.ex index 430116a50..100a81060 100644 --- a/lib/mix/tasks/pleroma/digest.ex +++ b/lib/mix/tasks/pleroma/digest.ex @@ -2,16 +2,7 @@ defmodule Mix.Tasks.Pleroma.Digest do use Mix.Task @shortdoc "Manages digest emails" - @moduledoc """ - Manages digest emails - ## Send digest email since given date (user registration date by default) - ignoring user activity status. - - ``mix pleroma.digest test `` - - Example: ``mix pleroma.digest test donaldtheduck 2019-05-20`` - """ def run(["test", nickname | opts]) do Mix.Pleroma.start_pleroma() -- cgit v1.2.3 From a54739a530a291483893b0c334d35fb893026a2a Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 08:51:57 +0300 Subject: Improve styling of CLI tasks --- docs/administration/CLI_tasks/digest.md | 6 ++---- docs/administration/CLI_tasks/emoji.md | 15 ++++++--------- 2 files changed, 8 insertions(+), 13 deletions(-) diff --git a/docs/administration/CLI_tasks/digest.md b/docs/administration/CLI_tasks/digest.md index 89b3ed237..547702031 100644 --- a/docs/administration/CLI_tasks/digest.md +++ b/docs/administration/CLI_tasks/digest.md @@ -1,14 +1,12 @@ # Managing digest emails Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl digest` and in case of source installs it's `mix pleroma.digest`. -## `test` +## Send digest email since given date (user registration date by default) ignoring user activity status. ```sh -$PREFIX test +$PREFIX test [] ``` -Send digest email since given date (user registration date by default) ignoring user activity status. - Example: ```sh $PREFIX test donaldtheduck 2019-05-20 diff --git a/docs/administration/CLI_tasks/emoji.md b/docs/administration/CLI_tasks/emoji.md index 39216a897..d274953eb 100644 --- a/docs/administration/CLI_tasks/emoji.md +++ b/docs/administration/CLI_tasks/emoji.md @@ -2,31 +2,28 @@ Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl emoji` and in case of source installs it's `mix pleroma.emoji`. -## `ls-packs` +## Lists the emoji packs and metadata specified in the manifest. ```sh -$PREFIX ls-packs [OPTION...] +$PREFIX ls-packs [] ``` -Lists the emoji packs and metadata specified in the manifest. - ### Options - `-m, --manifest PATH/URL` - path to a custom manifest, it can either be an URL starting with `http`, in that case the manifest will be fetched from that address, or a local path -## `get-packs` +## Fetch, verify and install the specified packs from the manifest into `STATIC-DIR/emoji/PACK-NAME` ```sh -$PREFIX get-packs [OPTION...] PACKS +$PREFIX get-packs [] ``` -Fetches, verifies and installs the specified PACKS from the manifest into the `STATIC-DIR/emoji/PACK-NAME` ### Options - `-m, --manifest PATH/URL` - same as [`ls-packs`](#ls-packs) -## `gen-pack` +## Create a new manifest entry and a file list from the specified remote pack file ```sh $PREFIX gen-pack PACK-URL ``` -Creates a new manifest entry and a file list from the specified remote pack file. Currently, only .zip archives are recognized as remote pack files and packs are therefore assumed to be zip archives. This command is intended to run interactively and will first ask you some basic questions about the pack, then download the remote file and generate an SHA256 checksum for it, then generate an emoji file list for you. +Currently, only .zip archives are recognized as remote pack files and packs are therefore assumed to be zip archives. This command is intended to run interactively and will first ask you some basic questions about the pack, then download the remote file and generate an SHA256 checksum for it, then generate an emoji file list for you. The manifest entry will either be written to a newly created `index.json` file or appended to the existing one, *replacing* the old pack with the same name if it was in the file previously. -- cgit v1.2.3 From 6435ba83cd07162a9ad9a386253814e2f12d951d Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 09:02:48 +0300 Subject: Move instance CLI task docs to a text file --- docs/administration/CLI_tasks/emoji.md | 2 +- docs/administration/CLI_tasks/instance.md | 30 ++++++++++++++++++++++++++++++ lib/mix/tasks/pleroma/instance.ex | 30 ------------------------------ 3 files changed, 31 insertions(+), 31 deletions(-) create mode 100644 docs/administration/CLI_tasks/instance.md diff --git a/docs/administration/CLI_tasks/emoji.md b/docs/administration/CLI_tasks/emoji.md index d274953eb..eee02f2ef 100644 --- a/docs/administration/CLI_tasks/emoji.md +++ b/docs/administration/CLI_tasks/emoji.md @@ -2,7 +2,7 @@ Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl emoji` and in case of source installs it's `mix pleroma.emoji`. -## Lists the emoji packs and metadata specified in the manifest. +## Lists emoji packs and metadata specified in the manifest ```sh $PREFIX ls-packs [] diff --git a/docs/administration/CLI_tasks/instance.md b/docs/administration/CLI_tasks/instance.md new file mode 100644 index 000000000..975ee61d9 --- /dev/null +++ b/docs/administration/CLI_tasks/instance.md @@ -0,0 +1,30 @@ +# Managing instance configuration + +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl instance` and in case of source installs it's `mix pleroma.instance`. + +## Generate a new configuration file +```sh +$PREFIX gen [] +``` + +If any of the options are left unspecified, you will be prompted interactively. + +## Options +- `-f`, `--force` - overwrite any output files +- `-o `, `--output ` - the output file for the generated configuration +- `--output-psql ` - the output file for the generated PostgreSQL setup +- `--domain ` - the domain of your instance +- `--instance-name ` - the name of your instance +- `--admin-email ` - the email address of the instance admin +- `--notify-email ` - email address for notifications +- `--dbhost ` - the hostname of the PostgreSQL database to use +- `--dbname ` - the name of the database to use +- `--dbuser ` - the user (aka role) to use for the database connection +- `--dbpass ` - the password to use for the database connection +- `--rum ` - Whether to enable RUM indexes +- `--indexable ` - Allow/disallow indexing site by search engines +- `--db-configurable ` - Allow/disallow configuring instance from admin part +- `--uploads-dir ` - the directory uploads go in when using a local uploader +- `--static-dir ` - the directory custom public files should be read from (custom emojis, frontend bundle overrides, robots.txt, etc.) +- `--listen-ip ` - the ip the app should listen to, defaults to 127.0.0.1 +- `--listen-port ` - the port the app should listen to, defaults to 4000 diff --git a/lib/mix/tasks/pleroma/instance.ex b/lib/mix/tasks/pleroma/instance.ex index 1a1634fe9..25f94eceb 100644 --- a/lib/mix/tasks/pleroma/instance.ex +++ b/lib/mix/tasks/pleroma/instance.ex @@ -7,36 +7,6 @@ defmodule Mix.Tasks.Pleroma.Instance do import Mix.Pleroma @shortdoc "Manages Pleroma instance" - @moduledoc """ - Manages Pleroma instance. - - ## Generate a new instance config. - - mix pleroma.instance gen [OPTION...] - - If any options are left unspecified, you will be prompted interactively - - ## Options - - - `-f`, `--force` - overwrite any output files - - `-o PATH`, `--output PATH` - the output file for the generated configuration - - `--output-psql PATH` - the output file for the generated PostgreSQL setup - - `--domain DOMAIN` - the domain of your instance - - `--instance-name INSTANCE_NAME` - the name of your instance - - `--admin-email ADMIN_EMAIL` - the email address of the instance admin - - `--notify-email NOTIFY_EMAIL` - email address for notifications - - `--dbhost HOSTNAME` - the hostname of the PostgreSQL database to use - - `--dbname DBNAME` - the name of the database to use - - `--dbuser DBUSER` - the user (aka role) to use for the database connection - - `--dbpass DBPASS` - the password to use for the database connection - - `--rum Y/N` - Whether to enable RUM indexes - - `--indexable Y/N` - Allow/disallow indexing site by search engines - - `--db-configurable Y/N` - Allow/disallow configuring instance from admin part - - `--uploads-dir` - the directory uploads go in when using a local uploader - - `--static-dir` - the directory custom public files should be read from (custom emojis, frontend bundle overrides, robots.txt, etc.) - - `--listen-ip` - the ip the app should listen to, defaults to 127.0.0.1 - - `--listen-port` - the port the app should listen to, defaults to 4000 - """ def run(["gen" | rest]) do {options, [], []} = -- cgit v1.2.3 From 808d0a0170577155d0f1097c66c4e0b23c8303b9 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 09:10:31 +0300 Subject: Move relay docs to a separate file --- docs/administration/CLI_tasks/relay.md | 30 ++++++++++++++++++++++++++++++ lib/mix/tasks/pleroma/relay.ex | 18 ------------------ 2 files changed, 30 insertions(+), 18 deletions(-) create mode 100644 docs/administration/CLI_tasks/relay.md diff --git a/docs/administration/CLI_tasks/relay.md b/docs/administration/CLI_tasks/relay.md new file mode 100644 index 000000000..aa44617df --- /dev/null +++ b/docs/administration/CLI_tasks/relay.md @@ -0,0 +1,30 @@ +# Managing relays + +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl relay` and in case of source installs it's `mix pleroma.relay`. + +## Follow a relay +```sh +$PREFIX follow +``` + +Example: +```sh +$PREFIX follow https://example.org/relay +``` + +## Unfollow a remote relay + +```sh +$PREFIX unfollow +``` + +Example: +```sh +$PREFIX unfollow https://example.org/relay +``` + +## List relay subscriptions + +```sh +$PREFIX list +``` diff --git a/lib/mix/tasks/pleroma/relay.ex b/lib/mix/tasks/pleroma/relay.ex index 200721163..519f2d1b5 100644 --- a/lib/mix/tasks/pleroma/relay.ex +++ b/lib/mix/tasks/pleroma/relay.ex @@ -9,25 +9,7 @@ defmodule Mix.Tasks.Pleroma.Relay do alias Pleroma.Web.ActivityPub.Relay @shortdoc "Manages remote relays" - @moduledoc """ - Manages remote relays - ## Follow a remote relay - - ``mix pleroma.relay follow `` - - Example: ``mix pleroma.relay follow https://example.org/relay`` - - ## Unfollow a remote relay - - ``mix pleroma.relay unfollow `` - - Example: ``mix pleroma.relay unfollow https://example.org/relay`` - - ## List relay subscriptions - - ``mix pleroma.relay list`` - """ def run(["follow", target]) do start_pleroma() -- cgit v1.2.3 From d39ccc2e7ffd019f8fe2438f388c0a0bb8aac34a Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 09:35:21 +0300 Subject: Move uploads task docs to a separate file --- docs/administration/CLI_tasks/uploads.md | 12 ++++++++++++ lib/mix/tasks/pleroma/uploads.ex | 9 --------- 2 files changed, 12 insertions(+), 9 deletions(-) create mode 100644 docs/administration/CLI_tasks/uploads.md diff --git a/docs/administration/CLI_tasks/uploads.md b/docs/administration/CLI_tasks/uploads.md new file mode 100644 index 000000000..a72bbd01f --- /dev/null +++ b/docs/administration/CLI_tasks/uploads.md @@ -0,0 +1,12 @@ +# Managing uploads + +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl uploads` and in case of source installs it's `mix pleroma.uploads`. + +## Migrate uploads from local to remote storage +```sh +$PREFIX migrate_local TARGET_UPLOADER [OPTIONS...] +``` +## Options +- `--delete` - delete local uploads after migrating them to the target uploader + +A list of available uploaders can be seen in [Configuration Cheat Sheet](../../configuration/cheatsheet.md#pleromaupload) diff --git a/lib/mix/tasks/pleroma/uploads.ex b/lib/mix/tasks/pleroma/uploads.ex index 95392d81b..bc2248a76 100644 --- a/lib/mix/tasks/pleroma/uploads.ex +++ b/lib/mix/tasks/pleroma/uploads.ex @@ -12,16 +12,7 @@ defmodule Mix.Tasks.Pleroma.Uploads do @log_every 50 @shortdoc "Migrates uploads from local to remote storage" - @moduledoc """ - Manages uploads - ## Migrate uploads from local to remote storage - mix pleroma.uploads migrate_local TARGET_UPLOADER [OPTIONS...] - Options: - - `--delete` - delete local uploads after migrating them to the target uploader - - A list of available uploaders can be seen in config.exs - """ def run(["migrate_local", target_uploader | args]) do delete? = Enum.member?(args, "--delete") start_pleroma() -- cgit v1.2.3 From f5372bfb4a65c8324926965fe34c920bc2449bc5 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 09:36:35 +0300 Subject: Fix up some headings --- docs/administration/CLI_tasks/instance.md | 2 +- docs/administration/CLI_tasks/uploads.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/administration/CLI_tasks/instance.md b/docs/administration/CLI_tasks/instance.md index 975ee61d9..ab0b68ad0 100644 --- a/docs/administration/CLI_tasks/instance.md +++ b/docs/administration/CLI_tasks/instance.md @@ -9,7 +9,7 @@ $PREFIX gen [] If any of the options are left unspecified, you will be prompted interactively. -## Options +### Options - `-f`, `--force` - overwrite any output files - `-o `, `--output ` - the output file for the generated configuration - `--output-psql ` - the output file for the generated PostgreSQL setup diff --git a/docs/administration/CLI_tasks/uploads.md b/docs/administration/CLI_tasks/uploads.md index a72bbd01f..321ec5e74 100644 --- a/docs/administration/CLI_tasks/uploads.md +++ b/docs/administration/CLI_tasks/uploads.md @@ -6,7 +6,7 @@ Every command should be ran with a prefix, in case of OTP releases it is `./bin/ ```sh $PREFIX migrate_local TARGET_UPLOADER [OPTIONS...] ``` -## Options +### Options - `--delete` - delete local uploads after migrating them to the target uploader A list of available uploaders can be seen in [Configuration Cheat Sheet](../../configuration/cheatsheet.md#pleromaupload) -- cgit v1.2.3 From 8fd47a4a5a9704a523046e7b8d2cdac3f090acea Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 09:38:24 +0300 Subject: Use consistent command signature --- docs/administration/CLI_tasks/uploads.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administration/CLI_tasks/uploads.md b/docs/administration/CLI_tasks/uploads.md index 321ec5e74..71800e341 100644 --- a/docs/administration/CLI_tasks/uploads.md +++ b/docs/administration/CLI_tasks/uploads.md @@ -4,7 +4,7 @@ Every command should be ran with a prefix, in case of OTP releases it is `./bin/ ## Migrate uploads from local to remote storage ```sh -$PREFIX migrate_local TARGET_UPLOADER [OPTIONS...] +$PREFIX migrate_local [] ``` ### Options - `--delete` - delete local uploads after migrating them to the target uploader -- cgit v1.2.3 From b4ca864c6b2e6ee9addea7fbc0b09fca581816ce Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:15:24 +0300 Subject: Move user tasks docs to a separate file --- docs/administration/CLI_tasks/user.md | 94 +++++++++++++++++++++++++++++++++++ lib/mix/tasks/pleroma/user.ex | 79 ----------------------------- 2 files changed, 94 insertions(+), 79 deletions(-) create mode 100644 docs/administration/CLI_tasks/user.md diff --git a/docs/administration/CLI_tasks/user.md b/docs/administration/CLI_tasks/user.md new file mode 100644 index 000000000..045730753 --- /dev/null +++ b/docs/administration/CLI_tasks/user.md @@ -0,0 +1,94 @@ +# Managing users + +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl user` and in case of source installs it's `mix pleroma.user`. + +## Create a user +```sh +$PREFIX new [] +``` + +### Options +- `--name ` - the user's display name +- `--bio ` - the user's bio +- `--password ` - the user's password +- `--moderator`/`--no-moderator` - whether the user should be a moderator +- `--admin`/`--no-admin` - whether the user should be an admin +- `-y`, `--assume-yes`/`--no-assume-yes` - whether to assume yes to all questions + +## Generate an invite link +```sh +$PREFIX invite [] +``` + +### Options +- `--expires-at DATE` - last day on which token is active (e.g. "2019-04-05") +- `--max-use NUMBER` - maximum numbers of token uses + +## List generated invites +```sh +$PREFIX invites +``` + +## Revoke invite +```sh +$PREFIX revoke_invite +``` + +## Delete a user +``` +$PREFIX rm +``` + +## Delete user's posts and interactions +```sh +$PREFIX delete_activities +``` + +## Sign user out from all applications (delete user's OAuth tokens and authorizations) +```sh +$PREFIX sign_out +``` + +## Deactivate or activate a user +```sh +$PREFIX toggle_activated +``` + +## Unsubscribe local users from a user and deactivate the user +```sh +$PREFIX unsubscribe NICKNAME +``` + +## Unsubscribe local users from an instance and deactivate all accounts on it +```sh +$PREFIX unsubscribe_all_from_instance +``` + +## Create a password reset link for user +```sh +$PREFIX reset_password +``` + +## Set the value of the given user's settings +```sh +$PREFIX set [] +``` +### Options +- `--locked`/`--no-locked` - whether the user should be locked +- `--moderator`/`--no-moderator` - whether the user should be a moderator +- `--admin`/`--no-admin` - whether the user should be an admin + +## Add tags to a user +```sh +$PREFIX tag +``` + +## Delete tags from a user +```sh +$PREFIX untag +``` + +## Toggle confirmation status of the user +```sh +$PREFIX toggle_confirmed +``` diff --git a/lib/mix/tasks/pleroma/user.ex b/lib/mix/tasks/pleroma/user.ex index d93ba8dee..3cf3ad2c6 100644 --- a/lib/mix/tasks/pleroma/user.ex +++ b/lib/mix/tasks/pleroma/user.ex @@ -10,86 +10,7 @@ defmodule Mix.Tasks.Pleroma.User do alias Pleroma.Web.OAuth @shortdoc "Manages Pleroma users" - @moduledoc """ - Manages Pleroma users. - ## Create a new user. - - mix pleroma.user new NICKNAME EMAIL [OPTION...] - - Options: - - `--name NAME` - the user's name (i.e., "Lain Iwakura") - - `--bio BIO` - the user's bio - - `--password PASSWORD` - the user's password - - `--moderator`/`--no-moderator` - whether the user is a moderator - - `--admin`/`--no-admin` - whether the user is an admin - - `-y`, `--assume-yes`/`--no-assume-yes` - whether to assume yes to all questions - - ## Generate an invite link. - - mix pleroma.user invite [OPTION...] - - Options: - - `--expires-at DATE` - last day on which token is active (e.g. "2019-04-05") - - `--max-use NUMBER` - maximum numbers of token uses - - ## List generated invites - - mix pleroma.user invites - - ## Revoke invite - - mix pleroma.user revoke_invite TOKEN OR TOKEN_ID - - ## Delete the user's account. - - mix pleroma.user rm NICKNAME - - ## Delete the user's activities. - - mix pleroma.user delete_activities NICKNAME - - ## Sign user out from all applications (delete user's OAuth tokens and authorizations). - - mix pleroma.user sign_out NICKNAME - - ## Deactivate or activate the user's account. - - mix pleroma.user toggle_activated NICKNAME - - ## Unsubscribe local users from user's account and deactivate it - - mix pleroma.user unsubscribe NICKNAME - - ## Unsubscribe local users from an entire instance and deactivate all accounts - - mix pleroma.user unsubscribe_all_from_instance INSTANCE - - ## Create a password reset link. - - mix pleroma.user reset_password NICKNAME - - ## Set the value of the given user's settings. - - mix pleroma.user set NICKNAME [OPTION...] - - Options: - - `--locked`/`--no-locked` - whether the user's account is locked - - `--moderator`/`--no-moderator` - whether the user is a moderator - - `--admin`/`--no-admin` - whether the user is an admin - - ## Add tags to a user. - - mix pleroma.user tag NICKNAME TAGS - - ## Delete tags from a user. - - mix pleroma.user untag NICKNAME TAGS - - ## Toggle confirmation of the user's account. - - mix pleroma.user toggle_confirmed NICKNAME - """ def run(["new", nickname, email | rest]) do {options, [], []} = OptionParser.parse( -- cgit v1.2.3 From 2cbe2dcbde9346fd354de816ea660b3ab085d876 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:31:59 +0300 Subject: Oops --- docs/configuration/cheatsheet.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 35274c61b..35832e606 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -743,8 +743,6 @@ A keyword list of rate limiters where a key is a limiter name and value is the l It is also possible to have different limits for unauthenticated and authenticated users: the keyword value must be a list of two tuples where the first one is a config for unauthenticated users and the second one is for authenticated. -TODO: Add a list of available limiters - Supported rate limiters: * `:search` for the search requests (account & status search etc.) -- cgit v1.2.3 From 66450f861597ac5c5a349f005b7cc061e4e34ded Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:36:01 +0300 Subject: Cheatsheet: Move the deprecated config warning into a warning block --- docs/configuration/cheatsheet.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 35832e606..f1d41b0c6 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -212,14 +212,15 @@ These settings **need to be complete**, they will override the defaults. NOTE: for versions < 1.0, you need to set [`:fe`](#fe) to false, as shown a few lines below. ## :fe -__THIS IS DEPRECATED__ +!!! warning + __THIS IS DEPRECATED__ -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: + 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 -``` + ```elixir + config :pleroma, :fe, false + ``` This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:instance`` is set to false. -- cgit v1.2.3 From cb162678df877e3f9b299e10516d0ebd29355b80 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:37:34 +0300 Subject: Add missing language spec --- docs/configuration/cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index f1d41b0c6..82367ae0b 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -266,7 +266,7 @@ All criteria are configured as a map of regular expressions to lists of policy m Example: -``` +```elixir config :pleroma, :mrf_subchain, match_actor: %{ ~r/https:\/\/example.com/s => [Pleroma.Web.ActivityPub.MRF.DropPolicy] -- cgit v1.2.3 From 4e70009490365f0439043aa59f9e6cd05f6da723 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:39:53 +0300 Subject: Move bold text in RemoveIp description into a proper warning --- docs/configuration/cheatsheet.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 82367ae0b..57325dd56 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -764,7 +764,8 @@ Available caches: ## Pleroma.Plugs.RemoteIp -**If your instance is not behind at least one reverse proxy, you should not enable this plug.** +!!! warning + If your instance is not behind at least one reverse proxy, you should not enable this plug. `Pleroma.Plugs.RemoteIp` is a shim to call [`RemoteIp`](https://git.pleroma.social/pleroma/remote_ip) but with runtime configuration. -- cgit v1.2.3 From 25849157aae60e1bac776d395cadb6d15424eb1d Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:43:38 +0300 Subject: Remove fe settings from :instance as they no longer do anything --- docs/configuration/cheatsheet.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 57325dd56..e23bcaf63 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -115,12 +115,6 @@ config :pleroma, Pleroma.Emails.Mailer, * `allowed_post_formats`: MIME-type list of formats allowed to be posted (transformed into HTML) * `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). * `mrf_transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. -* `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: - * "email": Copy and preprend re:, as in email. - * "masto": Copy verbatim, as in Mastodon. - * "noop": Don't copy the subject. -* `always_show_subject_input`: When set to false, auto-hide the subject field when it's empty. * `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with older software for theses nicknames. * `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature. -- cgit v1.2.3 From e560d65db3c6e2692a8060b0646d6e8808b864f0 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:45:40 +0300 Subject: Fix a typo in activity expirations --- docs/configuration/cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index e23bcaf63..e5f68f09b 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -551,7 +551,7 @@ The above example defines a single job which invokes `Pleroma.Web.Websub.refresh ## Pleroma.ActivityExpiration -# `enabled`: whether expired activities will be sent to the job queue to be deleted +* `enabled`: whether expired activities will be sent to the job queue to be deleted ## Pleroma.Web.Auth.Authenticator -- cgit v1.2.3 From aefb4dcff5721aaa20ebb52d4f7da4874cb1b612 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:54:41 +0300 Subject: Cheatsheet: Use note/warning blocks instead of bold text --- docs/configuration/cheatsheet.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index e5f68f09b..70a475363 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -15,7 +15,8 @@ You shouldn't edit the base config directly to avoid breakages and merge conflic * `proxy_remote`: If you're using a remote uploader, Pleroma will proxy media requests instead of redirecting to it. * `proxy_opts`: Proxy options, see `Pleroma.ReverseProxy` documentation. -Note: `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`. +!!! warning + `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`. ## Pleroma.Uploaders.Local * `uploads`: Which directory to store the user-uploads in, relative to pleroma’s working directory @@ -300,7 +301,10 @@ config :pleroma, :mrf_subchain, * `dstport`: Port advertised in urls (optional, defaults to `port`) ## Pleroma.Web.Endpoint -`Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here + +!!! note + `Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here. + * `http` - a list containing http protocol configuration, all configuration options can be viewed [here](https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html#module-options), only common options are listed here. For deployment using docker, you need to set this to `[ip: {0,0,0,0}, port: 4000]` to make pleroma accessible from other containers (such as your nginx server). - `ip` - a tuple consisting of 4 integers - `port` @@ -313,7 +317,8 @@ config :pleroma, :mrf_subchain, -**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 +!!! warning + 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 Example: ```elixir @@ -627,13 +632,14 @@ Email notifications settings. OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.). Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies). -Note: each strategy is shipped as a separate dependency; in order to get the strategies, run `OAUTH_CONSUMER_STRATEGIES="..." mix deps.get`, -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 is shipped as a separate dependency; in order to get the strategies, run `OAUTH_CONSUMER_STRATEGIES="..." mix deps.get`, 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"` +!!! 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:///oauth/twitter/callback -- cgit v1.2.3 From 2656f418183d0109a1706a78a2517b61e12871c7 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 10:57:27 +0300 Subject: Remove silent mode note as it's no longer relevant --- docs/configuration/cheatsheet.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 70a475363..9e5368cf1 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -444,11 +444,6 @@ This config contains two queues: `federator_incoming` and `federator_outgoing`. `config :pleroma_job_queue, :queues` is replaced by `config :pleroma, Oban, :queues` and uses the same format (keys are queues' names, values are max concurrent jobs numbers). -### Note on running with PostgreSQL in silent mode - -If you are running PostgreSQL in [`silent_mode`](https://postgresqlco.nf/en/doc/param/silent_mode?version=9.1), it's advised to set [`log_destination`](https://postgresqlco.nf/en/doc/param/log_destination?version=9.1) to `syslog`, -otherwise `postmaster.log` file may grow because of "you don't own a lock of type ShareLock" warnings (see https://github.com/sorentwo/oban/issues/52). - ## :workers Includes custom worker options not interpretable directly by `Oban`. -- cgit v1.2.3 From 8e08d5b2336bdb6108ec5df15b7b642e0bc2acad Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 11:02:07 +0300 Subject: MkDocs does not like if a paragraph doesn't have a newline after it --- docs/configuration/custom_emoji.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/configuration/custom_emoji.md b/docs/configuration/custom_emoji.md index f72c0edbc..1648840fd 100644 --- a/docs/configuration/custom_emoji.md +++ b/docs/configuration/custom_emoji.md @@ -4,6 +4,7 @@ Before you add your own custom emoji, check if they are available in an existing See `Mix.Tasks.Pleroma.Emoji` for information about emoji packs. To add custom emoji: + * 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). -- cgit v1.2.3 From 6baa037903e06c80a5b5f1c34b2cfdd471ba2f8f Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 11:17:29 +0300 Subject: Move database maintenance tasks docs to a separate file --- docs/administration/CLI_tasks/database.md | 48 +++++++++++++++++++++++++++++++ lib/mix/tasks/pleroma/database.ex | 27 ----------------- 2 files changed, 48 insertions(+), 27 deletions(-) create mode 100644 docs/administration/CLI_tasks/database.md diff --git a/docs/administration/CLI_tasks/database.md b/docs/administration/CLI_tasks/database.md new file mode 100644 index 000000000..484639231 --- /dev/null +++ b/docs/administration/CLI_tasks/database.md @@ -0,0 +1,48 @@ +# Database maintenance tasks + +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl database` and in case of source installs it's `mix pleroma.database`. + +## Replace embedded objects with their references + +Replaces embedded objects with references to them in the `objects` table. Only needs to be ran once if the instance was created before Pleroma 1.0.5. The reason why this is not a migration is because it could significantly increase the database size after being ran, however after this `VACUUM FULL` will be able to reclaim about 20% (really depends on what is in the database, your mileage may vary) of the db size before the migration. + +```sh +$PREFIX remove_embedded_objects [] +``` + +### Options +- `--vacuum` - run `VACUUM FULL` after the embedded objects are replaced with their references + +## Prune old remote posts from the database + +This will prune remote posts older than 90 days (configurable with [`config :pleroma, :instance, remote_post_retention_days`](../../configuration/cheatsheet.md#instance)) from the database, they will be refetched from source when accessed. + +!!! note + The disk space will only be reclaimed after `VACUUM FULL` + +```sh +$PREFIX pleroma.database prune_objects [] +``` + +### Options +- `--vacuum` - run `VACUUM FULL` after the objects are pruned + +## Create a conversation for all existing DMs + +Can be safely re-run + +```sh +$PREFIX bump_all_conversations +``` + +## Remove duplicated items from following and update followers count for all users + +```sh +$PREFIX update_users_following_followers_counts +``` + +## Fix the pre-existing "likes" collections for all objects + +```sh +$PREFIX fix_likes_collections +``` diff --git a/lib/mix/tasks/pleroma/database.ex b/lib/mix/tasks/pleroma/database.ex index 890a383df..81e687f64 100644 --- a/lib/mix/tasks/pleroma/database.ex +++ b/lib/mix/tasks/pleroma/database.ex @@ -13,34 +13,7 @@ defmodule Mix.Tasks.Pleroma.Database do use Mix.Task @shortdoc "A collection of database related tasks" - @moduledoc """ - A collection of database related tasks - ## Replace embedded objects with their references - - Replaces embedded objects with references to them in the `objects` table. Only needs to be ran once. The reason why this is not a migration is because it could significantly increase the database size after being ran, however after this `VACUUM FULL` will be able to reclaim about 20% (really depends on what is in the database, your mileage may vary) of the db size before the migration. - - mix pleroma.database remove_embedded_objects - - Options: - - `--vacuum` - run `VACUUM FULL` after the embedded objects are replaced with their references - - ## Prune old objects from the database - - mix pleroma.database prune_objects - - ## Create a conversation for all existing DMs. Can be safely re-run. - - mix pleroma.database bump_all_conversations - - ## Remove duplicated items from following and update followers count for all users - - mix pleroma.database update_users_following_followers_counts - - ## Fix the pre-existing "likes" collections for all objects - - mix pleroma.database fix_likes_collections - """ def run(["remove_embedded_objects" | args]) do {options, [], []} = OptionParser.parse( -- cgit v1.2.3 From e00403af232548fdef8ad8f2923a51561b3064f6 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 13:59:49 +0300 Subject: Mix tasks: derive moduledoc from doc files --- lib/mix/tasks/pleroma/database.ex | 1 + lib/mix/tasks/pleroma/digest.ex | 1 + lib/mix/tasks/pleroma/emoji.ex | 1 + lib/mix/tasks/pleroma/instance.ex | 1 + lib/mix/tasks/pleroma/relay.ex | 1 + lib/mix/tasks/pleroma/uploads.ex | 1 + lib/mix/tasks/pleroma/user.ex | 1 + 7 files changed, 7 insertions(+) diff --git a/lib/mix/tasks/pleroma/database.ex b/lib/mix/tasks/pleroma/database.ex index 81e687f64..cfd9eeada 100644 --- a/lib/mix/tasks/pleroma/database.ex +++ b/lib/mix/tasks/pleroma/database.ex @@ -13,6 +13,7 @@ defmodule Mix.Tasks.Pleroma.Database do use Mix.Task @shortdoc "A collection of database related tasks" + @moduledoc File.read!("docs/administration/CLI_tasks/database.md") def run(["remove_embedded_objects" | args]) do {options, [], []} = diff --git a/lib/mix/tasks/pleroma/digest.ex b/lib/mix/tasks/pleroma/digest.ex index 100a81060..7d09e70c5 100644 --- a/lib/mix/tasks/pleroma/digest.ex +++ b/lib/mix/tasks/pleroma/digest.ex @@ -2,6 +2,7 @@ defmodule Mix.Tasks.Pleroma.Digest do use Mix.Task @shortdoc "Manages digest emails" + @moduledoc File.read!("docs/administration/CLI_tasks/digest.md") def run(["test", nickname | opts]) do Mix.Pleroma.start_pleroma() diff --git a/lib/mix/tasks/pleroma/emoji.ex b/lib/mix/tasks/pleroma/emoji.ex index 32b92e6af..6ef0a635d 100644 --- a/lib/mix/tasks/pleroma/emoji.ex +++ b/lib/mix/tasks/pleroma/emoji.ex @@ -6,6 +6,7 @@ defmodule Mix.Tasks.Pleroma.Emoji do use Mix.Task @shortdoc "Manages emoji packs" + @moduledoc File.read!("docs/administration/CLI_tasks/emoji.md") def run(["ls-packs" | args]) do Application.ensure_all_started(:hackney) diff --git a/lib/mix/tasks/pleroma/instance.ex b/lib/mix/tasks/pleroma/instance.ex index 25f94eceb..9af6cda30 100644 --- a/lib/mix/tasks/pleroma/instance.ex +++ b/lib/mix/tasks/pleroma/instance.ex @@ -7,6 +7,7 @@ defmodule Mix.Tasks.Pleroma.Instance do import Mix.Pleroma @shortdoc "Manages Pleroma instance" + @moduledoc File.read!("docs/administration/CLI_tasks/instance.md") def run(["gen" | rest]) do {options, [], []} = diff --git a/lib/mix/tasks/pleroma/relay.ex b/lib/mix/tasks/pleroma/relay.ex index 519f2d1b5..d7a7b599f 100644 --- a/lib/mix/tasks/pleroma/relay.ex +++ b/lib/mix/tasks/pleroma/relay.ex @@ -9,6 +9,7 @@ defmodule Mix.Tasks.Pleroma.Relay do alias Pleroma.Web.ActivityPub.Relay @shortdoc "Manages remote relays" + @moduledoc File.read!("docs/administration/CLI_tasks/relay.md") def run(["follow", target]) do start_pleroma() diff --git a/lib/mix/tasks/pleroma/uploads.ex b/lib/mix/tasks/pleroma/uploads.ex index bc2248a76..3e6fc7ee0 100644 --- a/lib/mix/tasks/pleroma/uploads.ex +++ b/lib/mix/tasks/pleroma/uploads.ex @@ -12,6 +12,7 @@ defmodule Mix.Tasks.Pleroma.Uploads do @log_every 50 @shortdoc "Migrates uploads from local to remote storage" + @moduledoc File.read!("docs/administration/CLI_tasks/uploads.md") def run(["migrate_local", target_uploader | args]) do delete? = Enum.member?(args, "--delete") diff --git a/lib/mix/tasks/pleroma/user.ex b/lib/mix/tasks/pleroma/user.ex index 3cf3ad2c6..134b5bccc 100644 --- a/lib/mix/tasks/pleroma/user.ex +++ b/lib/mix/tasks/pleroma/user.ex @@ -10,6 +10,7 @@ defmodule Mix.Tasks.Pleroma.User do alias Pleroma.Web.OAuth @shortdoc "Manages Pleroma users" + @moduledoc File.read!("docs/administration/CLI_tasks/user.md") def run(["new", nickname, email | rest]) do {options, [], []} = -- cgit v1.2.3 From 1cae564b5d749a23f29a5303a82e27e2952a55ed Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 14:12:57 +0300 Subject: Move config task docs to a separate file and mark it as WIP --- docs/administration/CLI_tasks/config.md | 19 +++++++++++++++++++ docs/configuration/cheatsheet.md | 6 +++++- lib/mix/tasks/pleroma/config.ex | 13 +------------ 3 files changed, 25 insertions(+), 13 deletions(-) create mode 100644 docs/administration/CLI_tasks/config.md diff --git a/docs/administration/CLI_tasks/config.md b/docs/administration/CLI_tasks/config.md new file mode 100644 index 000000000..ce19e2402 --- /dev/null +++ b/docs/administration/CLI_tasks/config.md @@ -0,0 +1,19 @@ +# Transfering the config to/from the database + +!!! danger + This is a Work In Progress, not usable just yet. + +Every command should be ran with a prefix, in case of OTP releases it is `./bin/pleroma_ctl config` and in case of source installs it's +`mix pleroma.config`. + +## Transfer config from file to DB. + +```sh +$PREFIX migrate_to_db +``` + +## Transfer config from DB to `config/env.exported_from_db.secret.exs` + +```sh +$PREFIX migrate_from_db +``` diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 9e5368cf1..8f00915a3 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -131,13 +131,17 @@ config :pleroma, Pleroma.Emails.Mailer, * `user_name_length`: A user name maximum length (default: `100`) * `skip_thread_containment`: Skip filter out broken threads. The default is `false`. * `limit_to_local_content`: Limit unauthenticated users to search for local statutes and users only. Possible values: `:unauthenticated`, `:all` and `false`. The default is `:unauthenticated`. -* `dynamic_configuration`: Allow transferring configuration to DB with the subsequent customization from Admin api. * `max_account_fields`: The maximum number of custom fields in the user profile (default: `10`) * `max_remote_account_fields`: The maximum number of custom fields in the remote user profile (default: `20`) * `account_field_name_length`: An account field name maximum length (default: `512`) * `account_field_value_length`: An account field value maximum length (default: `2048`) * `external_user_synchronization`: Enabling following/followers counters synchronization for external users. +!!! danger + This is a Work In Progress, not usable just yet + +* `dynamic_configuration`: Allow transferring configuration to DB with the subsequent customization from Admin api. + ## :logger diff --git a/lib/mix/tasks/pleroma/config.ex b/lib/mix/tasks/pleroma/config.ex index 462940e7e..11e4fde43 100644 --- a/lib/mix/tasks/pleroma/config.ex +++ b/lib/mix/tasks/pleroma/config.ex @@ -8,18 +8,7 @@ defmodule Mix.Tasks.Pleroma.Config do alias Pleroma.Repo alias Pleroma.Web.AdminAPI.Config @shortdoc "Manages the location of the config" - @moduledoc """ - Manages the location of the config. - - ## Transfers config from file to DB. - - mix pleroma.config migrate_to_db - - ## Transfers config from DB to file `config/env.exported_from_db.secret.exs` - - mix pleroma.config migrate_from_db ENV - """ - + @moduledoc File.read!("docs/administration/CLI_tasks/config.md") def run(["migrate_to_db"]) do start_pleroma() -- cgit v1.2.3 From b5a43e301eb885f3f35632804b1cc1c7243edbfb Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 14:27:11 +0300 Subject: Change docs build/deploy to just trigger a pipeline in the docs repo --- .gitlab-ci.yml | 29 ++++------------------------- 1 file changed, 4 insertions(+), 25 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7bee30e08..e98f23b25 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -28,23 +28,6 @@ build: - mix deps.get - mix compile --force -docs-build: - stage: build - only: - - master@pleroma/pleroma - - develop@pleroma/pleroma - variables: - MIX_ENV: dev - PLEROMA_BUILD_ENV: prod - script: - - mix deps.get - - mix compile - - mix docs - artifacts: - paths: - - priv/static/doc - - unit-testing: stage: test services: @@ -85,19 +68,15 @@ analysis: docs-deploy: stage: deploy - image: alpine:3.9 + image: alpine:latest only: + - mkdocs-migration-prep@pleroma/pleroma - master@pleroma/pleroma - develop@pleroma/pleroma before_script: - - apk update && apk add openssh-client rsync + - apk add curl script: - - mkdir -p ~/.ssh - - echo "${SSH_HOST_KEY}" > ~/.ssh/known_hosts - - eval $(ssh-agent -s) - - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - - - rsync -hrvz --delete -e "ssh -p ${SSH_PORT}" priv/static/doc/ "${SSH_USER_HOST_LOCATION}/${CI_COMMIT_REF_NAME}" - + - curl -X POST -F"token=$DOCS_PIPELINE_TRIGGER" -F'ref=master' -F"variables[BRANCH]=$CI_COMMIT_REF_NAME" https://git.pleroma.social/api/v4/projects/673/trigger/pipeline review_app: image: alpine:3.9 stage: deploy -- cgit v1.2.3 From 69784eb75a00fb929765adbeab41022052038cca Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 15:10:04 +0300 Subject: Add a missing language specification --- docs/administration/CLI_tasks/user.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administration/CLI_tasks/user.md b/docs/administration/CLI_tasks/user.md index 045730753..cf120f2c9 100644 --- a/docs/administration/CLI_tasks/user.md +++ b/docs/administration/CLI_tasks/user.md @@ -35,7 +35,7 @@ $PREFIX revoke_invite ``` ## Delete a user -``` +```sh $PREFIX rm ``` -- cgit v1.2.3 From b8b98ac40f042a8c3d2562edc095f0e1a309760f Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Thu, 3 Oct 2019 10:40:49 -0500 Subject: Add missing extended_nickname_format setting to the default config --- CHANGELOG.md | 1 + config/config.exs | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a71a9dae6..c22995b82 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Fixed - Mastodon API: Fix private and direct statuses not being filtered out from the public timeline for an authenticated user (`GET /api/v1/timelines/public`) +- Added `:instance, extended_nickname_format` setting to the default config ## [1.1.0] - 2019-??-?? ### Security diff --git a/config/config.exs b/config/config.exs index 36bea19a0..ddbfb246a 100644 --- a/config/config.exs +++ b/config/config.exs @@ -279,7 +279,8 @@ config :pleroma, :instance, max_remote_account_fields: 20, account_field_name_length: 512, account_field_value_length: 2048, - external_user_synchronization: true + external_user_synchronization: true, + extended_nickname_format: false config :pleroma, :markup, # XXX - unfortunately, inline images must be enabled by default right now, because -- cgit v1.2.3 From b2f2012a4f34cfe8151e62d045f0eab3d165791a Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 3 Oct 2019 18:42:02 +0300 Subject: Remove a test branch from CI --- .gitlab-ci.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index e98f23b25..748bec74a 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -70,7 +70,6 @@ docs-deploy: stage: deploy image: alpine:latest only: - - mkdocs-migration-prep@pleroma/pleroma - master@pleroma/pleroma - develop@pleroma/pleroma before_script: -- cgit v1.2.3 From 06d9df79c5c99069dd12e863c99167eb20b6495b Mon Sep 17 00:00:00 2001 From: eugenijm Date: Wed, 2 Oct 2019 00:37:08 +0300 Subject: Mastodon API: Add `pleroma.unread_conversation_count` to the Account entity --- CHANGELOG.md | 1 + docs/API/differences_in_mastoapi_responses.md | 1 + lib/pleroma/conversation.ex | 2 + lib/pleroma/conversation/participation.ex | 17 ++++ lib/pleroma/user.ex | 56 ++++++++++++ lib/pleroma/user/info.ex | 1 + lib/pleroma/web/mastodon_api/views/account_view.ex | 11 +++ test/conversation/participation_test.exs | 4 + .../controllers/conversation_controller_test.exs | 101 +++++++++++++++++++-- test/web/mastodon_api/views/account_view_test.exs | 21 +++++ .../controllers/pleroma_api_controller_test.exs | 2 + 11 files changed, 207 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a71a9dae6..a38f61fba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Pleroma API: `GET /api/v1/pleroma/accounts/:id/scrobbles` to get a list of recently scrobbled items - Pleroma API: `POST /api/v1/pleroma/scrobble` to scrobble a media item - Mastodon API: Add `upload_limit`, `avatar_upload_limit`, `background_upload_limit`, and `banner_upload_limit` to `/api/v1/instance` +- Mastodon API: Add `pleroma.unread_conversation_count` to the Account entity ### Changed - **Breaking:** Elixir >=1.8 is now required (was >= 1.7) diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md index d007a69c3..21b297529 100644 --- a/docs/API/differences_in_mastoapi_responses.md +++ b/docs/API/differences_in_mastoapi_responses.md @@ -56,6 +56,7 @@ Has these additional fields under the `pleroma` object: - `settings_store`: A generic map of settings for frontends. Opaque to the backend. Only returned in `verify_credentials` and `update_credentials` - `chat_token`: The token needed for Pleroma chat. Only returned in `verify_credentials` - `deactivated`: boolean, true when the user is deactivated +- `unread_conversation_count`: The count of unread conversations. Only returned to the account owner. ### Source diff --git a/lib/pleroma/conversation.ex b/lib/pleroma/conversation.ex index be5821ad7..098016af2 100644 --- a/lib/pleroma/conversation.ex +++ b/lib/pleroma/conversation.ex @@ -67,6 +67,8 @@ defmodule Pleroma.Conversation do participations = Enum.map(users, fn user -> + User.increment_unread_conversation_count(conversation, user) + {:ok, participation} = Participation.create_for_user_and_conversation(user, conversation, opts) diff --git a/lib/pleroma/conversation/participation.ex b/lib/pleroma/conversation/participation.ex index e946f6de2..ab81f3217 100644 --- a/lib/pleroma/conversation/participation.ex +++ b/lib/pleroma/conversation/participation.ex @@ -52,6 +52,15 @@ defmodule Pleroma.Conversation.Participation do participation |> read_cng(%{read: true}) |> Repo.update() + |> case do + {:ok, participation} -> + participation = Repo.preload(participation, :user) + User.set_unread_conversation_count(participation.user) + {:ok, participation} + + error -> + error + end end def mark_as_unread(participation) do @@ -135,4 +144,12 @@ defmodule Pleroma.Conversation.Participation do {:ok, Repo.preload(participation, :recipients, force: true)} end + + def unread_conversation_count_for_user(user) do + from(p in __MODULE__, + where: p.user_id == ^user.id, + where: not p.read, + select: %{count: count(p.id)} + ) + end end diff --git a/lib/pleroma/user.ex b/lib/pleroma/user.ex index 4c1cdd042..572dd7746 100644 --- a/lib/pleroma/user.ex +++ b/lib/pleroma/user.ex @@ -11,6 +11,7 @@ defmodule Pleroma.User do alias Comeonin.Pbkdf2 alias Ecto.Multi alias Pleroma.Activity + alias Pleroma.Conversation.Participation alias Pleroma.Delivery alias Pleroma.Keys alias Pleroma.Notification @@ -842,6 +843,61 @@ defmodule Pleroma.User do def maybe_update_following_count(user), do: user + def set_unread_conversation_count(%User{local: true} = user) do + unread_query = Participation.unread_conversation_count_for_user(user) + + User + |> where([u], u.id == ^user.id) + |> join(:inner, [u], p in subquery(unread_query)) + |> update([u, p], + set: [ + info: + fragment( + "jsonb_set(?, '{unread_conversation_count}', ?::varchar::jsonb, true)", + u.info, + p.count + ) + ] + ) + |> select([u], u) + |> Repo.update_all([]) + |> case do + {1, [%{info: %User.Info{}} = user]} -> set_cache(user) + _ -> {:error, user} + end + end + + def set_unread_conversation_count(_), do: :noop + + def increment_unread_conversation_count(conversation, %User{local: true} = user) do + unread_query = + Participation.unread_conversation_count_for_user(user) + |> where([p], p.conversation_id == ^conversation.id) + + User + |> join(:inner, [u], p in subquery(unread_query)) + |> update([u, p], + set: [ + info: + fragment( + "jsonb_set(?, '{unread_conversation_count}', ((?->>'unread_conversation_count')::int + 1)::varchar::jsonb, true)", + u.info, + u.info + ) + ] + ) + |> where([u], u.id == ^user.id) + |> where([u, p], p.count == 0) + |> select([u], u) + |> Repo.update_all([]) + |> case do + {1, [%{info: %User.Info{}} = user]} -> set_cache(user) + _ -> {:error, user} + end + end + + def increment_unread_conversation_count(_, _), do: :noop + def remove_duplicated_following(%User{following: following} = user) do uniq_following = Enum.uniq(following) diff --git a/lib/pleroma/user/info.ex b/lib/pleroma/user/info.ex index ebd4ddebf..4b5b43d7f 100644 --- a/lib/pleroma/user/info.ex +++ b/lib/pleroma/user/info.ex @@ -47,6 +47,7 @@ defmodule Pleroma.User.Info do field(:hide_followers, :boolean, default: false) field(:hide_follows, :boolean, default: false) field(:hide_favorites, :boolean, default: true) + field(:unread_conversation_count, :integer, default: 0) field(:pinned_activities, {:array, :string}, default: []) field(:email_notifications, :map, default: %{"digest" => false}) field(:mascot, :map, default: nil) diff --git a/lib/pleroma/web/mastodon_api/views/account_view.ex b/lib/pleroma/web/mastodon_api/views/account_view.ex index 99169ef95..2d4976891 100644 --- a/lib/pleroma/web/mastodon_api/views/account_view.ex +++ b/lib/pleroma/web/mastodon_api/views/account_view.ex @@ -167,6 +167,7 @@ defmodule Pleroma.Web.MastodonAPI.AccountView do |> maybe_put_chat_token(user, opts[:for], opts) |> maybe_put_activation_status(user, opts[:for]) |> maybe_put_follow_requests_count(user, opts[:for]) + |> maybe_put_unread_conversation_count(user, opts[:for]) end defp username_from_nickname(string) when is_binary(string) do @@ -248,6 +249,16 @@ defmodule Pleroma.Web.MastodonAPI.AccountView do defp maybe_put_activation_status(data, _, _), do: data + defp maybe_put_unread_conversation_count(data, %User{id: user_id} = user, %User{id: user_id}) do + data + |> Kernel.put_in( + [:pleroma, :unread_conversation_count], + user.info.unread_conversation_count + ) + end + + defp maybe_put_unread_conversation_count(data, _, _), do: data + defp image_url(%{"url" => [%{"href" => href} | _]}), do: href defp image_url(_), do: nil end diff --git a/test/conversation/participation_test.exs b/test/conversation/participation_test.exs index a27167d42..f430bdf75 100644 --- a/test/conversation/participation_test.exs +++ b/test/conversation/participation_test.exs @@ -6,6 +6,7 @@ defmodule Pleroma.Conversation.ParticipationTest do use Pleroma.DataCase import Pleroma.Factory alias Pleroma.Conversation.Participation + alias Pleroma.User alias Pleroma.Web.CommonAPI test "getting a participation will also preload things" do @@ -30,6 +31,8 @@ defmodule Pleroma.Conversation.ParticipationTest do {:ok, activity} = CommonAPI.post(user, %{"status" => "Hey @#{other_user.nickname}.", "visibility" => "direct"}) + user = User.get_cached_by_id(user.id) + other_user = User.get_cached_by_id(user.id) [participation] = Participation.for_user(user) participation = Pleroma.Repo.preload(participation, :recipients) @@ -155,6 +158,7 @@ defmodule Pleroma.Conversation.ParticipationTest do [participation] = Participation.for_user_with_last_activity_id(user) participation = Repo.preload(participation, :recipients) + user = User.get_cached_by_id(user.id) assert participation.recipients |> length() == 1 assert user in participation.recipients diff --git a/test/web/mastodon_api/controllers/conversation_controller_test.exs b/test/web/mastodon_api/controllers/conversation_controller_test.exs index 7117fc76a..a308a7620 100644 --- a/test/web/mastodon_api/controllers/conversation_controller_test.exs +++ b/test/web/mastodon_api/controllers/conversation_controller_test.exs @@ -10,19 +10,23 @@ defmodule Pleroma.Web.MastodonAPI.ConversationControllerTest do import Pleroma.Factory - test "Conversations", %{conn: conn} do + test "returns a list of conversations", %{conn: conn} do user_one = insert(:user) user_two = insert(:user) user_three = insert(:user) {:ok, user_two} = User.follow(user_two, user_one) + assert User.get_cached_by_id(user_two.id).info.unread_conversation_count == 0 + {:ok, direct} = CommonAPI.post(user_one, %{ "status" => "Hi @#{user_two.nickname}, @#{user_three.nickname}!", "visibility" => "direct" }) + assert User.get_cached_by_id(user_two.id).info.unread_conversation_count == 1 + {:ok, _follower_only} = CommonAPI.post(user_one, %{ "status" => "Hi @#{user_two.nickname}!", @@ -52,23 +56,100 @@ defmodule Pleroma.Web.MastodonAPI.ConversationControllerTest do assert is_binary(res_id) assert unread == true assert res_last_status["id"] == direct.id + assert User.get_cached_by_id(user_one.id).info.unread_conversation_count == 1 + end - # Apparently undocumented API endpoint - res_conn = + test "updates the last_status on reply", %{conn: conn} do + user_one = insert(:user) + user_two = insert(:user) + + {:ok, direct} = + CommonAPI.post(user_one, %{ + "status" => "Hi @#{user_two.nickname}", + "visibility" => "direct" + }) + + {:ok, direct_reply} = + CommonAPI.post(user_two, %{ + "status" => "reply", + "visibility" => "direct", + "in_reply_to_status_id" => direct.id + }) + + [%{"last_status" => res_last_status}] = conn |> assign(:user, user_one) - |> post("/api/v1/conversations/#{res_id}/read") + |> get("/api/v1/conversations") + |> json_response(200) - assert response = json_response(res_conn, 200) - assert length(response["accounts"]) == 2 - assert response["last_status"]["id"] == direct.id - assert response["unread"] == false + assert res_last_status["id"] == direct_reply.id + end + + test "the user marks a conversation as read", %{conn: conn} do + user_one = insert(:user) + user_two = insert(:user) + + {:ok, direct} = + CommonAPI.post(user_one, %{ + "status" => "Hi @#{user_two.nickname}", + "visibility" => "direct" + }) + + [%{"id" => direct_conversation_id, "unread" => true}] = + conn + |> assign(:user, user_one) + |> get("/api/v1/conversations") + |> json_response(200) + + %{"unread" => false} = + conn + |> assign(:user, user_one) + |> post("/api/v1/conversations/#{direct_conversation_id}/read") + |> json_response(200) + + assert User.get_cached_by_id(user_one.id).info.unread_conversation_count == 0 + + # The conversation is marked as unread on reply + {:ok, _} = + CommonAPI.post(user_two, %{ + "status" => "reply", + "visibility" => "direct", + "in_reply_to_status_id" => direct.id + }) + + [%{"unread" => true}] = + conn + |> assign(:user, user_one) + |> get("/api/v1/conversations") + |> json_response(200) + + assert User.get_cached_by_id(user_one.id).info.unread_conversation_count == 1 + + # A reply doesn't increment the user's unread_conversation_count if the conversation is unread + {:ok, _} = + CommonAPI.post(user_two, %{ + "status" => "reply", + "visibility" => "direct", + "in_reply_to_status_id" => direct.id + }) + + assert User.get_cached_by_id(user_one.id).info.unread_conversation_count == 1 + end + + test "(vanilla) Mastodon frontend behaviour", %{conn: conn} do + user_one = insert(:user) + user_two = insert(:user) + + {:ok, direct} = + CommonAPI.post(user_one, %{ + "status" => "Hi @#{user_two.nickname}!", + "visibility" => "direct" + }) - # (vanilla) Mastodon frontend behaviour res_conn = conn |> assign(:user, user_one) - |> get("/api/v1/statuses/#{res_last_status["id"]}/context") + |> get("/api/v1/statuses/#{direct.id}/context") assert %{"ancestors" => [], "descendants" => []} == json_response(res_conn, 200) end diff --git a/test/web/mastodon_api/views/account_view_test.exs b/test/web/mastodon_api/views/account_view_test.exs index 62b2ab7e3..b7a4938a6 100644 --- a/test/web/mastodon_api/views/account_view_test.exs +++ b/test/web/mastodon_api/views/account_view_test.exs @@ -418,6 +418,27 @@ defmodule Pleroma.Web.MastodonAPI.AccountViewTest do following_count: 1 } = AccountView.render("show.json", %{user: user, for: user}) end + + test "shows unread_conversation_count only to the account owner" do + user = insert(:user) + other_user = insert(:user) + + {:ok, _activity} = + CommonAPI.post(user, %{ + "status" => "Hey @#{other_user.nickname}.", + "visibility" => "direct" + }) + + user = User.get_cached_by_ap_id(user.ap_id) + + assert AccountView.render("show.json", %{user: user, for: other_user})[:pleroma][ + :unread_conversation_count + ] == nil + + assert AccountView.render("show.json", %{user: user, for: user})[:pleroma][ + :unread_conversation_count + ] == 1 + end end describe "follow requests counter" do diff --git a/test/web/pleroma_api/controllers/pleroma_api_controller_test.exs b/test/web/pleroma_api/controllers/pleroma_api_controller_test.exs index 7eaeda4a0..8a6528cbb 100644 --- a/test/web/pleroma_api/controllers/pleroma_api_controller_test.exs +++ b/test/web/pleroma_api/controllers/pleroma_api_controller_test.exs @@ -8,6 +8,7 @@ defmodule Pleroma.Web.PleromaAPI.PleromaAPIControllerTest do alias Pleroma.Conversation.Participation alias Pleroma.Notification alias Pleroma.Repo + alias Pleroma.User alias Pleroma.Web.CommonAPI import Pleroma.Factory @@ -73,6 +74,7 @@ defmodule Pleroma.Web.PleromaAPI.PleromaAPIControllerTest do participation = Repo.preload(participation, :recipients) + user = User.get_cached_by_id(user.id) assert [user] == participation.recipients assert other_user not in participation.recipients -- cgit v1.2.3 From e4ab9a05ddc857298f2f0f36e06c2a874e1d6a6b Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Fri, 4 Oct 2019 00:10:28 +0200 Subject: cheatsheet.md: link to pleroma-fe docs for :frontend_configurations --- docs/configuration/cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 8f00915a3..b86799ecc 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -189,7 +189,7 @@ See the [Quack Github](https://github.com/azohra/quack) for more details ## :frontend_configurations -This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. +This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. You can find the documentation for `pleroma_fe` configuration into [Pleroma-FE configuration and customization for instance administrators](/frontend/CONFIGURATION/#options). Frontends can access these settings at `/api/pleroma/frontend_configurations` -- cgit v1.2.3 From 5dc14c89cecc121ffb047c2a7c972af0b0f89ef8 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Fri, 4 Oct 2019 06:47:36 +0200 Subject: =?UTF-8?q?notification=5Fview.ex:=20Make=20sure=20`account`=20isn?= =?UTF-8?q?=E2=80=99t=20empty?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Related: https://git.pleroma.social/pleroma/pleroma/issues/1203 --- .../web/mastodon_api/views/notification_view.ex | 60 ++++++++++++---------- .../mastodon_api/views/notification_view_test.exs | 6 +++ 2 files changed, 38 insertions(+), 28 deletions(-) diff --git a/lib/pleroma/web/mastodon_api/views/notification_view.ex b/lib/pleroma/web/mastodon_api/views/notification_view.ex index 60b58dc90..5e3dbe728 100644 --- a/lib/pleroma/web/mastodon_api/views/notification_view.ex +++ b/lib/pleroma/web/mastodon_api/views/notification_view.ex @@ -25,40 +25,44 @@ defmodule Pleroma.Web.MastodonAPI.NotificationView do parent_activity = Activity.get_create_by_object_ap_id(activity.data["object"]) mastodon_type = Activity.mastodon_notification_type(activity) - response = %{ - id: to_string(notification.id), - type: mastodon_type, - created_at: CommonAPI.Utils.to_masto_date(notification.inserted_at), - account: AccountView.render("show.json", %{user: actor, for: user}), - pleroma: %{ - is_seen: notification.seen + with %{id: _} = account <- AccountView.render("show.json", %{user: actor, for: user}) do + response = %{ + id: to_string(notification.id), + type: mastodon_type, + created_at: CommonAPI.Utils.to_masto_date(notification.inserted_at), + account: account, + pleroma: %{ + is_seen: notification.seen + } } - } - case mastodon_type do - "mention" -> - response - |> Map.merge(%{ - status: StatusView.render("show.json", %{activity: activity, for: user}) - }) + case mastodon_type do + "mention" -> + response + |> Map.merge(%{ + status: StatusView.render("show.json", %{activity: activity, for: user}) + }) - "favourite" -> - response - |> Map.merge(%{ - status: StatusView.render("show.json", %{activity: parent_activity, for: user}) - }) + "favourite" -> + response + |> Map.merge(%{ + status: StatusView.render("show.json", %{activity: parent_activity, for: user}) + }) - "reblog" -> - response - |> Map.merge(%{ - status: StatusView.render("show.json", %{activity: parent_activity, for: user}) - }) + "reblog" -> + response + |> Map.merge(%{ + status: StatusView.render("show.json", %{activity: parent_activity, for: user}) + }) - "follow" -> - response + "follow" -> + response - _ -> - nil + _ -> + nil + end + else + _ -> nil end end end diff --git a/test/web/mastodon_api/views/notification_view_test.exs b/test/web/mastodon_api/views/notification_view_test.exs index 81ab82e2b..c9043a69a 100644 --- a/test/web/mastodon_api/views/notification_view_test.exs +++ b/test/web/mastodon_api/views/notification_view_test.exs @@ -100,5 +100,11 @@ defmodule Pleroma.Web.MastodonAPI.NotificationViewTest do NotificationView.render("index.json", %{notifications: [notification], for: followed}) assert [expected] == result + + User.perform(:delete, follower) + notification = Notification |> Repo.one() |> Repo.preload(:activity) + + assert [] == + NotificationView.render("index.json", %{notifications: [notification], for: followed}) end end -- cgit v1.2.3 From d3ac4e8083f254a6a0e329a5807c0973f55402f4 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Fri, 4 Oct 2019 13:30:46 +0700 Subject: Fix OAuthController --- lib/pleroma/web/oauth/oauth_controller.ex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/pleroma/web/oauth/oauth_controller.ex b/lib/pleroma/web/oauth/oauth_controller.ex index e418dc70d..1cd7294e7 100644 --- a/lib/pleroma/web/oauth/oauth_controller.ex +++ b/lib/pleroma/web/oauth/oauth_controller.ex @@ -460,7 +460,7 @@ defmodule Pleroma.Web.OAuth.OAuthController do end # Special case: Local MastodonFE - defp redirect_uri(%Plug.Conn{} = conn, "."), do: mastodon_api_url(conn, :login) + defp redirect_uri(%Plug.Conn{} = conn, "."), do: auth_url(conn, :login) defp redirect_uri(%Plug.Conn{}, redirect_uri), do: redirect_uri -- cgit v1.2.3 From 821729208506980bc65e9671c5462b629dffddaa Mon Sep 17 00:00:00 2001 From: rinpatch Date: Fri, 4 Oct 2019 01:05:50 +0300 Subject: Fix get_cached_by_nickname_or_id not allowing to get local users by nickname Closes #1293 --- CHANGELOG.md | 1 + lib/pleroma/user.ex | 2 +- test/user_test.exs | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a71a9dae6..f677611c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Fixed - Mastodon API: Fix private and direct statuses not being filtered out from the public timeline for an authenticated user (`GET /api/v1/timelines/public`) +- Mastodon API: Inability to get some local users by nickname in `/api/v1/accounts/:id_or_nickname` ## [1.1.0] - 2019-??-?? ### Security diff --git a/lib/pleroma/user.ex b/lib/pleroma/user.ex index 4c1cdd042..c2f8fa0d7 100644 --- a/lib/pleroma/user.ex +++ b/lib/pleroma/user.ex @@ -583,7 +583,7 @@ defmodule Pleroma.User do is_integer(nickname_or_id) or FlakeId.flake_id?(nickname_or_id) -> get_cached_by_id(nickname_or_id) || get_cached_by_nickname(nickname_or_id) - restrict_to_local == false -> + restrict_to_local == false or not String.contains?(nickname_or_id, "@") -> get_cached_by_nickname(nickname_or_id) restrict_to_local == :unauthenticated and match?(%User{}, opts[:for]) -> diff --git a/test/user_test.exs b/test/user_test.exs index 126bd69e8..1bc853c94 100644 --- a/test/user_test.exs +++ b/test/user_test.exs @@ -1725,4 +1725,61 @@ defmodule Pleroma.UserTest do assert %{info: %{hide_follows: true}} = Repo.get(User, user.id) assert {:ok, %{info: %{hide_follows: true}}} = Cachex.get(:user_cache, "ap_id:#{user.ap_id}") end + + describe "get_cached_by_nickname_or_id" do + setup do + limit_to_local_content = Pleroma.Config.get([:instance, :limit_to_local_content]) + local_user = insert(:user) + remote_user = insert(:user, nickname: "nickname@example.com", local: false) + + on_exit(fn -> + Pleroma.Config.put([:instance, :limit_to_local_content], limit_to_local_content) + end) + + [local_user: local_user, remote_user: remote_user] + end + + test "allows getting remote users by id no matter what :limit_to_local_content is set to", %{ + remote_user: remote_user + } do + Pleroma.Config.put([:instance, :limit_to_local_content], false) + assert %User{} = User.get_cached_by_nickname_or_id(remote_user.id) + + Pleroma.Config.put([:instance, :limit_to_local_content], true) + assert %User{} = User.get_cached_by_nickname_or_id(remote_user.id) + + Pleroma.Config.put([:instance, :limit_to_local_content], :unauthenticated) + assert %User{} = User.get_cached_by_nickname_or_id(remote_user.id) + end + + test "disallows getting remote users by nickname without authentication when :limit_to_local_content is set to :unauthenticated", + %{remote_user: remote_user} do + Pleroma.Config.put([:instance, :limit_to_local_content], :unauthenticated) + assert nil == User.get_cached_by_nickname_or_id(remote_user.nickname) + end + + test "allows getting remote users by nickname with authentication when :limit_to_local_content is set to :unauthenticated", + %{remote_user: remote_user, local_user: local_user} do + Pleroma.Config.put([:instance, :limit_to_local_content], :unauthenticated) + assert %User{} = User.get_cached_by_nickname_or_id(remote_user.nickname, for: local_user) + end + + test "disallows getting remote users by nickname when :limit_to_local_content is set to true", + %{remote_user: remote_user} do + Pleroma.Config.put([:instance, :limit_to_local_content], true) + assert nil == User.get_cached_by_nickname_or_id(remote_user.nickname) + end + + test "allows getting local users by nickname no matter what :limit_to_local_content is set to", + %{local_user: local_user} do + Pleroma.Config.put([:instance, :limit_to_local_content], false) + assert %User{} = User.get_cached_by_nickname_or_id(local_user.nickname) + + Pleroma.Config.put([:instance, :limit_to_local_content], true) + assert %User{} = User.get_cached_by_nickname_or_id(local_user.nickname) + + Pleroma.Config.put([:instance, :limit_to_local_content], :unauthenticated) + assert %User{} = User.get_cached_by_nickname_or_id(local_user.nickname) + end + end end -- cgit v1.2.3 From 568a995d64c91f339989077da06e381b4b8cb070 Mon Sep 17 00:00:00 2001 From: lain Date: Fri, 4 Oct 2019 16:32:42 +0200 Subject: ActivityPub: Change addressing of Undo. --- lib/pleroma/web/activity_pub/utils.ex | 12 ++++++++---- test/web/activity_pub/activity_pub_test.exs | 5 +++-- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/lib/pleroma/web/activity_pub/utils.ex b/lib/pleroma/web/activity_pub/utils.ex index 0828591ee..ac5550671 100644 --- a/lib/pleroma/web/activity_pub/utils.ex +++ b/lib/pleroma/web/activity_pub/utils.ex @@ -461,14 +461,16 @@ defmodule Pleroma.Web.ActivityPub.Utils do """ def make_unannounce_data( %User{ap_id: ap_id} = user, - %Activity{data: %{"context" => context}} = activity, + %Activity{data: %{"context" => context, "object" => object}} = activity, activity_id ) do + object = Object.normalize(object) + %{ "type" => "Undo", "actor" => ap_id, "object" => activity.data, - "to" => [user.follower_address, activity.data["actor"]], + "to" => [user.follower_address, object.data["actor"]], "cc" => [Pleroma.Constants.as_public()], "context" => context } @@ -477,14 +479,16 @@ defmodule Pleroma.Web.ActivityPub.Utils do def make_unlike_data( %User{ap_id: ap_id} = user, - %Activity{data: %{"context" => context}} = activity, + %Activity{data: %{"context" => context, "object" => object}} = activity, activity_id ) do + object = Object.normalize(object) + %{ "type" => "Undo", "actor" => ap_id, "object" => activity.data, - "to" => [user.follower_address, activity.data["actor"]], + "to" => [user.follower_address, object.data["actor"]], "cc" => [Pleroma.Constants.as_public()], "context" => context } diff --git a/test/web/activity_pub/activity_pub_test.exs b/test/web/activity_pub/activity_pub_test.exs index f29497847..c9f2a92e7 100644 --- a/test/web/activity_pub/activity_pub_test.exs +++ b/test/web/activity_pub/activity_pub_test.exs @@ -811,10 +811,11 @@ defmodule Pleroma.Web.ActivityPub.ActivityPubTest do {:ok, like_activity, object} = ActivityPub.like(user, object) assert object.data["like_count"] == 1 - {:ok, _, _, object} = ActivityPub.unlike(user, object) + {:ok, unlike_activity, _, object} = ActivityPub.unlike(user, object) assert object.data["like_count"] == 0 assert Activity.get_by_id(like_activity.id) == nil + assert note_activity.actor in unlike_activity.recipients end end @@ -890,7 +891,7 @@ defmodule Pleroma.Web.ActivityPub.ActivityPubTest do assert unannounce_activity.data["to"] == [ User.ap_followers(user), - announce_activity.data["actor"] + object.data["actor"] ] assert unannounce_activity.data["type"] == "Undo" -- cgit v1.2.3 From 2a7f44acfe7075947982546f3dfef61a9cbe45e9 Mon Sep 17 00:00:00 2001 From: lain Date: Fri, 4 Oct 2019 17:10:49 +0200 Subject: ActivityPub.Utils: Fix undo test. --- test/web/activity_pub/utils_test.exs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/test/web/activity_pub/utils_test.exs b/test/web/activity_pub/utils_test.exs index b1c1d6f71..c57ea7eb9 100644 --- a/test/web/activity_pub/utils_test.exs +++ b/test/web/activity_pub/utils_test.exs @@ -106,11 +106,13 @@ defmodule Pleroma.Web.ActivityPub.UtilsTest do user = insert(:user) like_activity = insert(:like_activity, data_attrs: %{"context" => "test context"}) + object = Object.normalize(like_activity.data["object"]) + assert Utils.make_unlike_data(user, like_activity, nil) == %{ "type" => "Undo", "actor" => user.ap_id, "object" => like_activity.data, - "to" => [user.follower_address, like_activity.data["actor"]], + "to" => [user.follower_address, object.data["actor"]], "cc" => [Pleroma.Constants.as_public()], "context" => like_activity.data["context"] } @@ -119,7 +121,7 @@ defmodule Pleroma.Web.ActivityPub.UtilsTest do "type" => "Undo", "actor" => user.ap_id, "object" => like_activity.data, - "to" => [user.follower_address, like_activity.data["actor"]], + "to" => [user.follower_address, object.data["actor"]], "cc" => [Pleroma.Constants.as_public()], "context" => like_activity.data["context"], "id" => "9mJEZK0tky1w2xD2vY" -- cgit v1.2.3 From 8325858ed229304297df9f57d6e4a359cfa2b4a8 Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Fri, 4 Oct 2019 15:17:32 +0000 Subject: tests: streamer: add a test for blocked transitive activities --- test/web/streamer/streamer_test.exs | 74 ++++++++++++++++++++++++++++--------- 1 file changed, 56 insertions(+), 18 deletions(-) diff --git a/test/web/streamer/streamer_test.exs b/test/web/streamer/streamer_test.exs index b8fcd41fa..d33eb1e42 100644 --- a/test/web/streamer/streamer_test.exs +++ b/test/web/streamer/streamer_test.exs @@ -233,30 +233,68 @@ defmodule Pleroma.Web.StreamerTest do end end - test "it doesn't send to blocked users" do - user = insert(:user) - blocked_user = insert(:user) - {:ok, user} = User.block(user, blocked_user) + describe "blocks" do + test "it doesn't send messages involving blocked users" do + user = insert(:user) + blocked_user = insert(:user) + {:ok, user} = User.block(user, blocked_user) - task = - Task.async(fn -> - refute_receive {:text, _}, 1_000 - end) + task = + Task.async(fn -> + refute_receive {:text, _}, 1_000 + end) - fake_socket = %StreamerSocket{ - transport_pid: task.pid, - user: user - } + fake_socket = %StreamerSocket{ + transport_pid: task.pid, + user: user + } - {:ok, activity} = CommonAPI.post(blocked_user, %{"status" => "Test"}) + {:ok, activity} = CommonAPI.post(blocked_user, %{"status" => "Test"}) - topics = %{ - "public" => [fake_socket] - } + topics = %{ + "public" => [fake_socket] + } - Worker.push_to_socket(topics, "public", activity) + Worker.push_to_socket(topics, "public", activity) - Task.await(task) + Task.await(task) + end + + test "it doesn't send messages transitively involving blocked users" do + blocker = insert(:user) + blockee = insert(:user) + friend = insert(:user) + + task = + Task.async(fn -> + refute_receive {:text, _}, 1_000 + end) + + fake_socket = %StreamerSocket{ + transport_pid: task.pid, + user: blocker + } + + topics = %{ + "public" => [fake_socket] + } + + {:ok, blocker} = User.block(blocker, blockee) + + {:ok, activity_one} = CommonAPI.post(friend, %{"status" => "hey! @#{blockee.nickname}"}) + + Worker.push_to_socket(topics, "public", activity_one) + + {:ok, activity_two} = CommonAPI.post(blockee, %{"status" => "hey! @#{friend.nickname}"}) + + Worker.push_to_socket(topics, "public", activity_two) + + {:ok, activity_three} = CommonAPI.post(blockee, %{"status" => "hey! @#{blocker.nickname}"}) + + Worker.push_to_socket(topics, "public", activity_three) + + Task.await(task) + end end test "it doesn't send unwanted DMs to list" do -- cgit v1.2.3 From 2417b633ed866e6517a3fa0c30d0e85fc76dd548 Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Fri, 4 Oct 2019 15:21:45 +0000 Subject: streamer: add missing copyright headers --- lib/pleroma/web/streamer/ping.ex | 4 ++++ lib/pleroma/web/streamer/state.ex | 4 ++++ lib/pleroma/web/streamer/streamer_socket.ex | 4 ++++ lib/pleroma/web/streamer/supervisor.ex | 4 ++++ lib/pleroma/web/streamer/worker.ex | 4 ++++ 5 files changed, 20 insertions(+) diff --git a/lib/pleroma/web/streamer/ping.ex b/lib/pleroma/web/streamer/ping.ex index f77cbb95c..db3e68abe 100644 --- a/lib/pleroma/web/streamer/ping.ex +++ b/lib/pleroma/web/streamer/ping.ex @@ -1,3 +1,7 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + defmodule Pleroma.Web.Streamer.Ping do use GenServer require Logger diff --git a/lib/pleroma/web/streamer/state.ex b/lib/pleroma/web/streamer/state.ex index c48752d95..5ce3ebb8a 100644 --- a/lib/pleroma/web/streamer/state.ex +++ b/lib/pleroma/web/streamer/state.ex @@ -1,3 +1,7 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + defmodule Pleroma.Web.Streamer.State do use GenServer require Logger diff --git a/lib/pleroma/web/streamer/streamer_socket.ex b/lib/pleroma/web/streamer/streamer_socket.ex index f006c0306..cf0fa3077 100644 --- a/lib/pleroma/web/streamer/streamer_socket.ex +++ b/lib/pleroma/web/streamer/streamer_socket.ex @@ -1,3 +1,7 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + defmodule Pleroma.Web.Streamer.StreamerSocket do defstruct transport_pid: nil, user: nil diff --git a/lib/pleroma/web/streamer/supervisor.ex b/lib/pleroma/web/streamer/supervisor.ex index 6afe19323..ec5985085 100644 --- a/lib/pleroma/web/streamer/supervisor.ex +++ b/lib/pleroma/web/streamer/supervisor.ex @@ -1,3 +1,7 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + defmodule Pleroma.Web.Streamer.Supervisor do use Supervisor diff --git a/lib/pleroma/web/streamer/worker.ex b/lib/pleroma/web/streamer/worker.ex index 5804508eb..bbb7483e5 100644 --- a/lib/pleroma/web/streamer/worker.ex +++ b/lib/pleroma/web/streamer/worker.ex @@ -1,3 +1,7 @@ +# Pleroma: A lightweight social networking server +# Copyright © 2017-2019 Pleroma Authors +# SPDX-License-Identifier: AGPL-3.0-only + defmodule Pleroma.Web.Streamer.Worker do use GenServer -- cgit v1.2.3 From 5a0c018d2a6d3cea15761c1cc51691dcb85a0c97 Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Fri, 4 Oct 2019 15:41:55 +0000 Subject: streamer: worker: check for lack of intersectionality between a user's blocklist and an activity's recipientlist --- lib/pleroma/web/streamer/worker.ex | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lib/pleroma/web/streamer/worker.ex b/lib/pleroma/web/streamer/worker.ex index bbb7483e5..3d2c8f473 100644 --- a/lib/pleroma/web/streamer/worker.ex +++ b/lib/pleroma/web/streamer/worker.ex @@ -132,11 +132,14 @@ defmodule Pleroma.Web.Streamer.Worker do blocks = user.info.blocks || [] mutes = user.info.mutes || [] reblog_mutes = user.info.muted_reblogs || [] + recipient_blocks = MapSet.new(blocks ++ mutes) + recipients = MapSet.new(item.recipients) domain_blocks = Pleroma.Web.ActivityPub.MRF.subdomains_regex(user.info.domain_blocks) with parent when not is_nil(parent) <- Object.normalize(item), true <- Enum.all?([blocks, mutes, reblog_mutes], &(item.actor not in &1)), true <- Enum.all?([blocks, mutes], &(parent.data["actor"] not in &1)), + true <- MapSet.disjoint?(recipients, recipient_blocks), %{host: item_host} <- URI.parse(item.actor), %{host: parent_host} <- URI.parse(parent.data["actor"]), false <- Pleroma.Web.ActivityPub.MRF.subdomain_match?(domain_blocks, item_host), -- cgit v1.2.3 From d1d058bf85a94909cb0c599bb5f2bd469de804d5 Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Fri, 4 Oct 2019 15:42:25 +0000 Subject: streamer: worker: actually use should_send? consistently --- lib/pleroma/web/streamer/worker.ex | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/lib/pleroma/web/streamer/worker.ex b/lib/pleroma/web/streamer/worker.ex index 3d2c8f473..0ea224874 100644 --- a/lib/pleroma/web/streamer/worker.ex +++ b/lib/pleroma/web/streamer/worker.ex @@ -201,11 +201,8 @@ defmodule Pleroma.Web.Streamer.Worker do # Get the current user so we have up-to-date blocks etc. if socket_user do user = User.get_cached_by_ap_id(socket_user.ap_id) - blocks = user.info.blocks || [] - mutes = user.info.mutes || [] - with true <- Enum.all?([blocks, mutes], &(item.actor not in &1)), - true <- thread_containment(item, user) do + if should_send?(user, item) do send(transport_pid, {:text, StreamerView.render("update.json", item, user)}) end else -- cgit v1.2.3 From dbf5fce67e39821b8f3caa7f3f59deeb95754bce Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Fri, 4 Oct 2019 15:45:06 +0000 Subject: update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ebc46b7d..4a904a3f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -76,6 +76,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - ActivityPub: Deactivated user deletion - ActivityPub: Fix `/users/:nickname/inbox` crashing without an authenticated user - MRF: fix ability to follow a relay when AntiFollowbotPolicy was enabled +- Mastodon API: Blocks are now treated consistently between the Streaming API and the Timeline APIs ### Added - Expiring/ephemeral activites. All activities can have expires_at value set, which controls when they should be deleted automatically. -- cgit v1.2.3 From 83631752af053b02a05abe0e9f7d6c7cf9a5154a Mon Sep 17 00:00:00 2001 From: Maksim Pechnikov Date: Fri, 4 Oct 2019 22:20:53 +0300 Subject: removed legacy api: "/objects/:uuid/likes" --- .../web/activity_pub/activity_pub_controller.ex | 32 ----------- lib/pleroma/web/activity_pub/utils.ex | 10 ---- lib/pleroma/web/activity_pub/views/object_view.ex | 36 ------------- lib/pleroma/web/router.ex | 1 - .../activity_pub/activity_pub_controller_test.exs | 63 ---------------------- 5 files changed, 142 deletions(-) diff --git a/lib/pleroma/web/activity_pub/activity_pub_controller.ex b/lib/pleroma/web/activity_pub/activity_pub_controller.ex index 7cd13b4b8..080030eb5 100644 --- a/lib/pleroma/web/activity_pub/activity_pub_controller.ex +++ b/lib/pleroma/web/activity_pub/activity_pub_controller.ex @@ -82,38 +82,6 @@ defmodule Pleroma.Web.ActivityPub.ActivityPubController do conn end - def object_likes(conn, %{"uuid" => uuid, "page" => page}) do - with ap_id <- o_status_url(conn, :object, uuid), - %Object{} = object <- Object.get_cached_by_ap_id(ap_id), - {_, true} <- {:public?, Visibility.is_public?(object)}, - likes <- Utils.get_object_likes(object) do - {page, _} = Integer.parse(page) - - conn - |> put_resp_content_type("application/activity+json") - |> put_view(ObjectView) - |> render("likes.json", %{ap_id: ap_id, likes: likes, page: page}) - else - {:public?, false} -> - {:error, :not_found} - end - end - - def object_likes(conn, %{"uuid" => uuid}) do - with ap_id <- o_status_url(conn, :object, uuid), - %Object{} = object <- Object.get_cached_by_ap_id(ap_id), - {_, true} <- {:public?, Visibility.is_public?(object)}, - likes <- Utils.get_object_likes(object) do - conn - |> put_resp_content_type("application/activity+json") - |> put_view(ObjectView) - |> render("likes.json", %{ap_id: ap_id, likes: likes}) - else - {:public?, false} -> - {:error, :not_found} - end - end - def activity(conn, %{"uuid" => uuid}) do with ap_id <- o_status_url(conn, :activity, uuid), %Activity{} = activity <- Activity.normalize(ap_id), diff --git a/lib/pleroma/web/activity_pub/utils.ex b/lib/pleroma/web/activity_pub/utils.ex index ac5550671..272011a9f 100644 --- a/lib/pleroma/web/activity_pub/utils.ex +++ b/lib/pleroma/web/activity_pub/utils.ex @@ -251,16 +251,6 @@ defmodule Pleroma.Web.ActivityPub.Utils do |> Repo.one() end - @doc """ - Returns like activities targeting an object - """ - def get_object_likes(%{data: %{"id" => id}}) do - id - |> Activity.Queries.by_object_id() - |> Activity.Queries.by_type("Like") - |> Repo.all() - end - @spec make_like_data(User.t(), map(), String.t()) :: map() def make_like_data( %User{ap_id: ap_id} = actor, diff --git a/lib/pleroma/web/activity_pub/views/object_view.ex b/lib/pleroma/web/activity_pub/views/object_view.ex index 88c55acdd..d8a3ec288 100644 --- a/lib/pleroma/web/activity_pub/views/object_view.ex +++ b/lib/pleroma/web/activity_pub/views/object_view.ex @@ -37,40 +37,4 @@ defmodule Pleroma.Web.ActivityPub.ObjectView do Map.merge(base, additional) end - - def render("likes.json", %{ap_id: ap_id, likes: likes, page: page}) do - collection(likes, "#{ap_id}/likes", page) - |> Map.merge(Pleroma.Web.ActivityPub.Utils.make_json_ld_header()) - end - - def render("likes.json", %{ap_id: ap_id, likes: likes}) do - %{ - "id" => "#{ap_id}/likes", - "type" => "OrderedCollection", - "totalItems" => length(likes), - "first" => collection(likes, "#{ap_id}/likes", 1) - } - |> Map.merge(Pleroma.Web.ActivityPub.Utils.make_json_ld_header()) - end - - def collection(collection, iri, page) do - offset = (page - 1) * 10 - items = Enum.slice(collection, offset, 10) - items = Enum.map(items, fn object -> Transmogrifier.prepare_object(object.data) end) - total = length(collection) - - map = %{ - "id" => "#{iri}?page=#{page}", - "type" => "OrderedCollectionPage", - "partOf" => iri, - "totalItems" => total, - "orderedItems" => items - } - - if offset + length(items) < total do - Map.put(map, "next", "#{iri}?page=#{page + 1}") - else - map - end - end end diff --git a/lib/pleroma/web/router.ex b/lib/pleroma/web/router.ex index f91af8137..405ae724e 100644 --- a/lib/pleroma/web/router.ex +++ b/lib/pleroma/web/router.ex @@ -580,7 +580,6 @@ defmodule Pleroma.Web.Router do pipe_through(:ostatus) get("/users/:nickname/outbox", ActivityPubController, :outbox) - get("/objects/:uuid/likes", ActivityPubController, :object_likes) end pipeline :activitypub_client do diff --git a/test/web/activity_pub/activity_pub_controller_test.exs b/test/web/activity_pub/activity_pub_controller_test.exs index 1ffa91b70..6a3e48b5e 100644 --- a/test/web/activity_pub/activity_pub_controller_test.exs +++ b/test/web/activity_pub/activity_pub_controller_test.exs @@ -225,69 +225,6 @@ defmodule Pleroma.Web.ActivityPub.ActivityPubControllerTest do end end - describe "/object/:uuid/likes" do - setup do - like = insert(:like_activity) - like_object_ap_id = Object.normalize(like).data["id"] - - uuid = - like_object_ap_id - |> String.split("/") - |> List.last() - - [id: like.data["id"], uuid: uuid] - end - - test "it returns the like activities in a collection", %{conn: conn, id: id, uuid: uuid} do - result = - conn - |> put_req_header("accept", "application/activity+json") - |> get("/objects/#{uuid}/likes") - |> json_response(200) - - assert List.first(result["first"]["orderedItems"])["id"] == id - assert result["type"] == "OrderedCollection" - assert result["totalItems"] == 1 - refute result["first"]["next"] - end - - test "it does not crash when page number is exceeded total pages", %{conn: conn, uuid: uuid} do - result = - conn - |> put_req_header("accept", "application/activity+json") - |> get("/objects/#{uuid}/likes?page=2") - |> json_response(200) - - assert result["type"] == "OrderedCollectionPage" - assert result["totalItems"] == 1 - refute result["next"] - assert Enum.empty?(result["orderedItems"]) - end - - test "it contains the next key when likes count is more than 10", %{conn: conn} do - note = insert(:note_activity) - insert_list(11, :like_activity, note_activity: note) - - uuid = - note - |> Object.normalize() - |> Map.get(:data) - |> Map.get("id") - |> String.split("/") - |> List.last() - - result = - conn - |> put_req_header("accept", "application/activity+json") - |> get("/objects/#{uuid}/likes?page=1") - |> json_response(200) - - assert result["totalItems"] == 11 - assert length(result["orderedItems"]) == 10 - assert result["next"] - end - end - describe "/activities/:uuid" do test "it returns a json representation of the activity", %{conn: conn} do activity = insert(:note_activity) -- cgit v1.2.3