From 5416b719526bc5f6aa773d79f80376c7b28e034c Mon Sep 17 00:00:00 2001 From: 0x46616c6b <0x46616c6b@users.noreply.github.com> Date: Wed, 18 Dec 2024 14:43:05 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Improve=20mkdocs=20(#698)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/development/coding_style.md | 4 +- docs/development/release.md | 10 +- docs/development/tests.md | 32 +++-- docs/installation/checkpassword.md | 29 +++-- docs/installation/code.md | 10 +- docs/installation/database.md | 8 +- docs/installation/finalize.md | 36 +++--- docs/installation/webserver.md | 200 +++++++++++++++-------------- docs/mail_crypt/legacy.md | 9 +- docs/update/index.md | 14 +- docs/wkd/index.md | 4 +- mkdocs.yml | 7 + 12 files changed, 204 insertions(+), 159 deletions(-) diff --git a/docs/development/coding_style.md b/docs/development/coding_style.md index c28607bf..16d6ec95 100644 --- a/docs/development/coding_style.md +++ b/docs/development/coding_style.md @@ -4,4 +4,6 @@ We use the default Symfony coding style. Check and adjust coding style by running `php-cs-fixer`: - make cs-fixer +```shell +make cs-fixer +``` diff --git a/docs/development/release.md b/docs/development/release.md index 7e6ffa34..4d7ac522 100644 --- a/docs/development/release.md +++ b/docs/development/release.md @@ -4,12 +4,16 @@ Release tarballs are the preferred way to install Userli. This page explains how First, you'll need a [Github API token](https://github.com/settings/tokens). -The token needs the following priviledges: +The token needs the following privileges: - public_repo, repo:status, repo_deployment +```text +public_repo, repo:status, repo_deployment +``` Now, execute the following script. It will create a version tag, release and copy the info from `CHANGELOG.md` to the release info. - $ GITHUB_API_TOKEN= GPG_SIGN_KEY="" ./bin/github-release.sh +```shell +GITHUB_API_TOKEN= GPG_SIGN_KEY="" ./bin/github-release.sh +``` diff --git a/docs/development/tests.md b/docs/development/tests.md index 585f4a10..2ba2275b 100644 --- a/docs/development/tests.md +++ b/docs/development/tests.md @@ -2,20 +2,24 @@ ## Linting, unit tests and functional tests - vagrant up && vagrant ssh - make test - make integration +```shell +vagrant up && vagrant ssh +make test +make integration +``` ## Test checkpassword script - # Start vagrant box and login - vagrant up && vagrant ssh - # Create DB schema and load fixtures - bin/console doctrine:schema:create - bin/console doctrine:fixture:load - # Run `app:users:checkpassword` locally. First should return `0`, second `1` - echo -en 'user@example.org\0password' | ./bin/console app:users:checkpassword /bin/true; echo $? - echo -en 'user@example.org\0wrong' | ./bin/console app:users:checkpassword /bin/true; echo $? - # Logout from vagrant and test via IMAP login - exit - ./tests/test_checkpassword_login.sh +```shell +# Start vagrant box and login +vagrant up && vagrant ssh +# Create DB schema and load fixtures +bin/console doctrine:schema:create +bin/console doctrine:fixture:load +# Run `app:users:checkpassword` locally. First should return `0`, second `1` +echo -en 'user@example.org\0password' | ./bin/console app:users:checkpassword /bin/true; echo $? +echo -en 'user@example.org\0wrong' | ./bin/console app:users:checkpassword /bin/true; echo $? +# Logout from vagrant and test via IMAP login +exit +./tests/test_checkpassword_login.sh +``` diff --git a/docs/installation/checkpassword.md b/docs/installation/checkpassword.md index 4297f69b..242ad989 100644 --- a/docs/installation/checkpassword.md +++ b/docs/installation/checkpassword.md @@ -13,19 +13,22 @@ Example configuration for using checkpassword in Dovecot: `/etc/dovecot/conf.d/auth-checkpassword.conf.ext`: - passdb { - driver = checkpassword - args = /path/to/userli/bin/console app:users:checkpassword - } +```text +passdb { + driver = checkpassword + args = /path/to/userli/bin/console app:users:checkpassword +} - userdb { - driver = prefetch - } +userdb { + driver = prefetch +} + +userdb { + driver = checkpassword + args = /path/to/userli/bin/console app:users:checkpassword +} +``` - userdb { - driver = checkpassword - args = /path/to/userli/bin/console app:users:checkpassword - } ## Required permissions and sudo @@ -35,4 +38,6 @@ read access to the userli application. In order to grant the required permissions, add the Dovecot system user to the userli system group: - adduser dovecot userli +```shell +adduser dovecot userli +``` diff --git a/docs/installation/code.md b/docs/installation/code.md index 08301394..a13077ba 100644 --- a/docs/installation/code.md +++ b/docs/installation/code.md @@ -4,7 +4,9 @@ Install the [latest release](https://github.com/systemli/userli/releases/latest) Download and unpack the actual source code. - mkdir userli && cd userli - wget https://github.com/systemli/userli/releases/download/x.x.x/userli-x.x.x.tar.gz - # Check signature and hash sum, if you know how to - tar -xvzf userli-x.x.x.tar.gz +```shell +mkdir userli && cd userli +wget https://github.com/systemli/userli/releases/download/x.x.x/userli-x.x.x.tar.gz +# Check signature and hash sum, if you know how to +tar -xvzf userli-x.x.x.tar.gz +``` diff --git a/docs/installation/database.md b/docs/installation/database.md index 072ca533..04af718e 100644 --- a/docs/installation/database.md +++ b/docs/installation/database.md @@ -4,6 +4,8 @@ Create Userli database and database user. For simplicity, the user has full access to `userli` database. - mysql -e 'CREATE DATABASE userli' - mysql -e 'CREATE USER `userli`@`localhost` IDENTIFIED BY ""' - mysql -e 'GRANT ALL PRIVILEGES ON userli.* TO `userli`@`localhost`' +```shell +mysql -e 'CREATE DATABASE userli' +mysql -e 'CREATE USER `userli`@`localhost` IDENTIFIED BY ""' +mysql -e 'GRANT ALL PRIVILEGES ON userli.* TO `userli`@`localhost`' +``` diff --git a/docs/installation/finalize.md b/docs/installation/finalize.md index 514ffec5..0611deb4 100644 --- a/docs/installation/finalize.md +++ b/docs/installation/finalize.md @@ -4,21 +4,25 @@ Last steps to make Userli work properly. ## Create database scheme - # Create default database schema - bin/console doctrine:schema:create +```shell +# Create default database schema +bin/console doctrine:schema:create - # Load default reserved names into database - bin/console app:reservednames:import +# Load default reserved names into database +bin/console app:reservednames:import - # Warm up cache - bin/console cache:warmup +# Warm up cache +bin/console cache:warmup +``` ## Configure Dovecot Configure Dovecot to use separate directories per domain and user. Change the `mail_location` in `10-mail.conf` to something like this: - mail_location = maildir:~/%d/%n +```text +mail_location = maildir:~/%d/%n +``` ## Cronjobs @@ -27,14 +31,16 @@ have write permissions at Dovecot's maildir (usually this directory belongs to the system user `vmail`) you have to use a [script](https://github.com/systemli/ansible-role-userli/blob/master/templates/userli-maildirs-remove.sh.j2) to delete a maildir from a removed Userli account: - # Daily create lists of removed mail accounts - @daily userli cd /path/to/userli && bin/console app:users:remove --list --env=prod >/usr/local/share/userli/maildirs-remove.txt +```text +# Daily create lists of removed mail accounts +@daily userli cd /path/to/userli && bin/console app:users:remove --list --env=prod >/usr/local/share/userli/maildirs-remove.txt - # Daily delete maildirs of removed accounts - @daily /usr/local/bin/userli-maildirs-remove.sh +# Daily delete maildirs of removed accounts +@daily /usr/local/bin/userli-maildirs-remove.sh - # Daily unlink old redeemed vouchers - @daily userli cd /path/to/userli && bin/console app:voucher:unlink +# Daily unlink old redeemed vouchers +@daily userli cd /path/to/userli && bin/console app:voucher:unlink - # Send weekly report to admins - 12 13 * * 1 userli cd /path/to/userli && bin/console app:report:weekly +# Send weekly report to admins +12 13 * * 1 userli cd /path/to/userli && bin/console app:report:weekly +``` diff --git a/docs/installation/webserver.md b/docs/installation/webserver.md index 9f636760..591677fc 100644 --- a/docs/installation/webserver.md +++ b/docs/installation/webserver.md @@ -7,109 +7,115 @@ Don't blindly copy them, but adjust them to your needs. ## Caddy - :8080 - gzip - root /var/www/userli/public - # PHP-FPM Configuration - fastcgi / /run/php/php8.0-fpm.sock php - rewrite { - to {path} /index.php?{query} - } +```text +:8080 +gzip +root /var/www/userli/public +# PHP-FPM Configuration +fastcgi / /run/php/php8.0-fpm.sock php +rewrite { + to {path} /index.php?{query} +} +``` ## Nginx - server { - listen 80; - - root /vagrant/public; - index index.php; - - location / { - try_files $uri /index.php$is_args$args; - } - - error_page 404 /404.html; - - error_page 500 502 503 504 /50x.html; - location = /50x.html { - root /usr/share/nginx/www; - } - - location ~ ^/index\.php(/|$) { - fastcgi_split_path_info ^(.+\.php)(/.*)$; - fastcgi_pass unix:/var/run/php/php8.0-fpm.sock; - include fastcgi_params; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - fastcgi_param HTTPS off; - } +```text +server { + listen 80; + + root /vagrant/public; + index index.php; + + location / { + try_files $uri /index.php$is_args$args; + } + + error_page 404 /404.html; + + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/www; + } + + location ~ ^/index\.php(/|$) { + fastcgi_split_path_info ^(.+\.php)(/.*)$; + fastcgi_pass unix:/var/run/php/php8.0-fpm.sock; + include fastcgi_params; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + fastcgi_param HTTPS off; } +} +``` ## Apache2 - - - ServerName users.example.org - ServerAdmin admin@example.org - RewriteEngine On - RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [NE,R,L] - - - - - - ServerName users.example.org - ServerAdmin admin@example.org - - DocumentRoot /var/www/users.example.org/www/public - +```text + + + ServerName users.example.org + ServerAdmin admin@example.org + RewriteEngine On + RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [NE,R,L] + + + + + + ServerName users.example.org + ServerAdmin admin@example.org + + DocumentRoot /var/www/users.example.org/www/public + + + AllowOverride AuthConfig FileInfo Indexes Limit Options=ExecCGI,Includes,Indexes,SymLinksIfOwnerMatch,MultiViews + Options -Indexes -MultiViews +SymLinksIfOwnerMatch + + LimitRequestBody 10485760 + + + + + Require all granted + + + SetEnv APP_ENV prod + + + SuexecUserGroup userli userli + + + + AddHandler fcgid-script .php + FCGIWrapper /var/www/users.example.org/php-fcgi/php-fcgi-starter .php + + IPCConnectTimeout 20 + IPCCommTimeout 60 + FcgidBusyTimeout 60 + MaxRequestLen 10485760 + - AllowOverride AuthConfig FileInfo Indexes Limit Options=ExecCGI,Includes,Indexes,SymLinksIfOwnerMatch,MultiViews - Options -Indexes -MultiViews +SymLinksIfOwnerMatch - - LimitRequestBody 10485760 - - - - - Require all granted + Options +ExecCGI - - SetEnv APP_ENV prod - - - SuexecUserGroup userli userli - - - - AddHandler fcgid-script .php - FCGIWrapper /var/www/users.example.org/php-fcgi/php-fcgi-starter .php - - IPCConnectTimeout 20 - IPCCommTimeout 60 - FcgidBusyTimeout 60 - MaxRequestLen 10485760 - - - Options +ExecCGI - - - - - Header add X-Content-Type-Options "nosniff" - Header add X-XSS-Protection "1; mode=block" - Header set Referrer-Policy "no-referrer" - Header add X-Frame-Options "SAMEORIGIN" - - ErrorLog "|/usr/bin/logger -t apache -p local0.error" - - Protocols h2 http/1.1 - - SSLEngine On - SSLCertificateFile /etc/letsencrypt/live/users.example.org/fullchain.pem - SSLCertificateKeyFile /etc/letsencrypt/live/users.example.org/privkey.pem - - - Header always set Strict-Transport-Security: "max-age=31536000;includeSubdomains" - - - + + + + Header add X-Content-Type-Options "nosniff" + Header add X-XSS-Protection "1; mode=block" + Header set Referrer-Policy "no-referrer" + Header add X-Frame-Options "SAMEORIGIN" + + ErrorLog "|/usr/bin/logger -t apache -p local0.error" + + Protocols h2 http/1.1 + + SSLEngine On + SSLCertificateFile /etc/letsencrypt/live/users.example.org/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/users.example.org/privkey.pem + + + Header always set Strict-Transport-Security: "max-age=31536000;includeSubdomains" + + + +``` diff --git a/docs/mail_crypt/legacy.md b/docs/mail_crypt/legacy.md index 423b58ec..4029eb16 100644 --- a/docs/mail_crypt/legacy.md +++ b/docs/mail_crypt/legacy.md @@ -8,7 +8,6 @@ partially unencrypted (the old) and partially encrypted (the new) mails. Therefore we decided to leave the exercise to enable MailCrypt for legacy users who got a MailCrypt key pair generated in the meantime to the system admins (e.g. by a cron script). - In order to enable MailCrypt for a legacy user, do the following: @@ -39,12 +38,16 @@ mail from legacy mailboxes that already have a MailCrypt key configured. This script needs to be invoked as a user who has write access to the mailbox in question - probably the best is to run it as root: - ./bin/mailcrypt-encrypt-maildir user@example.org +```shell +./bin/mailcrypt-encrypt-maildir user@example.org +``` The following SQL statement can be used to enable MailCrypt for all legacy users that got a MailCrypt key pair generated. Use with caution! - UPDATE virtual_users SET mail_crypt=1 WHERE mail_crypt_secret_box IS NOT NULL AND mail_crypt = 0; +```sql +UPDATE virtual_users SET mail_crypt=1 WHERE mail_crypt_secret_box IS NOT NULL AND mail_crypt = 0; +``` We might add a migration script to encrypt old mails from existing users at a later point. diff --git a/docs/update/index.md b/docs/update/index.md index f95a2afe..1b09af0f 100644 --- a/docs/update/index.md +++ b/docs/update/index.md @@ -5,11 +5,13 @@ to see whether manual steps are required. To automatically update the database schema of userli, run these commands: - # Warm up cache - bin/console cache:warmup +```shell +# Warm up cache +bin/console cache:warmup - # Show database schema updates - bin/console doctrine:schema:update --dump-sql +# Show database schema updates +bin/console doctrine:schema:update --dump-sql - # If necessary update the database schema - bin/console doctrine:schema:update --force +# If necessary update the database schema +bin/console doctrine:schema:update --force +``` diff --git a/docs/wkd/index.md b/docs/wkd/index.md index e7dcd1f4..208b61a2 100644 --- a/docs/wkd/index.md +++ b/docs/wkd/index.md @@ -20,4 +20,6 @@ for details. The WKD directory can be regenerated at any time by running the console command: - bin/console app:wkd:export-keys +```shell +bin/console app:wkd:export-keys +``` diff --git a/mkdocs.yml b/mkdocs.yml index 60279de3..cb196d52 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,6 +32,9 @@ nav: theme: name: material features: + - content.code.copy + - content.code.select + - content.code.annotate - navigation.tabs - navigation.tabs.sticky - navigation.sections @@ -51,3 +54,7 @@ extra: markdown_extensions: - admonition + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences