Merge branch 'add_some_information_about_setting_up_a_development_environment' into 'develop'

Add some information about setting up a development environment

Closes #1904

See merge request pleroma/pleroma!3207

.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

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]
+        }
+      ]
+    }
+```

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).
+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]
-        }
-      ]
-    }
-```

docs/development/index.md

@@ -0,0 +1 @@
+This section contains notes and guidelines for developers.

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://<host>:<port>` (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).

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

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

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

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

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

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`
 

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

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

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 index if exists objects_fts")
-    execute "drop trigger if exists tsvectorupdate on objects"
+    execute("drop trigger if exists tsvectorupdate on objects")
-    execute "drop function if exists objects_fts_update()"
+    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