commit a3d011eebcee9f70463a68c28b2252073336ed54 · pyrox.dev/nixpkgs

+172 -116

nixos/modules/services/networking/pleroma.xml

···

       4
        
                version="5.0"

     

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

     

       6
        
        <title>Pleroma</title>

     

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

     

       8
       -
        <section xml:id="module-services-pleroma-getting-started">

     

       9
       -
          <title>Quick Start</title>

     

       10
       -
          <para>To get quickly started, you can use this sample NixOS configuration and adapt it to your use case.</para>

     

       11
       -
          <para><programlisting>

     

       12
       -
           {

     

       13
       -
             security.acme = {

     

       14
       -
               email = "root@tld";

     

       15
       -
               acceptTerms = true;

     

       16
       -
               certs = {

     

       17
       -
                 "social.tld.com" = {

     

       18
       -
                   webroot = "/var/www/social.tld.com";

     

       19
       -
                   email = "root@tld";

     

       20
       -
                   group = "nginx";

     

       21
       -
                 };

     

       22
       -
               };

     

       23
       -
             };

     

       24
       -
             services = {

     

       25
       -
               pleroma = {

     

       26
       -
                 enable = true;

     

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

     

       28
       -
                 configs = [

     

       29
       -
                 ''

     

       30
       -
                   import Config

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       31
        
       

     

       32
       -
                   config :pleroma, Pleroma.Web.Endpoint,

     

       33
       -
                   url: [host: "social.tld.com", scheme: "https", port: 443],

     

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

     

       35
        
       

     

       36
       -
                   config :pleroma, :instance,

     

       37
       -
                   name: "NixOS test pleroma server",

     

       38
       -
                   email: "pleroma@social.tld.com",

     

       39
       -
                   notify_email: "pleroma@social.tld.com",

     

       40
       -
                   limit: 5000,

     

       41
       -
                   registrations_open: true

     

       42
        
       

     

       43
       -
                   config :pleroma, :media_proxy,

     

       44
       -
                   enabled: false,

     

       45
       -
                   redirect_on_failure: true

     

       46
       -
                   #base_url: "https://cache.pleroma.social"

     

       47
        
       

     

       48
       -
                   config :pleroma, Pleroma.Repo,

     

       49
       -
                   adapter: Ecto.Adapters.Postgres,

     

       50
       -
                   username: "pleroma",

     

       51
       -
                   password: "${test-db-passwd}",

     

       52
       -
                   database: "pleroma",

     

       53
       -
                   hostname: "localhost",

     

       54
       -
                   pool_size: 10,

     

       55
       -
                   prepare: :named,

     

       56
       -
                   parameters: [

     

       57
       -
                       plan_cache_mode: "force_custom_plan"

     

       58
       -
                   ]

     

       59
        
       

     

       60
       -
                   config :pleroma, :database, rum_enabled: false

     

       61
       -
                   config :pleroma, :instance, static_dir: "/var/lib/pleroma/static"

     

       62
       -
                   config :pleroma, Pleroma.Uploaders.Local, uploads: "/var/lib/pleroma/uploads"

     

       63
       -
                   config :pleroma, configurable_from_database: false

     

       64
       -
                 ''

     

       65
       -
                 ];

     

       66
       -
               };

     

       67
       -
               postgresql = {

     

       68
       -
                 enable = true;

     

       69
       -
                 package = pkgs.postgresql_12;

     

       70
       -
               };

     

       71
       -
               nginx = {

     

       72
       -
                 enable = true;

     

       73
       -
                 addSSL = true;

     

       74
       -
                 sslCertificate = "/var/lib/acme/social.tld.com/fullchain.pem";

     

       75
       -
                 sslCertificateKey = "/var/lib/acme/social.tld.com/key.pem";

     

       76
       -
                 root = "/var/www/social.tld.com";

     

       77
       -
                 # ACME endpoint

     

       78
       -
                 locations."/.well-known/acme-challenge" = {

     

       79
       -
                     root = "/var/www/social.tld.com/";

     

       80
       -
                 };

     

       81
       -
                 virtualHosts."social.tld.com" = {

     

       82
       -
                   addSSL = true;

     

       83
       -
                   locations."/" = {

     

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

     

       85
       -
                     extraConfig = ''

     

       86
       -
                       add_header 'Access-Control-Allow-Origin' '*' always;

     

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

     

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

     

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

     

       90
       -
                       if ($request_method = OPTIONS) {

     

       91
       -
                           return 204;

     

       92
       -
                       }

     

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

     

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

     

       95
       -
                       add_header X-Frame-Options DENY;

     

       96
       -
                       add_header X-Content-Type-Options nosniff;

     

       97
       -
                       add_header Referrer-Policy same-origin;

     

       98
       -
                       add_header X-Download-Options noopen;

     

       99
       -
                       proxy_http_version 1.1;

     

       100
       -
                       proxy_set_header Upgrade $http_upgrade;

     

       101
       -
                       proxy_set_header Connection "upgrade";

     

       102
       -
                       proxy_set_header Host $host;

     

       103
       -
                       client_max_body_size 16m;

     

       104
       -
                     '';

     

       105
       -
                   };

     

       106
       -
                 };

     

       107
       -
               };

     

       108
       -
             };

     

       109
       -
           };

     

       110
       -
          </programlisting></para>

     

       111
       -
          <para>Note that you'll need to seed your database and upload your pleroma secrets to the path pointed by <literal>config.pleroma.secretConfigFile</literal>. You can find more informations about how to do that in the <link linkend="module-services-pleroma-generate-config">next</link> section.</para>

     

       112
       -
        </section>

     

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

     

       114
       -
          <title>Generating the Pleroma Config and Seed the Database</title>

     

       115
        
       

     

       116
       -
          <para>Before using this service, you'll need to generate your

     

       117
       -
       server configuration and its associated database seed. The

     

       118
       -
       <literal>pleroma_ctl</literal> CLI utility can help you with that. You

     

       119
       -
       can start with <literal>pleroma_ctl instance gen --output config.exs

     

       120
       -
       --output-psql setup.psql</literal>, this will prompt you some

     

       121
       -
       questions and will generate both your config file and database initial

     

       122
       -
       migration. </para>

     

       123
       -
       <para>For more details about this configuration format, please have a look at the <link xlink:href="https://docs-develop.pleroma.social/backend/configuration/cheatsheet/">upstream documentation</link>.</para>

     

       124
       -
       <para>To seed your database, you can use the <literal>setup.psql</literal> file you just generated by running

     

       125
        
       <programlisting>

     

       126
       -
           sudo -u postgres psql -f setup.psql

     

       127
       -
       </programlisting></para>

     

       128
       -
          <para>In regard of the pleroma service configuration you also just generated, you'll need to split it in two parts. The "public" part, which do not contain any secrets and thus can be safely stored in the Nix store and its "private" counterpart containing some secrets (database password, endpoint secret key, salts, etc.).</para>

     

       129
        
       

     

       130
       -
          <para>The public part will live in your NixOS machine configuration in the <link linkend="opt-services.pleroma.configs">services.pleroma.configs</link> option. However, it's up to you to upload the secret pleroma configuration to the path pointed by <link linkend="opt-services.pleroma.secretConfigFile">services.pleroma.secretConfigFile</link>. You can do that manually or rely on a third party tool such as <link xlink:href="https://github.com/DBCDK/morph">Morph</link> or <link xlink:href="https://github.com/NixOS/nixops">NixOps</link>.</para>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       131
        
        </section>

     

       132
        
       </chapter>

···

       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

     

       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>

     

       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

     

       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

     

       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>

     

       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
        
       

     

       64
       +
           config :pleroma, :media_proxy,

     

       65
       +
             enabled: false,

     

       66
       +
             redirect_on_failure: true

     

       0
        
       
     

       67
        
       

     

       68
       +
           config :pleroma, Pleroma.Repo,

     

       69
       +
             adapter: Ecto.Adapters.Postgres,

     

       70
       +
             username: "pleroma",

     

       71
       +
             database: "pleroma",

     

       72
       +
             hostname: "localhost"

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       73
        
       

     

       74
       +
           # Configure web push notifications

     

       75
       +
           config :web_push_encryption, :vapid_details,

     

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

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       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

     

       0
        
       
     

       0
        
       
     

       85
        
       <programlisting>

     

       86
       +
       # Pleroma instance passwords

     

       0
        
       
     

       0
        
       
     

       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

     

       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

     

       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;

     

       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>

     

       130
       +
       security.acme = {

     

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

     

       132
       +
         acceptTerms = true;

     

       133
       +
       };

     

       134
       +
       

     

       135
       +
       services.nginx = {

     

       136
       +
         enable = true;

     

       137
       +
         addSSL = true;

     

       138
       +
       

     

       139
       +
         recommendedTlsSettings = true;

     

       140
       +
         recommendedOptimisation = true;

     

       141
       +
         recommendedGzipSettings = true;

     

       142
       +
       

     

       143
       +
         recommendedProxySettings = false;

     

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

     

       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;

     

       158
       +
                 gzip on;

     

       159
       +
       

     

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

     

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

     

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

     

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

     

       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;

     

       171
       +
                 add_header Referrer-Policy same-origin;

     

       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;

     

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

     

       180
       +
               '';

     

       181
       +
             };

     

       182
       +
           };

     

       183
       +
         };

     

       184
       +
       };

     

       185
       +
       </programlisting>

     

       186
       +
         </para>

     

       187
        
        </section>

     

       188
        
       </chapter>