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
This commit is contained in:
rinpatch 2021-01-10 08:25:36 +00:00
commit ad5338a79c
20 changed files with 127 additions and 41 deletions

2
.gitignore vendored
View file

@ -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

View file

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

View file

@ -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).

View file

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

View file

@ -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).

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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`

View file

@ -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

View file

@ -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

View file

@ -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