From 6284e8f4b2e9b737d1ed256e89f2ac3ba673d6f8 Mon Sep 17 00:00:00 2001 From: Ilja Date: Sun, 10 Jan 2021 08:25:36 +0000 Subject: [PATCH] Add development section * I cretaed a folder 'development' * I split up the file dev.md into three parts and moved it to this folder * index.md * authentication_authorization.md * mrf.md * I also moved ap_extensions.md * I created a new file setting_up_pleroma_dev.md --- .gitignore | 2 +- docs/configuration/mrf.md | 23 ++++++ docs/{ => development}/API/admin_api.md | 0 docs/{ => development}/API/chats.md | 0 .../API/differences_in_mastoapi_responses.md | 0 docs/{ => development}/API/pleroma_api.md | 0 docs/{ => development}/API/prometheus.md | 0 docs/{ => development}/ap_extensions.md | 0 .../authentication_authorization.md} | 27 +------ docs/development/index.md | 1 + docs/development/setting_up_pleroma_dev.md | 70 +++++++++++++++++++ docs/installation/alpine_linux_en.md | 2 +- docs/installation/arch_linux_en.md | 2 +- docs/installation/debian_based_en.md | 2 +- docs/installation/debian_based_jp.md | 2 +- docs/installation/freebsd_en.md | 2 +- docs/installation/netbsd_en.md | 2 +- docs/installation/openbsd_en.md | 2 +- docs/installation/openbsd_fi.md | 2 +- ...510135645_add_fts_index_to_objects_two.exs | 29 ++++++-- 20 files changed, 127 insertions(+), 41 deletions(-) rename docs/{ => development}/API/admin_api.md (100%) rename docs/{ => development}/API/chats.md (100%) rename docs/{ => development}/API/differences_in_mastoapi_responses.md (100%) rename docs/{ => development}/API/pleroma_api.md (100%) rename docs/{ => development}/API/prometheus.md (100%) rename docs/{ => development}/ap_extensions.md (100%) rename docs/{dev.md => development/authentication_authorization.md} (72%) create mode 100644 docs/development/index.md create mode 100644 docs/development/setting_up_pleroma_dev.md diff --git a/.gitignore b/.gitignore index 62ca61bce..4dea75e93 100644 --- a/.gitignore +++ b/.gitignore @@ -32,7 +32,7 @@ erl_crash.dump # Database setup file, some may forget to delete it -/config/setup_db.psql +/config/setup_db*.psql .DS_Store .env diff --git a/docs/configuration/mrf.md b/docs/configuration/mrf.md index 31c66e098..9e8c0a2d7 100644 --- a/docs/configuration/mrf.md +++ b/docs/configuration/mrf.md @@ -133,3 +133,26 @@ config :pleroma, :mrf, ``` 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. + +### MRF policies descriptions + +If MRF policy depends on config, it can be added into MRF tab to adminFE by adding `config_description/0` method, which returns a map with a specific structure. See existing MRF's like `lib/pleroma/web/activity_pub/mrf/activity_expiration_policy.ex` for examples. Note that more complex inputs, like tuples or maps, may need extra changes in the adminFE and just adding it to `config_description/0` may not be enough to get these inputs working from the adminFE. + +Example: + +```elixir +%{ + key: :mrf_activity_expiration, + related_policy: "Pleroma.Web.ActivityPub.MRF.ActivityExpirationPolicy", + label: "MRF Activity Expiration Policy", + description: "Adds automatic expiration to all local activities", + children: [ + %{ + key: :days, + type: :integer, + description: "Default global expiration time for all local activities (in days)", + suggestions: [90, 365] + } + ] + } +``` diff --git a/docs/API/admin_api.md b/docs/development/API/admin_api.md similarity index 100% rename from docs/API/admin_api.md rename to docs/development/API/admin_api.md diff --git a/docs/API/chats.md b/docs/development/API/chats.md similarity index 100% rename from docs/API/chats.md rename to docs/development/API/chats.md diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md similarity index 100% rename from docs/API/differences_in_mastoapi_responses.md rename to docs/development/API/differences_in_mastoapi_responses.md diff --git a/docs/API/pleroma_api.md b/docs/development/API/pleroma_api.md similarity index 100% rename from docs/API/pleroma_api.md rename to docs/development/API/pleroma_api.md diff --git a/docs/API/prometheus.md b/docs/development/API/prometheus.md similarity index 100% rename from docs/API/prometheus.md rename to docs/development/API/prometheus.md diff --git a/docs/ap_extensions.md b/docs/development/ap_extensions.md similarity index 100% rename from docs/ap_extensions.md rename to docs/development/ap_extensions.md diff --git a/docs/dev.md b/docs/development/authentication_authorization.md similarity index 72% rename from docs/dev.md rename to docs/development/authentication_authorization.md index 765380a58..183bfc2c9 100644 --- a/docs/dev.md +++ b/docs/development/authentication_authorization.md @@ -1,5 +1,3 @@ -This document contains notes and guidelines for Pleroma developers. - # Authentication & Authorization ## OAuth token-based authentication & authorization @@ -20,27 +18,4 @@ This document contains notes and guidelines for Pleroma developers. ## Auth-related configuration, OAuth consumer mode etc. -See `Authentication` section of [the configuration cheatsheet](configuration/cheatsheet.md#authentication). - -## MRF policies descriptions - -If MRF policy depends on config, it can be added into MRF tab to adminFE by adding `config_description/0` method, which returns map with special structure. - -Example: - -```elixir -%{ - key: :mrf_activity_expiration, - related_policy: "Pleroma.Web.ActivityPub.MRF.ActivityExpirationPolicy", - label: "MRF Activity Expiration Policy", - description: "Adds automatic expiration to all local activities", - children: [ - %{ - key: :days, - type: :integer, - description: "Default global expiration time for all local activities (in days)", - suggestions: [90, 365] - } - ] - } -``` +See `Authentication` section of [the configuration cheatsheet](../configuration/cheatsheet.md#authentication). diff --git a/docs/development/index.md b/docs/development/index.md new file mode 100644 index 000000000..01a617596 --- /dev/null +++ b/docs/development/index.md @@ -0,0 +1 @@ +This section contains notes and guidelines for developers. diff --git a/docs/development/setting_up_pleroma_dev.md b/docs/development/setting_up_pleroma_dev.md new file mode 100644 index 000000000..8da761d62 --- /dev/null +++ b/docs/development/setting_up_pleroma_dev.md @@ -0,0 +1,70 @@ +# Setting up a Pleroma development environment + +Pleroma requires some adjustments from the defaults for running the instance locally. The following should help you to get started. + +## Installing + +1. Install Pleroma as explained in [the docs](../installation/debian_based_en.md), with some exceptions: + * You can use your own fork of the repository and add pleroma as a remote `git remote add pleroma 'https://git.pleroma.social/pleroma/pleroma'` + * You can skip systemd and nginx and all that stuff + * No need to create a dedicated pleroma user, it's easier to just use your own user + * For the DB you can still choose a dedicated user, the mix tasks set it up for you so it's no extra work for you + * For domain you can use `localhost` + * instead of creating a `prod.secret.exs`, create `dev.secret.exs` + * No need to prefix with `MIX_ENV=prod`. We're using dev and that's the default MIX_ENV +2. Change the dev.secret.exs + * Change the scheme in `config :pleroma, Pleroma.Web.Endpoint` to http (see examples below) + * If you want to change other settings, you can do that too +3. You can now start the server `mix phx.server`. Once it's build and started, you can access the instance on `http://:` (e.g.http://localhost:4000 ) and should be able to do everything locally you normaly can. + +Example config to change the scheme to http. Change the port if you want to run on another port. +```elixir + config :pleroma, Pleroma.Web.Endpoint, + url: [host: "localhost", scheme: "http", port: 4000], +``` + +Example config to disable captcha. This makes it a bit easier to create test-users. +```elixir +config :pleroma, Pleroma.Captcha, + enabled: false +``` + +Example config to change the log level to info +```elixir +config :logger, :console, + # :debug :info :warning :error + level: :info +``` + +## Testing + +1. Create a `test.secret.exs` file with the content as shown below +2. Create the database user and test database. + 1. You can use the `config/setup_db.psql` as a template. Copy the file if you want and change the database name, user and password to the values for the test-database (e.g. 'pleroma_local_test' for database and user). Then run this file like you did during installation. + 2. The tests will try to create the Database, so we'll have to allow our test-database user to create databases, `sudo -Hu postgres psql -c "ALTER USER pleroma_local_test WITH CREATEDB;"` +3. Run the tests with `mix test`. The tests should succeed. + +Example content for the `test.secret.exs` file. Feel free to use another user, database name or password, just make sure the database is dedicated for the testing environment. +```elixir +# Pleroma test configuration + +# NOTE: This file should not be committed to a repo or otherwise made public +# without removing sensitive information. + +import Config + +config :pleroma, Pleroma.Repo, + username: "pleroma_local_test", + password: "mysuperduperpassword", + database: "pleroma_local_test", + hostname: "localhost" + +``` + +## Updating + +Update Pleroma as explained in [the docs](../administration/updating.md). Just make sure you pull from upstream and not from your own fork. + +## Working on multiple branches + +If you develop on a separate branch, it's possible you did migrations that aren't merged into another branch you're working on. If you have multiple things you're working on, it's probably best to set up multiple pleroma's each with their own database. If you finished with a branch and want to switch back to develop to start a new branch from there, you can drop the database and recreate the database (e.g. by using `config/setup_db.psql`). The commands to drop and recreate the database can be found in [the docs](../administration/backup.md). diff --git a/docs/installation/alpine_linux_en.md b/docs/installation/alpine_linux_en.md index 62f2fb778..2f8520a78 100644 --- a/docs/installation/alpine_linux_en.md +++ b/docs/installation/alpine_linux_en.md @@ -80,7 +80,7 @@ sudo /etc/init.d/postgresql start sudo rc-update add postgresql ``` -### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md)) +### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md)) ```shell sudo apk add ffmpeg imagemagick exiftool diff --git a/docs/installation/arch_linux_en.md b/docs/installation/arch_linux_en.md index 0eb6d2d5f..9cbd3f429 100644 --- a/docs/installation/arch_linux_en.md +++ b/docs/installation/arch_linux_en.md @@ -56,7 +56,7 @@ sudo -iu postgres initdb -D /var/lib/postgres/data sudo systemctl enable --now postgresql.service ``` -### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md)) +### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md)) ```shell sudo pacman -S ffmpeg imagemagick perl-image-exiftool diff --git a/docs/installation/debian_based_en.md b/docs/installation/debian_based_en.md index 2b1c7406f..926a85367 100644 --- a/docs/installation/debian_based_en.md +++ b/docs/installation/debian_based_en.md @@ -54,7 +54,7 @@ sudo apt update sudo apt install elixir erlang-dev erlang-nox ``` -### Optional packages: [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md) +### Optional packages: [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md) ```shell sudo apt install imagemagick ffmpeg libimage-exiftool-perl diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 94e22325c..2613a86d9 100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -54,7 +54,7 @@ sudo apt update sudo apt install elixir erlang-dev erlang-nox ``` -### オプションパッケージ: [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md) +### オプションパッケージ: [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md) ```shell sudo apt install imagemagick ffmpeg libimage-exiftool-perl diff --git a/docs/installation/freebsd_en.md b/docs/installation/freebsd_en.md index fdcb06c53..2dc466eb8 100644 --- a/docs/installation/freebsd_en.md +++ b/docs/installation/freebsd_en.md @@ -26,7 +26,7 @@ Setup the required services to automatically start at boot, using `sysrc(8)`. # service postgresql start ``` -### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md)) +### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md)) ```shell # pkg install imagemagick ffmpeg p5-Image-ExifTool diff --git a/docs/installation/netbsd_en.md b/docs/installation/netbsd_en.md index d5fa04fdf..233cf28b7 100644 --- a/docs/installation/netbsd_en.md +++ b/docs/installation/netbsd_en.md @@ -44,7 +44,7 @@ pgsql=YES First, run `# /etc/rc.d/pgsql start`. Then, `$ sudo -Hu pgsql -g pgsql createdb`. -### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md)) +### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md)) `# pkgin install ImageMagick ffmpeg4 p5-Image-ExifTool` diff --git a/docs/installation/openbsd_en.md b/docs/installation/openbsd_en.md index 8092ac379..0e1269ca5 100644 --- a/docs/installation/openbsd_en.md +++ b/docs/installation/openbsd_en.md @@ -27,7 +27,7 @@ Pleroma requires a reverse proxy, OpenBSD has relayd in base (and is used in thi #### Optional software -Per [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md): +Per [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md): * ImageMagick * ffmpeg * exiftool diff --git a/docs/installation/openbsd_fi.md b/docs/installation/openbsd_fi.md index 01cf34ab4..a61434147 100644 --- a/docs/installation/openbsd_fi.md +++ b/docs/installation/openbsd_fi.md @@ -20,7 +20,7 @@ Asenna tarvittava ohjelmisto: #### Optional software -[`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md): +[`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md): * ImageMagick * ffmpeg * exiftool diff --git a/priv/repo/optional_migrations/rum_indexing/20190510135645_add_fts_index_to_objects_two.exs b/priv/repo/optional_migrations/rum_indexing/20190510135645_add_fts_index_to_objects_two.exs index 757afa129..82e02281d 100644 --- a/priv/repo/optional_migrations/rum_indexing/20190510135645_add_fts_index_to_objects_two.exs +++ b/priv/repo/optional_migrations/rum_indexing/20190510135645_add_fts_index_to_objects_two.exs @@ -3,7 +3,14 @@ defmodule Pleroma.Repo.Migrations.AddFtsIndexToObjectsTwo do def up do execute("create extension if not exists rum") - drop_if_exists index(:objects, ["(to_tsvector('english', data->>'content'))"], using: :gin, name: :objects_fts) + + drop_if_exists( + index(:objects, ["(to_tsvector('english', data->>'content'))"], + using: :gin, + name: :objects_fts + ) + ) + alter table(:objects) do add(:fts_content, :tsvector) end @@ -14,7 +21,10 @@ defmodule Pleroma.Repo.Migrations.AddFtsIndexToObjectsTwo do return new; end $$ LANGUAGE plpgsql") - execute("create index if not exists objects_fts on objects using RUM (fts_content rum_tsvector_addon_ops, inserted_at) with (attach = 'inserted_at', to = 'fts_content');") + + execute( + "create index if not exists objects_fts on objects using RUM (fts_content rum_tsvector_addon_ops, inserted_at) with (attach = 'inserted_at', to = 'fts_content');" + ) execute("CREATE TRIGGER tsvectorupdate BEFORE INSERT OR UPDATE ON objects FOR EACH ROW EXECUTE PROCEDURE objects_fts_update()") @@ -23,12 +33,19 @@ defmodule Pleroma.Repo.Migrations.AddFtsIndexToObjectsTwo do end def down do - execute "drop index if exists objects_fts" - execute "drop trigger if exists tsvectorupdate on objects" - execute "drop function if exists objects_fts_update()" + execute("drop index if exists objects_fts") + execute("drop trigger if exists tsvectorupdate on objects") + execute("drop function if exists objects_fts_update()") + alter table(:objects) do remove(:fts_content, :tsvector) end - create_if_not_exists index(:objects, ["(to_tsvector('english', data->>'content'))"], using: :gin, name: :objects_fts) + + create_if_not_exists( + index(:objects, ["(to_tsvector('english', data->>'content'))"], + using: :gin, + name: :objects_fts + ) + ) end end