commit 5917123885c19a1044a8599a0891b40f79e0de18 · pyrox.dev/nixpkgs

+180

nixos/modules/services/networking/pleroma.md

···

       1
       +
       # Pleroma {#module-services-pleroma}

     

       2
       +
       

     

       3
       +
       [Pleroma](https://pleroma.social/) is a lightweight activity pub server.

     

       4
       +
       

     

       5
       +
       ## Generating the Pleroma config {#module-services-pleroma-generate-config}

     

       6
       +
       

     

       7
       +
       The `pleroma_ctl` CLI utility will prompt you some questions and it will generate an initial config file. This is an example of usage

     

       8
       +
       ```ShellSession

     

       9
       +
       $ mkdir tmp-pleroma

     

       10
       +
       $ cd tmp-pleroma

     

       11
       +
       $ nix-shell -p pleroma-otp

     

       12
       +
       $ pleroma_ctl instance gen --output config.exs --output-psql setup.psql

     

       13
       +
       ```

     

       14
       +
       

     

       15
       +
       The `config.exs` file can be further customized following the instructions on the [upstream documentation](https://docs-develop.pleroma.social/backend/configuration/cheatsheet/). Many refinements can be applied also after the service is running.

     

       16
       +
       

     

       17
       +
       ## Initializing the database {#module-services-pleroma-initialize-db}

     

       18
       +
       

     

       19
       +
       First, the Postgresql service must be enabled in the NixOS configuration

     

       20
       +
       ```

     

       21
       +
       services.postgresql = {

     

       22
       +
         enable = true;

     

       23
       +
         package = pkgs.postgresql_13;

     

       24
       +
       };

     

       25
       +
       ```

     

       26
       +
       and activated with the usual

     

       27
       +
       ```ShellSession

     

       28
       +
       $ nixos-rebuild switch

     

       29
       +
       ```

     

       30
       +
       

     

       31
       +
       Then you can create and seed the database, using the `setup.psql` file that you generated in the previous section, by running

     

       32
       +
       ```ShellSession

     

       33
       +
       $ sudo -u postgres psql -f setup.psql

     

       34
       +
       ```

     

       35
       +
       

     

       36
       +
       ## Enabling the Pleroma service locally {#module-services-pleroma-enable}

     

       37
       +
       

     

       38
       +
       In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.

     

       39
       +
       

     

       40
       +
       This is an example of configuration, where [](#opt-services.pleroma.configs) option contains the content of the file `config.exs`, generated [in the first section](#module-services-pleroma-generate-config), but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is important, because otherwise they will be stored publicly in the Nix store.

     

       41
       +
       ```

     

       42
       +
       services.pleroma = {

     

       43
       +
         enable = true;

     

       44
       +
         secretConfigFile = "/var/lib/pleroma/secrets.exs";

     

       45
       +
         configs = [

     

       46
       +
           ''

     

       47
       +
           import Config

     

       48
       +
       

     

       49
       +
           config :pleroma, Pleroma.Web.Endpoint,

     

       50
       +
             url: [host: "pleroma.example.net", scheme: "https", port: 443],

     

       51
       +
             http: [ip: {127, 0, 0, 1}, port: 4000]

     

       52
       +
       

     

       53
       +
           config :pleroma, :instance,

     

       54
       +
             name: "Test",

     

       55
       +
             email: "admin@example.net",

     

       56
       +
             notify_email: "admin@example.net",

     

       57
       +
             limit: 5000,

     

       58
       +
             registrations_open: true

     

       59
       +
       

     

       60
       +
           config :pleroma, :media_proxy,

     

       61
       +
             enabled: false,

     

       62
       +
             redirect_on_failure: true

     

       63
       +
       

     

       64
       +
           config :pleroma, Pleroma.Repo,

     

       65
       +
             adapter: Ecto.Adapters.Postgres,

     

       66
       +
             username: "pleroma",

     

       67
       +
             database: "pleroma",

     

       68
       +
             hostname: "localhost"

     

       69
       +
       

     

       70
       +
           # Configure web push notifications

     

       71
       +
           config :web_push_encryption, :vapid_details,

     

       72
       +
             subject: "mailto:admin@example.net"

     

       73
       +
       

     

       74
       +
           # ... TO CONTINUE ...

     

       75
       +
           ''

     

       76
       +
         ];

     

       77
       +
       };

     

       78
       +
       ```

     

       79
       +
       

     

       80
       +
       Secrets must be moved into a file pointed by [](#opt-services.pleroma.secretConfigFile), in our case `/var/lib/pleroma/secrets.exs`. This file can be created copying the previously generated `config.exs` file and then removing all the settings, except the secrets. This is an example

     

       81
       +
       ```

     

       82
       +
       # Pleroma instance passwords

     

       83
       +
       

     

       84
       +
       import Config

     

       85
       +
       

     

       86
       +
       config :pleroma, Pleroma.Web.Endpoint,

     

       87
       +
          secret_key_base: "<the secret generated by pleroma_ctl>",

     

       88
       +
          signing_salt: "<the secret generated by pleroma_ctl>"

     

       89
       +
       

     

       90
       +
       config :pleroma, Pleroma.Repo,

     

       91
       +
         password: "<the secret generated by pleroma_ctl>"

     

       92
       +
       

     

       93
       +
       # Configure web push notifications

     

       94
       +
       config :web_push_encryption, :vapid_details,

     

       95
       +
         public_key: "<the secret generated by pleroma_ctl>",

     

       96
       +
         private_key: "<the secret generated by pleroma_ctl>"

     

       97
       +
       

     

       98
       +
       # ... TO CONTINUE ...

     

       99
       +
       ```

     

       100
       +
       Note that the lines of the same configuration group are comma separated (i.e. all the lines end with a comma, except the last one), so when the lines with passwords are added or removed, commas must be adjusted accordingly.

     

       101
       +
       

     

       102
       +
       The service can be enabled with the usual

     

       103
       +
       ```ShellSession

     

       104
       +
       $ nixos-rebuild switch

     

       105
       +
       ```

     

       106
       +
       

     

       107
       +
       The service is accessible only from the local `127.0.0.1:4000` port. It can be tested using a port forwarding like this

     

       108
       +
       ```ShellSession

     

       109
       +
       $ ssh -L 4000:localhost:4000 myuser@example.net

     

       110
       +
       ```

     

       111
       +
       and then accessing <http://localhost:4000> from a web browser.

     

       112
       +
       

     

       113
       +
       ## Creating the admin user {#module-services-pleroma-admin-user}

     

       114
       +
       

     

       115
       +
       After Pleroma service is running, all [Pleroma administration utilities](https://docs-develop.pleroma.social/) can be used. In particular an admin user can be created with

     

       116
       +
       ```ShellSession

     

       117
       +
       $ pleroma_ctl user new <nickname> <email>  --admin --moderator --password <password>

     

       118
       +
       ```

     

       119
       +
       

     

       120
       +
       ## Configuring Nginx {#module-services-pleroma-nginx}

     

       121
       +
       

     

       122
       +
       In this configuration, Pleroma is listening only on the local port 4000. Nginx can be configured as a Reverse Proxy, for forwarding requests from public ports to the Pleroma service. This is an example of configuration, using

     

       123
       +
       [Let's Encrypt](https://letsencrypt.org/) for the TLS certificates

     

       124
       +
       ```

     

       125
       +
       security.acme = {

     

       126
       +
         email = "root@example.net";

     

       127
       +
         acceptTerms = true;

     

       128
       +
       };

     

       129
       +
       

     

       130
       +
       services.nginx = {

     

       131
       +
         enable = true;

     

       132
       +
         addSSL = true;

     

       133
       +
       

     

       134
       +
         recommendedTlsSettings = true;

     

       135
       +
         recommendedOptimisation = true;

     

       136
       +
         recommendedGzipSettings = true;

     

       137
       +
       

     

       138
       +
         recommendedProxySettings = false;

     

       139
       +
         # NOTE: if enabled, the NixOS proxy optimizations will override the Pleroma

     

       140
       +
         # specific settings, and they will enter in conflict.

     

       141
       +
       

     

       142
       +
         virtualHosts = {

     

       143
       +
           "pleroma.example.net" = {

     

       144
       +
             http2 = true;

     

       145
       +
             enableACME = true;

     

       146
       +
             forceSSL = true;

     

       147
       +
       

     

       148
       +
             locations."/" = {

     

       149
       +
               proxyPass = "http://127.0.0.1:4000";

     

       150
       +
       

     

       151
       +
               extraConfig = ''

     

       152
       +
                 etag on;

     

       153
       +
                 gzip on;

     

       154
       +
       

     

       155
       +
                 add_header 'Access-Control-Allow-Origin' '*' always;

     

       156
       +
                 add_header 'Access-Control-Allow-Methods' 'POST, PUT, DELETE, GET, PATCH, OPTIONS' always;

     

       157
       +
                 add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Idempotency-Key' always;

     

       158
       +
                 add_header 'Access-Control-Expose-Headers' 'Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id' always;

     

       159
       +
                 if ($request_method = OPTIONS) {

     

       160
       +
                   return 204;

     

       161
       +
                 }

     

       162
       +
                 add_header X-XSS-Protection "1; mode=block";

     

       163
       +
                 add_header X-Permitted-Cross-Domain-Policies none;

     

       164
       +
                 add_header X-Frame-Options DENY;

     

       165
       +
                 add_header X-Content-Type-Options nosniff;

     

       166
       +
                 add_header Referrer-Policy same-origin;

     

       167
       +
                 add_header X-Download-Options noopen;

     

       168
       +
                 proxy_http_version 1.1;

     

       169
       +
                 proxy_set_header Upgrade $http_upgrade;

     

       170
       +
                 proxy_set_header Connection "upgrade";

     

       171
       +
                 proxy_set_header Host $host;

     

       172
       +
       

     

       173
       +
                 client_max_body_size 16m;

     

       174
       +
                 # NOTE: increase if users need to upload very big files

     

       175
       +
               '';

     

       176
       +
             };

     

       177
       +
           };

     

       178
       +
         };

     

       179
       +
       };

     

       180
       +
       ```

nixos/modules/services/networking/pleroma.nix

···

       147
        
       

     

       148
        
         };

     

       149
        
         meta.maintainers = with lib.maintainers; [ ninjatrappeur ];

     

       0
        
       
     

       0
        
       
     

       150
        
         meta.doc = ./pleroma.xml;

     

       151
        
       }

···

       147
        
       

     

       148
        
         };

     

       149
        
         meta.maintainers = with lib.maintainers; [ ninjatrappeur ];

     

       150
       +
         # Don't edit the docbook xml directly, edit the md and generate it:

     

       151
       +
         # `pandoc pleroma.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > pleroma.xml`

     

       152
        
         meta.doc = ./pleroma.xml;

     

       153
        
       }

+140 -85

nixos/modules/services/networking/pleroma.xml

···

       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
                version="5.0"

     

       5
       -
                xml:id="module-services-pleroma">

     

       6
       -
        <title>Pleroma</title>

     

       7
       -
        <para>

     

       8
       -
         <link xlink:href="https://pleroma.social/">Pleroma</link> is a lightweight activity pub server.</para>

     

       9
       -
        <section xml:id="module-services-pleroma-generate-config">

     

       10
       -
         <title>Generating the Pleroma config</title>

     

       11
       -
         <para>The <literal>pleroma_ctl</literal> CLI utility will prompt you some questions and it will generate an initial config file. This is an example of usage

     

       12
       -
       <programlisting>

     

       13
       -
       <prompt>$ </prompt>mkdir tmp-pleroma

     

       14
       -
       <prompt>$ </prompt>cd tmp-pleroma

     

       15
       -
       <prompt>$ </prompt>nix-shell -p pleroma-otp

     

       16
       -
       <prompt>$ </prompt>pleroma_ctl instance gen --output config.exs --output-psql setup.psql

     

       0
        
       
     

       0
        
       
     

       17
        
       </programlisting>

     

       18
       -
         </para>

     

       19
       -
         <para>The <literal>config.exs</literal> file can be further customized following the instructions on the <link xlink:href="https://docs-develop.pleroma.social/backend/configuration/cheatsheet/">upstream documentation</link>. Many refinements can be applied also after the service is running.</para>

     

       20
       -
        </section>

     

       21
       -
        <section xml:id="module-services-pleroma-initialize-db">

     

       22
       -
         <title>Initializing the database</title>

     

       23
       -
         <para>First, the Postgresql service must be enabled in the NixOS configuration

     

       24
       -
       <programlisting>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       25
        
       services.postgresql = {

     

       26
        
         enable = true;

     

       27
        
         package = pkgs.postgresql_13;

     

       28
        
       };

     

       29
        
       </programlisting>

     

       30
       -
       and activated with the usual

     

       31
       -
       <programlisting>

     

       32
       -
       <prompt>$ </prompt>nixos-rebuild switch

     

       0
        
       
     

       0
        
       
     

       33
        
       </programlisting>

     

       34
       -
         </para>

     

       35
       -
         <para>Then you can create and seed the database, using the <literal>setup.psql</literal> file that you generated in the previous section, by running

     

       36
       -
       <programlisting>

     

       37
       -
       <prompt>$ </prompt>sudo -u postgres psql -f setup.psql

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       38
        
       </programlisting>

     

       39
       -
         </para>

     

       40
       -
        </section>

     

       41
       -
        <section xml:id="module-services-pleroma-enable">

     

       42
       -
         <title>Enabling the Pleroma service locally</title>

     

       43
       -
         <para>In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.</para>

     

       44
       -
         <para>This is an example of configuration, where <link linkend="opt-services.pleroma.configs">services.pleroma.configs</link> option contains the content of the file <literal>config.exs</literal>, generated <link linkend="module-services-pleroma-generate-config">in the first section</link>, but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is important, because otherwise they will be stored publicly in the Nix store.

     

       45
       -
       <programlisting>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       46
        
       services.pleroma = {

     

       47
        
         enable = true;

     

       48
       -
         secretConfigFile = "/var/lib/pleroma/secrets.exs";

     

       49
        
         configs = [

     

       50
        
           ''

     

       51
        
           import Config

     

       52
        
       

     

       53
        
           config :pleroma, Pleroma.Web.Endpoint,

     

       54
       -
             url: [host: "pleroma.example.net", scheme: "https", port: 443],

     

       55
        
             http: [ip: {127, 0, 0, 1}, port: 4000]

     

       56
        
       

     

       57
        
           config :pleroma, :instance,

     

       58
       -
             name: "Test",

     

       59
       -
             email: "admin@example.net",

     

       60
       -
             notify_email: "admin@example.net",

     

       61
        
             limit: 5000,

     

       62
        
             registrations_open: true

     

       63
        
       

     
···

       67
        
       

     

       68
        
           config :pleroma, Pleroma.Repo,

     

       69
        
             adapter: Ecto.Adapters.Postgres,

     

       70
       -
             username: "pleroma",

     

       71
       -
             database: "pleroma",

     

       72
       -
             hostname: "localhost"

     

       73
        
       

     

       74
        
           # Configure web push notifications

     

       75
        
           config :web_push_encryption, :vapid_details,

     

       76
       -
             subject: "mailto:admin@example.net"

     

       77
        
       

     

       78
        
           # ... TO CONTINUE ...

     

       79
        
           ''

     

       80
        
         ];

     

       81
        
       };

     

       82
        
       </programlisting>

     

       83
       -
         </para>

     

       84
       -
         <para>Secrets must be moved into a file pointed by <link linkend="opt-services.pleroma.secretConfigFile">services.pleroma.secretConfigFile</link>, in our case <literal>/var/lib/pleroma/secrets.exs</literal>. This file can be created copying the previously generated <literal>config.exs</literal> file and then removing all the settings, except the secrets. This is an example

     

       85
       -
       <programlisting>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       86
        
       # Pleroma instance passwords

     

       87
        
       

     

       88
        
       import Config

     

       89
        
       

     

       90
        
       config :pleroma, Pleroma.Web.Endpoint,

     

       91
       -
          secret_key_base: "&lt;the secret generated by pleroma_ctl&gt;",

     

       92
       -
          signing_salt: "&lt;the secret generated by pleroma_ctl&gt;"

     

       93
        
       

     

       94
        
       config :pleroma, Pleroma.Repo,

     

       95
       -
         password: "&lt;the secret generated by pleroma_ctl&gt;"

     

       96
        
       

     

       97
        
       # Configure web push notifications

     

       98
        
       config :web_push_encryption, :vapid_details,

     

       99
       -
         public_key: "&lt;the secret generated by pleroma_ctl&gt;",

     

       100
       -
         private_key: "&lt;the secret generated by pleroma_ctl&gt;"

     

       101
        
       

     

       102
        
       # ... TO CONTINUE ...

     

       103
        
       </programlisting>

     

       104
       -
         Note that the lines of the same configuration group are comma separated (i.e. all the lines end with a comma, except the last one), so when the lines with passwords are added or removed, commas must be adjusted accordingly.</para>

     

       105
       -
       

     

       106
       -
         <para>The service can be enabled with the usual

     

       107
       -
       <programlisting>

     

       108
       -
       <prompt>$ </prompt>nixos-rebuild switch

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       109
        
       </programlisting>

     

       110
       -
         </para>

     

       111
       -
         <para>The service is accessible only from the local <literal>127.0.0.1:4000</literal> port. It can be tested using a port forwarding like this

     

       112
       -
       <programlisting>

     

       113
       -
       <prompt>$ </prompt>ssh -L 4000:localhost:4000 myuser@example.net

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       114
        
       </programlisting>

     

       115
       -
       and then accessing <link xlink:href="http://localhost:4000">http://localhost:4000</link> from a web browser.</para>

     

       116
       -
        </section>

     

       117
       -
        <section xml:id="module-services-pleroma-admin-user">

     

       118
       -
         <title>Creating the admin user</title>

     

       119
       -
         <para>After Pleroma service is running, all <link xlink:href="https://docs-develop.pleroma.social/">Pleroma administration utilities</link> can be used. In particular an admin user can be created with

     

       120
       -
       <programlisting>

     

       121
       -
       <prompt>$ </prompt>pleroma_ctl user new &lt;nickname&gt; &lt;email&gt;  --admin --moderator --password &lt;password&gt;

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       122
        
       </programlisting>

     

       123
       -
         </para>

     

       124
       -
        </section>

     

       125
       -
        <section xml:id="module-services-pleroma-nginx">

     

       126
       -
         <title>Configuring Nginx</title>

     

       127
       -
         <para>In this configuration, Pleroma is listening only on the local port 4000. Nginx can be configured as a Reverse Proxy, for forwarding requests from public ports to the Pleroma service. This is an example of configuration, using

     

       128
       -
       <link xlink:href="https://letsencrypt.org/">Let's Encrypt</link> for the TLS certificates

     

       129
       -
       <programlisting>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       130
        
       security.acme = {

     

       131
       -
         email = "root@example.net";

     

       132
        
         acceptTerms = true;

     

       133
        
       };

     

       134
        
       

     
···

       145
        
         # specific settings, and they will enter in conflict.

     

       146
        
       

     

       147
        
         virtualHosts = {

     

       148
       -
           "pleroma.example.net" = {

     

       149
        
             http2 = true;

     

       150
        
             enableACME = true;

     

       151
        
             forceSSL = true;

     

       152
        
       

     

       153
       -
             locations."/" = {

     

       154
       -
               proxyPass = "http://127.0.0.1:4000";

     

       155
        
       

     

       156
        
               extraConfig = ''

     

       157
        
                 etag on;

     
···

       164
        
                 if ($request_method = OPTIONS) {

     

       165
        
                   return 204;

     

       166
        
                 }

     

       167
       -
                 add_header X-XSS-Protection "1; mode=block";

     

       168
        
                 add_header X-Permitted-Cross-Domain-Policies none;

     

       169
        
                 add_header X-Frame-Options DENY;

     

       170
        
                 add_header X-Content-Type-Options nosniff;

     
···

       172
        
                 add_header X-Download-Options noopen;

     

       173
        
                 proxy_http_version 1.1;

     

       174
        
                 proxy_set_header Upgrade $http_upgrade;

     

       175
       -
                 proxy_set_header Connection "upgrade";

     

       176
        
                 proxy_set_header Host $host;

     

       177
        
       

     

       178
        
                 client_max_body_size 16m;

     
···

       183
        
         };

     

       184
        
       };

     

       185
        
       </programlisting>

     

       186
       -
         </para>

     

       187
       -
        </section>

     

       188
        
       </chapter>

···

       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pleroma">

     

       2
       +
         <title>Pleroma</title>

     

       3
       +
         <para>

     

       4
       +
           <link xlink:href="https://pleroma.social/">Pleroma</link> is a

     

       5
       +
           lightweight activity pub server.

     

       6
       +
         </para>

     

       7
       +
         <section xml:id="module-services-pleroma-generate-config">

     

       8
       +
           <title>Generating the Pleroma config</title>

     

       9
       +
           <para>

     

       10
       +
             The <literal>pleroma_ctl</literal> CLI utility will prompt you

     

       11
       +
             some questions and it will generate an initial config file. This

     

       12
       +
             is an example of usage

     

       13
       +
           </para>

     

       14
       +
           <programlisting>

     

       15
       +
       $ mkdir tmp-pleroma

     

       16
       +
       $ cd tmp-pleroma

     

       17
       +
       $ nix-shell -p pleroma-otp

     

       18
       +
       $ pleroma_ctl instance gen --output config.exs --output-psql setup.psql

     

       19
        
       </programlisting>

     

       20
       +
           <para>

     

       21
       +
             The <literal>config.exs</literal> file can be further customized

     

       22
       +
             following the instructions on the

     

       23
       +
             <link xlink:href="https://docs-develop.pleroma.social/backend/configuration/cheatsheet/">upstream

     

       24
       +
             documentation</link>. Many refinements can be applied also after

     

       25
       +
             the service is running.

     

       26
       +
           </para>

     

       27
       +
         </section>

     

       28
       +
         <section xml:id="module-services-pleroma-initialize-db">

     

       29
       +
           <title>Initializing the database</title>

     

       30
       +
           <para>

     

       31
       +
             First, the Postgresql service must be enabled in the NixOS

     

       32
       +
             configuration

     

       33
       +
           </para>

     

       34
       +
           <programlisting>

     

       35
        
       services.postgresql = {

     

       36
        
         enable = true;

     

       37
        
         package = pkgs.postgresql_13;

     

       38
        
       };

     

       39
        
       </programlisting>

     

       40
       +
           <para>

     

       41
       +
             and activated with the usual

     

       42
       +
           </para>

     

       43
       +
           <programlisting>

     

       44
       +
       $ nixos-rebuild switch

     

       45
        
       </programlisting>

     

       46
       +
           <para>

     

       47
       +
             Then you can create and seed the database, using the

     

       48
       +
             <literal>setup.psql</literal> file that you generated in the

     

       49
       +
             previous section, by running

     

       50
       +
           </para>

     

       51
       +
           <programlisting>

     

       52
       +
       $ sudo -u postgres psql -f setup.psql

     

       53
        
       </programlisting>

     

       54
       +
         </section>

     

       55
       +
         <section xml:id="module-services-pleroma-enable">

     

       56
       +
           <title>Enabling the Pleroma service locally</title>

     

       57
       +
           <para>

     

       58
       +
             In this section we will enable the Pleroma service only locally,

     

       59
       +
             so its configurations can be improved incrementally.

     

       60
       +
           </para>

     

       61
       +
           <para>

     

       62
       +
             This is an example of configuration, where

     

       63
       +
             <xref linkend="opt-services.pleroma.configs"></xref> option

     

       64
       +
             contains the content of the file <literal>config.exs</literal>,

     

       65
       +
             generated

     

       66
       +
             <link linkend="module-services-pleroma-generate-config">in the

     

       67
       +
             first section</link>, but with the secrets (database password,

     

       68
       +
             endpoint secret key, salts, etc.) removed. Removing secrets is

     

       69
       +
             important, because otherwise they will be stored publicly in the

     

       70
       +
             Nix store.

     

       71
       +
           </para>

     

       72
       +
           <programlisting>

     

       73
        
       services.pleroma = {

     

       74
        
         enable = true;

     

       75
       +
         secretConfigFile = &quot;/var/lib/pleroma/secrets.exs&quot;;

     

       76
        
         configs = [

     

       77
        
           ''

     

       78
        
           import Config

     

       79
        
       

     

       80
        
           config :pleroma, Pleroma.Web.Endpoint,

     

       81
       +
             url: [host: &quot;pleroma.example.net&quot;, scheme: &quot;https&quot;, port: 443],

     

       82
        
             http: [ip: {127, 0, 0, 1}, port: 4000]

     

       83
        
       

     

       84
        
           config :pleroma, :instance,

     

       85
       +
             name: &quot;Test&quot;,

     

       86
       +
             email: &quot;admin@example.net&quot;,

     

       87
       +
             notify_email: &quot;admin@example.net&quot;,

     

       88
        
             limit: 5000,

     

       89
        
             registrations_open: true

     

       90
        
       

     
···

       94
        
       

     

       95
        
           config :pleroma, Pleroma.Repo,

     

       96
        
             adapter: Ecto.Adapters.Postgres,

     

       97
       +
             username: &quot;pleroma&quot;,

     

       98
       +
             database: &quot;pleroma&quot;,

     

       99
       +
             hostname: &quot;localhost&quot;

     

       100
        
       

     

       101
        
           # Configure web push notifications

     

       102
        
           config :web_push_encryption, :vapid_details,

     

       103
       +
             subject: &quot;mailto:admin@example.net&quot;

     

       104
        
       

     

       105
        
           # ... TO CONTINUE ...

     

       106
        
           ''

     

       107
        
         ];

     

       108
        
       };

     

       109
        
       </programlisting>

     

       110
       +
           <para>

     

       111
       +
             Secrets must be moved into a file pointed by

     

       112
       +
             <xref linkend="opt-services.pleroma.secretConfigFile"></xref>, in

     

       113
       +
             our case <literal>/var/lib/pleroma/secrets.exs</literal>. This

     

       114
       +
             file can be created copying the previously generated

     

       115
       +
             <literal>config.exs</literal> file and then removing all the

     

       116
       +
             settings, except the secrets. This is an example

     

       117
       +
           </para>

     

       118
       +
           <programlisting>

     

       119
        
       # Pleroma instance passwords

     

       120
        
       

     

       121
        
       import Config

     

       122
        
       

     

       123
        
       config :pleroma, Pleroma.Web.Endpoint,

     

       124
       +
          secret_key_base: &quot;&lt;the secret generated by pleroma_ctl&gt;&quot;,

     

       125
       +
          signing_salt: &quot;&lt;the secret generated by pleroma_ctl&gt;&quot;

     

       126
        
       

     

       127
        
       config :pleroma, Pleroma.Repo,

     

       128
       +
         password: &quot;&lt;the secret generated by pleroma_ctl&gt;&quot;

     

       129
        
       

     

       130
        
       # Configure web push notifications

     

       131
        
       config :web_push_encryption, :vapid_details,

     

       132
       +
         public_key: &quot;&lt;the secret generated by pleroma_ctl&gt;&quot;,

     

       133
       +
         private_key: &quot;&lt;the secret generated by pleroma_ctl&gt;&quot;

     

       134
        
       

     

       135
        
       # ... TO CONTINUE ...

     

       136
        
       </programlisting>

     

       137
       +
           <para>

     

       138
       +
             Note that the lines of the same configuration group are comma

     

       139
       +
             separated (i.e. all the lines end with a comma, except the last

     

       140
       +
             one), so when the lines with passwords are added or removed,

     

       141
       +
             commas must be adjusted accordingly.

     

       142
       +
           </para>

     

       143
       +
           <para>

     

       144
       +
             The service can be enabled with the usual

     

       145
       +
           </para>

     

       146
       +
           <programlisting>

     

       147
       +
       $ nixos-rebuild switch

     

       148
        
       </programlisting>

     

       149
       +
           <para>

     

       150
       +
             The service is accessible only from the local

     

       151
       +
             <literal>127.0.0.1:4000</literal> port. It can be tested using a

     

       152
       +
             port forwarding like this

     

       153
       +
           </para>

     

       154
       +
           <programlisting>

     

       155
       +
       $ ssh -L 4000:localhost:4000 myuser@example.net

     

       156
        
       </programlisting>

     

       157
       +
           <para>

     

       158
       +
             and then accessing

     

       159
       +
             <link xlink:href="http://localhost:4000" role="uri">http://localhost:4000</link>

     

       160
       +
             from a web browser.

     

       161
       +
           </para>

     

       162
       +
         </section>

     

       163
       +
         <section xml:id="module-services-pleroma-admin-user">

     

       164
       +
           <title>Creating the admin user</title>

     

       165
       +
           <para>

     

       166
       +
             After Pleroma service is running, all

     

       167
       +
             <link xlink:href="https://docs-develop.pleroma.social/">Pleroma

     

       168
       +
             administration utilities</link> can be used. In particular an

     

       169
       +
             admin user can be created with

     

       170
       +
           </para>

     

       171
       +
           <programlisting>

     

       172
       +
       $ pleroma_ctl user new &lt;nickname&gt; &lt;email&gt;  --admin --moderator --password &lt;password&gt;

     

       173
        
       </programlisting>

     

       174
       +
         </section>

     

       175
       +
         <section xml:id="module-services-pleroma-nginx">

     

       176
       +
           <title>Configuring Nginx</title>

     

       177
       +
           <para>

     

       178
       +
             In this configuration, Pleroma is listening only on the local port

     

       179
       +
             4000. Nginx can be configured as a Reverse Proxy, for forwarding

     

       180
       +
             requests from public ports to the Pleroma service. This is an

     

       181
       +
             example of configuration, using

     

       182
       +
             <link xlink:href="https://letsencrypt.org/">Let's Encrypt</link>

     

       183
       +
             for the TLS certificates

     

       184
       +
           </para>

     

       185
       +
           <programlisting>

     

       186
        
       security.acme = {

     

       187
       +
         email = &quot;root@example.net&quot;;

     

       188
        
         acceptTerms = true;

     

       189
        
       };

     

       190
        
       

     
···

       201
        
         # specific settings, and they will enter in conflict.

     

       202
        
       

     

       203
        
         virtualHosts = {

     

       204
       +
           &quot;pleroma.example.net&quot; = {

     

       205
        
             http2 = true;

     

       206
        
             enableACME = true;

     

       207
        
             forceSSL = true;

     

       208
        
       

     

       209
       +
             locations.&quot;/&quot; = {

     

       210
       +
               proxyPass = &quot;http://127.0.0.1:4000&quot;;

     

       211
        
       

     

       212
        
               extraConfig = ''

     

       213
        
                 etag on;

     
···

       220
        
                 if ($request_method = OPTIONS) {

     

       221
        
                   return 204;

     

       222
        
                 }

     

       223
       +
                 add_header X-XSS-Protection &quot;1; mode=block&quot;;

     

       224
        
                 add_header X-Permitted-Cross-Domain-Policies none;

     

       225
        
                 add_header X-Frame-Options DENY;

     

       226
        
                 add_header X-Content-Type-Options nosniff;

     
···

       228
        
                 add_header X-Download-Options noopen;

     

       229
        
                 proxy_http_version 1.1;

     

       230
        
                 proxy_set_header Upgrade $http_upgrade;

     

       231
       +
                 proxy_set_header Connection &quot;upgrade&quot;;

     

       232
        
                 proxy_set_header Host $host;

     

       233
        
       

     

       234
        
                 client_max_body_size 16m;

     
···

       239
        
         };

     

       240
        
       };

     

       241
        
       </programlisting>

     

       242
       +
         </section>

     

       0
        
       
     

       243
        
       </chapter>