diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/API/admin_api.md | 65 | ||||
| -rw-r--r-- | docs/administration/CLI_tasks/frontend.md | 69 | ||||
| -rw-r--r-- | docs/clients.md | 35 | ||||
| -rw-r--r-- | docs/configuration/cheatsheet.md | 17 | ||||
| -rw-r--r-- | docs/installation/freebsd_en.md | 210 |
5 files changed, 347 insertions, 49 deletions
diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index 4b143e4ee..c0ea074f0 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -313,31 +313,53 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On failure: `Not found` - On success: JSON array of user's latest statuses +## `GET /api/pleroma/admin/relay` + +### List Relays + +Params: none +Response: + +* On success: JSON array of relays + +```json +[ + {"actor": "https://example.com/relay", "followed_back": true}, + {"actor": "https://example2.com/relay", "followed_back": false} +] +``` + ## `POST /api/pleroma/admin/relay` ### Follow a Relay -- Params: - - `relay_url` -- Response: - - On success: URL of the followed relay +Params: + +* `relay_url` + +Response: + +* On success: relay json object + +```json +{"actor": "https://example.com/relay", "followed_back": true} +``` ## `DELETE /api/pleroma/admin/relay` ### Unfollow a Relay -- Params: - - `relay_url` -- Response: - - On success: URL of the unfollowed relay +Params: -## `GET /api/pleroma/admin/relay` +* `relay_url` -### List Relays +Response: -- Params: none -- Response: - - On success: JSON array of relays +* On success: URL of the unfollowed relay + +```json +{"https://example.com/relay"} +``` ## `POST /api/pleroma/admin/users/invite_token` @@ -1266,11 +1288,14 @@ Loads json generated from `config/descriptions.exs`. - Params: - *optional* `page`: **integer** page number - *optional* `page_size`: **integer** number of log entries per page (default is `50`) +- *optional* `query`: **string** search term - Response: ``` json { + "page_size": integer, + "count": integer, "urls": [ "http://example.com/media/a688346.jpg", "http://example.com/media/fb1f4d.jpg" @@ -1290,12 +1315,7 @@ Loads json generated from `config/descriptions.exs`. - Response: ``` json -{ - "urls": [ - "http://example.com/media/a688346.jpg", - "http://example.com/media/fb1f4d.jpg" - ] -} +{ } ``` @@ -1311,11 +1331,6 @@ Loads json generated from `config/descriptions.exs`. - Response: ``` json -{ - "urls": [ - "http://example.com/media/a688346.jpg", - "http://example.com/media/fb1f4d.jpg" - ] -} +{ } ``` diff --git a/docs/administration/CLI_tasks/frontend.md b/docs/administration/CLI_tasks/frontend.md new file mode 100644 index 000000000..7d1c1e937 --- /dev/null +++ b/docs/administration/CLI_tasks/frontend.md @@ -0,0 +1,69 @@ +# Managing frontends + +`mix pleroma.frontend install <frontend> [--ref <ref>] [--file <file>] [--build-url <build-url>] [--path <path>] [--build-dir <build-dir>]` + +Frontend can be installed either from local zip file, or automatically downloaded from the web. + +You can give all the options directly on the command like, but missing information will be filled out by looking at the data configured under `frontends.available` in the config files. + +Currently known `<frontend>` values are: +- [admin-fe](https://git.pleroma.social/pleroma/admin-fe) +- [kenoma](http://git.pleroma.social/lambadalambda/kenoma) +- [pleroma-fe](http://git.pleroma.social/pleroma/pleroma-fe) +- [fedi-fe](https://git.pleroma.social/pleroma/fedi-fe) +- [soapbox-fe](https://gitlab.com/soapbox-pub/soapbox-fe) + +You can still install frontends that are not configured, see below. + +## Example installations for a known frontend + +For a frontend configured under the `available` key, it's enough to install it by name. + +```sh tab="OTP" +./bin/pleroma_ctl frontend install pleroma +``` + +```sh tab="From Source" +mix pleroma.frontend install pleroma +``` + +This will download the latest build for the the pre-configured `ref` and install it. It can then be configured as the one of the served frontends in the config file (see `primary` or `admin`). + +You can override any of the details. To install a pleroma build from a different url, you could do this: + +```sh tab="OPT" +./bin/pleroma_ctl frontend install pleroma --ref 2hu_edition --build-url https://example.org/raymoo.zip +``` + +```sh tab="From Source" +mix pleroma.frontend install pleroma --ref 2hu_edition --build-url https://example.org/raymoo.zip +``` + +Similarly, you can also install from a local zip file. + +```sh tab="OTP" +./bin/pleroma_ctl frontend install pleroma --ref mybuild --file ~/Downloads/doomfe.zip +``` + +```sh tab="From Source" +mix pleroma.frontend install pleroma --ref mybuild --file ~/Downloads/doomfe.zip +``` + +The resulting frontend will always be installed into a folder of this template: `${instance_static}/frontends/${name}/${ref}` + +Careful: This folder will be completely replaced on installation + +## Example installation for an unknown frontend + +The installation process is the same, but you will have to give all the needed options on the commond line. For example: + +```sh tab="OTP" +./bin/pleroma_ctl frontend install gensokyo --ref master --build-url https://gensokyo.2hu/builds/marisa.zip +``` + +```sh tab="From Source" +mix pleroma.frontend install gensokyo --ref master --build-url https://gensokyo.2hu/builds/marisa.zip +``` + +If you don't have a zip file but just want to install a frontend from a local path, you can simply copy the files over a folder of this template: `${instance_static}/frontends/${name}/${ref}` + diff --git a/docs/clients.md b/docs/clients.md index 2a42c659f..f84295b1f 100644 --- a/docs/clients.md +++ b/docs/clients.md @@ -6,11 +6,11 @@ Feel free to contact us to be added to this list! ### Roma for Desktop - Homepage: <https://www.pleroma.com/#desktopApp> - Source Code: <https://github.com/roma-apps/roma-desktop> -- Platforms: Windows, Mac, (Linux?) +- Platforms: Windows, Mac, Linux - Features: Streaming Ready ### Social -- Source Code: <https://gitlab.gnome.org/BrainBlasted/Social> +- Source Code: <https://gitlab.gnome.org/World/Social> - Contact: [@brainblasted@social.libre.fi](https://social.libre.fi/users/brainblasted) - Platforms: Linux (GNOME) - Note(2019-01-28): Not at a pre-alpha stage yet @@ -35,7 +35,7 @@ Feel free to contact us to be added to this list! - Source Code: <https://framagit.org/tom79/fedilab/> - Contact: [@fedilab@framapiaf.org](https://framapiaf.org/users/fedilab) - Platforms: Android -- Features: Streaming Ready, Moderation, Text Formatting +- Features: Streaming Ready, Moderation, Text Formatting ### Kyclos - Source Code: <https://git.pleroma.social/pleroma/harbour-kyclos> @@ -48,16 +48,9 @@ Feel free to contact us to be added to this list! - Platforms: Android - Features: No Streaming, Emoji Reactions, Text Formatting, FE Stickers -### Nekonium -- Homepage: [F-Droid Repository](https://repo.gdgd.jp.net/), [Google Play](https://play.google.com/store/apps/details?id=com.apps.nekonium), [Amazon](https://www.amazon.co.jp/dp/B076FXPRBC/) -- Source: <https://gogs.gdgd.jp.net/lin/nekonium> -- Contact: [@lin@pleroma.gdgd.jp.net](https://pleroma.gdgd.jp.net/users/lin) -- Platforms: Android -- Features: Streaming Ready - ### Fedi - Homepage: <https://www.fediapp.com/> -- Source Code: Proprietary, but free +- Source Code: Proprietary, but gratis - Platforms: iOS, Android - Features: Pleroma-specific features like Reactions @@ -70,9 +63,9 @@ Feel free to contact us to be added to this list! ### Twidere - Homepage: <https://twidere.mariotaku.org/> -- Source Code: <https://github.com/TwidereProject/Twidere-Android/>, <https://github.com/TwidereProject/Twidere-iOS/> +- Source Code: <https://github.com/TwidereProject/Twidere-Android/> - Contact: <me@mariotaku.org> -- Platform: Android, iOS +- Platform: Android - Features: No Streaming ### Indigenous @@ -89,11 +82,6 @@ Feel free to contact us to be added to this list! - Contact: [@gcupc@glitch.social](https://glitch.social/users/gcupc) - Features: No Streaming -### Feather -- Source Code: <https://github.com/kaniini/feather> -- Contact: [@kaniini@pleroma.site](https://pleroma.site/kaniini) -- Features: No Streaming - ### Halcyon - Source Code: <https://notabug.org/halcyon-suite/halcyon> - Contact: [@halcyon@social.csswg.org](https://social.csswg.org/users/halcyon) @@ -107,6 +95,15 @@ Feel free to contact us to be added to this list! - Features: No Streaming ### Sengi +- Homepage: <https://nicolasconstant.github.io/sengi/> - Source Code: <https://github.com/NicolasConstant/sengi> - Contact: [@sengi_app@mastodon.social](https://mastodon.social/users/sengi_app) -- Note(2019-01-28): The development is currently in a early stage. + +### DashFE +- Source Code: <https://notabug.org/daisuke/DashboardFE> +- Contact: [@dashfe@stereophonic.space](https://stereophonic.space/users/dashfe) + +### BloatFE +- Source Code: <https://git.freesoftwareextremist.com/bloat/> +- Contact: [@r@freesoftwareextremist.com](https://freesoftwareextremist.com/users/r) +- Features: Does not requires JavaScript diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index e5742bc3a..a09d6b6b2 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -38,8 +38,8 @@ To add configuration to your config file, you can copy it from the base config. * `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. -* `public`: Makes the client API in authenticated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network. See also: `restrict_unauthenticated`. -* `quarantined_instances`: List of ActivityPub instances where private(DMs, followers-only) activities will not be send. +* `public`: Makes the client API in authenticated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network. Note that there is a dependent setting restricting or allowing unauthenticated access to specific resources, see `restrict_unauthenticated` for more details. +* `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 [:frontend_configurations](#frontend_configurations) or in ``static/config.json``. * `allowed_post_formats`: MIME-type list of formats allowed to be posted (transformed into HTML). * `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with @@ -552,6 +552,7 @@ the source code is here: [kocaptcha](https://github.com/koto-bank/kocaptcha). Th * `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. * `filename_display_max_length`: Set max length of a filename to display. 0 = no limit. Default: 30. +* `default_description`: Sets which default description an image has if none is set explicitly. Options: nil (default) - Don't set a default, :filename - use the filename of the file, a string (e.g. "attachment") - Use this string !!! warning `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`. @@ -1051,6 +1052,8 @@ Restrict access for unauthenticated users to timelines (public and federated), u * `local` * `remote` +Note: when `:instance, :public` is set to `false`, all `:restrict_unauthenticated` items be effectively set to `true` by default. If you'd like to allow unauthenticated access to specific API endpoints on a private instance, please explicitly set `:restrict_unauthenticated` to non-default value in `config/prod.secret.exs`. + Note: setting `restrict_unauthenticated/timelines/local` to `true` has no practical sense if `restrict_unauthenticated/timelines/federated` is set to `false` (since local public activities will still be delivered to unauthenticated users as part of federated timeline). ## Pleroma.Web.ApiSpec.CastAndValidate @@ -1067,11 +1070,11 @@ Control favicons for instances. Frontends in Pleroma are swappable - you can specify which one to use here. -For now, you can set a frontend with the key `primary` and the options of `name` and `ref`. This will then make Pleroma serve the frontend from a folder constructed by concatenating the instance static path, `frontends` and the name and ref. +You can set a frontends for the key `primary` and `admin` and the options of `name` and `ref`. This will then make Pleroma serve the frontend from a folder constructed by concatenating the instance static path, `frontends` and the name and ref. -The key `primary` refers to the frontend that will be served by default for general requests. In the future, other frontends like the admin frontend will also be configurable here. +The key `primary` refers to the frontend that will be served by default for general requests. The key `admin` refers to the frontend that will be served at the `/pleroma/admin` path. -If you don't set anything here, the bundled frontend will be used. +If you don't set anything here, the bundled frontends will be used. Example: @@ -1080,6 +1083,10 @@ config :pleroma, :frontends, primary: %{ "name" => "pleroma", "ref" => "stable" + }, + admin: %{ + "name" => "admin", + "ref" => "develop" } ``` diff --git a/docs/installation/freebsd_en.md b/docs/installation/freebsd_en.md new file mode 100644 index 000000000..130d68766 --- /dev/null +++ b/docs/installation/freebsd_en.md @@ -0,0 +1,210 @@ +# Installing on FreeBSD + +This document was written for FreeBSD 12.1, but should be work on future releases. + +## Required software + +This assumes the target system has `pkg(8)`. + +``` +# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh +``` + +Copy the rc.d scripts to the right directory: + +Setup the required services to automatically start at boot, using `sysrc(8)`. + +``` +# sysrc nginx_enable=YES +# sysrc postgresql_enable=YES +``` + +## Initialize postgres + +``` +# service postgresql initdb +# service postgresql start +``` + +## Configuring Pleroma + +Create a user for Pleroma: + +``` +# pw add user pleroma -m +# echo 'export LC_ALL="en_US.UTF-8"' >> /home/pleroma/.profile +# su -l pleroma +``` + +Clone the repository: + +``` +$ cd $HOME # Should be the same as /home/pleroma +$ git clone -b stable https://git.pleroma.social/pleroma/pleroma.git +``` + +Configure Pleroma. Note that you need a domain name at this point: + +``` +$ cd /home/pleroma/pleroma +$ mix deps.get # Enter "y" when asked to install Hex +$ mix pleroma.instance gen # You will be asked a few questions here. +$ cp config/generated_config.exs config/prod.secret.exs +``` + +Since Postgres is configured, we can now initialize the database. There should +now be a file in `config/setup_db.psql` that makes this easier. Edit it, and +*change the password* to a password of your choice. Make sure it is secure, since +it'll be protecting your database. As root, you can now initialize the database: + +``` +# cd /home/pleroma/pleroma +# sudo -Hu postgres -g postgres psql -f config/setup_db.psql +``` + +Postgres allows connections from all users without a password by default. To +fix this, edit `/var/db/postgres/data12/pg_hba.conf`. Change every `trust` to +`password`. + +Once this is done, restart Postgres with: +``` +# service postgresql restart +``` + +Run the database migrations. + +Back as the pleroma user, run the following to implement any database migrations. + +``` +# su -l pleroma +$ cd /home/pleroma/pleroma +$ MIX_ENV=prod mix ecto.migrate +``` + +You will need to do this whenever you update with `git pull`: + +## Configuring acme.sh + +We'll be using acme.sh in Stateless Mode for TLS certificate renewal. + +First, as root, allow the user `acme` to have access to the acme log file, as follows: + +``` +# touch /var/log/acme.sh.log +# chown acme:acme /var/log/acme.sh.log +# chmod 600 /var/log/acme.sh.log +``` + +Next, obtain your account fingerprint: + +``` +# sudo -Hu acme -g acme acme.sh --register-account +``` + +You need to add the following to your nginx configuration for the server +running on port 80: + +``` + location ~ ^/\.well-known/acme-challenge/([-_a-zA-Z0-9]+)$ { + default_type text/plain; + return 200 "$1.6fXAG9VyG0IahirPEU2ZerUtItW2DHzDzD9wZaEKpqd"; + } +``` + +Replace the string after after `$1.` with your fingerprint. + +Start nginx: + +``` +# service nginx start +``` + +It should now be possible to issue a cert (replace `example.com` +with your domain name): + +``` +# sudo -Hu acme -g acme acme.sh --issue -d example.com --stateless +``` + +Let's add auto-renewal to `/etc/crontab` +(replace `example.com` with your domain): + +``` +/usr/local/bin/sudo -Hu acme -g acme /usr/local/sbin/acme.sh -r -d example.com --stateless +``` + +### Configuring nginx + +FreeBSD's default nginx configuration does not contain an include directive, which is +typically used for multiple sites. Therefore, you will need to first create the required +directory as follows: + + +``` +# mkdir -p /usr/local/etc/nginx/sites-available +``` + +Next, add an `include` directive to `/usr/local/etc/nginx/nginx.conf`, within the `http {}` +block, as follows: + + +``` +http { +... + include /usr/local/etc/nginx/sites-available/*; +} +``` + +As root, copy `/home/pleroma/pleroma/installation/pleroma.nginx` to +`/usr/local/etc/nginx/sites-available/pleroma.nginx`. + +Edit the defaults of `/usr/local/etc/nginx/sites-available/pleroma.nginx`: + +* Change `ssl_trusted_certificate` to `/var/db/acme/certs/example.tld/example.tld.cer`. +* Change `ssl_certificate` to `/var/db/acme/certs/example.tld/fullchain.cer`. +* Change `ssl_certificate_key` to `/var/db/acme/certs/example.tld/example.tld.key`. +* Change all references of `example.tld` to your instance's domain name. + +## Creating a startup script for Pleroma + +Pleroma will need to compile when it initially starts, which typically takes a longer +period of time. Therefore, it is good practice to initially run pleroma from the +command-line before utilizing the rc.d script. That is done as follows: + +``` +# su -l pleroma +$ cd $HOME/pleroma +$ MIX_ENV=prod mix phx.server +``` + +Copy the startup script to the correct location and make sure it's executable: + +``` +# cp /home/pleroma/pleroma/installation/freebsd/rc.d/pleroma /usr/local/etc/rc.d/pleroma +# chmod +x /usr/local/etc/rc.d/pleroma +``` + +Update the `/etc/rc.conf` and start pleroma with the following commands: + +``` +# sysrc pleroma_enable=YES +# service pleroma start +``` + +#### Create your first user + +If your instance is up and running, you can create your first user with administrative rights with the following task: + +```shell +sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin +``` +## Conclusion + +Restart nginx with `# service nginx restart` and you should be up and running. + +Make sure your time is in sync, or other instances will receive your posts with +incorrect timestamps. You should have ntpd running. + +## Questions + +Questions about the installation or didn’t it work as it should be, ask in [#pleroma:matrix.org](https://matrix.heldscal.la/#/room/#freenode_#pleroma:matrix.org) or IRC Channel **#pleroma** on **Freenode**. |