Order the menu items (#1250)

docs/01-user/README.md

@@ -1 +1,6 @@
-# User
+# User
+
+Thanks for using Mbin!
+
+Do you want to learn more?  
+See our [user guide](01-user_guide.md) and [FAQ](02-FAQ.md) pages.

docs/02-admin/01-installation/bare_metal.md → docs/02-admin/01-installation/01-bare_metal.md

@@ -62,7 +62,7 @@ sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=compose
 
 If you have a firewall installed (or you're behind a NAT), be sure to open port `443` for the web server. Mbin should run behind a reverse proxy like Nginx.
 
-For Nginx see: [Nginx configuration](../02-configuration/nginx.md).
+For Nginx see: [Nginx configuration](../02-configuration/02-nginx.md).
 
 ## Install NodeJS (frontend tools)
 
@@ -125,6 +125,10 @@ cd /var/www/mbin
 git clone https://github.com/MbinOrg/mbin.git .
 ```
 
+> [!TIP]
+> You might now want to switch to the latest stable release tag instead of using the `main` branch.
+> Try: `git checkout v1.7.3` (v1.7.3 might **not** be the latest version: [lookup the latest version](https://github.com/MbinOrg/mbin/releases))
+
 ### Create & configure media directory
 
 ```bash
@@ -177,7 +181,7 @@ nano .env.local
 Make sure you have substituted all the passwords and configured the basic services in `.env` file.
 
 > [!NOTE]
-> The snippet below are to variables inside the .env file. Using the keys generated in the section above "Generating Secrets" fill in the values. You should fully review this file to ensure everything is configured correctly.
+> The snippet below are to variables inside the `.env` file. Using the keys generated in the section above "Generating Secrets" fill in the values. You should fully review this file to ensure everything is configured correctly.
 
 ```ini
 REDIS_PASSWORD="{!SECRET!!KEY!-32_1-!}"
@@ -208,7 +212,7 @@ MAILER_DSN=smtp://username:[email protected]:587?encryption=tls&auth_mode=
 MAILER_DSN=smtp://username:[email protected]:465?encryption=ssl&auth_mode=log
 ```
 
-#### OAuth2 keys for API credential grants
+### OAuth2 keys for API credential grants
 
 1. Create an RSA key pair using OpenSSL:
 
@@ -235,6 +239,8 @@ OAUTH_PASSPHRASE=<Your (optional) passphrase from above here>
 OAUTH_ENCRYPTION_KEY=<Hex string generated in previous step>
 ```
 
+See also: [Mbin config files](../02-configuration/01-mbin_config_files.md) for more configuration options.
+
 ## Service Configuration
 
 ### PHP
@@ -328,14 +334,14 @@ composer clear-cache
 
 ### Caching
 
-You can choose between either Redis, Valkey or KeyDB.
+You can choose between either Valkey, KeyDB or Redis.
 
 > [!TIP]
-> More Redis/Valkey/KeyDB fine-tuning settings can be found in the [Redis configuration guide](../02-configuration/redis.md).
+> More Valkey/KeyDB/Redis fine-tuning settings can be found in the [Valkey / KeyDB / Redis configuration guide](../02-configuration/05-redis.md).
 
-#### Redis
+#### Valkey / KeyDB or Redis
 
-Edit `redis.conf` file:
+Edit `redis.conf` file (or the corresponding Valkey or KeyDB config file):
 
 ```bash
 sudo nano /etc/redis/redis.conf
@@ -430,7 +436,7 @@ php bin/console doctrine:migrations:migrate
 ```
 
 > [!IMPORTANT]
-> Check out the [PostgreSQL configuration page](../02-configuration/postgresql.md). You should not run the default PostgreSQL configuration in production!
+> Check out the [PostgreSQL configuration page](../02-configuration/04-postgresql.md). You should not run the default PostgreSQL configuration in production!
 
 ## Install RabbitMQ
 

docs/02-admin/01-installation/docker.md → docs/02-admin/01-installation/02-docker.md

@@ -1,7 +1,7 @@
 # Docker Installation
 
 > [!NOTE]
-> Docker installation is currently not advised for production use. Try the [Bare Metal installation](./bare_metal.md) instead.
+> Docker installation is currently not advised for production use. Try the [Bare Metal installation](01-bare_metal.md) instead.
 
 ## System Requirements
 

docs/02-admin/01-installation/README.md

@@ -1,9 +1,9 @@
 # Installation
 
-You can choose between:
+You can choose between server production installations:
 
-- [Bare metal/VM installation](./bare_metal.md)
+- [Bare metal/VM installation](01-bare_metal.md) (recommended)
 
 Or:
 
-- [Docker installation](./docker.md)
+- [Docker installation](02-docker.md)

docs/02-admin/02-configuration/README.md

@@ -5,7 +5,8 @@ Assuming you have already Mbin installed and followed the installation guide.
 
 Currently, the following configuration guides are provided:
 
-- [Mbin config](./mbin_config_files.md)
-- [Nginx](./nginx.md)
-- [Let's Encrypt](./lets_encrypt.md)
-- [Redis / KeyDB](./redis.md)
+- [Mbin config](./01-mbin_config_files.md)
+- [Nginx](./02-nginx.md)
+- [Let's Encrypt](./03-lets_encrypt.md)
+- [PostgreSQL](./04-postgresql.md)
+- [Valkey / KeyDB / Redis](./05-redis.md)

docs/02-admin/03-optional-features/sso.md → docs/02-admin/03-optional-features/02-sso.md

@@ -1,9 +1,10 @@
 # SSO (Single Sign On) Providers
 
-SSOs are used to simplify the registration flow. You authorize the server to use an existing account from one 
+SSOs are used to simplify the registration flow. You authorize the server to use an existing account from one
 of the available SSO providers.
 
 Mbin supports a multitude of SSO providers:
+
 - Google
 - Facebook
 - GitHub
@@ -16,18 +17,22 @@ Mbin supports a multitude of SSO providers:
 - Azure
 
 To enable an SSO provider you (usually) have to create a developer account on the specific platform, create an app
-and provide the app/client ID and a secret. These have to be entered in the correct environment variable 
-in the `.env`|`.env.local` file 
+and provide the app/client ID and a secret. These have to be entered in the correct environment variable
+in the `.env`|`.env.local` file
 
 ### Google
+
 https://developers.google.com/
+
 ```dotenv
 OAUTH_GOOGLE_ID=AS2easdioh912 # your client ID
 OAUTH_GOOGLE_SECRET=sdfpsajh329ura39ßseaoßjf30u # your client secret
 ```
 
 ### Facebook
+
 https://developers.facebook.com
+
 ```dotenv
 OAUTH_FACEBOOK_ID=AS2easdioh912 # your client ID
 OAUTH_FACEBOOK_SECRET=sdfpsajh329ura39ßseaoßjf30u # your client secret
@@ -45,13 +50,16 @@ You need a GitHub account, if you do no have one, yet, go and create one: https:
 6. Now you have the chance to upload an icon (at the bottom of the page)
 7. Click "Generate a new client secret"
 8. Insert the "Client ID" and the generated client secret into the `.env` file:
+
 ```dotenv
 OAUTH_GITHUB_ID=AS2easdioh912 # your client ID
 OAUTH_GITHUB_SECRET=sdfpsajh329ura39ßseaoßjf30u # your client secret
 ```
 
 ### Keycloak
+
 Self-hosted, https://www.keycloak.org/
+
 ```dotenv
 OAUTH_KEYCLOAK_ID=AS2easdioh912 # your client ID
 OAUTH_KEYCLOAK_SECRET=sdfpsajh329ura39ßseaoßjf30u # your client secret
@@ -61,7 +69,9 @@ OAUTH_KEYCLOAK_VERSION=
 ```
 
 ### Zitadel
+
 Self-hosted, https://zitadel.com/
+
 ```dotenv
 OAUTH_ZITADEL_ID=AS2easdioh912 # your client ID
 OAUTH_ZITADEL_SECRET=sdfpsajh329ura39ßseaoßjf30u # your client secret
@@ -77,12 +87,14 @@ You need a SimpleLogin account, if you do not have one, yet, go and create one:
 3. Choose an icon (if you want to)
 4. Click on "OAuth Settings" on the right
 5. Insert the client ID ("AppID / OAuth2 Client ID") and the client secret ("AppSecret / OAuth2 Client Secret")
-in your `.env` file
+   in your `.env` file
+
 ```dotenv
 OAUTH_SIMPLELOGIN_ID=gehirneimer.de-vycjfiaznc # your client ID
 OAUTH_SIMPLELOGIN_SECRET=fdiuasdfusdfsdfpsdagofweopf # your client secret
 ```
-6. Back in the browser, scroll down to "Authorized Redirect URIs" and click on "Add new uri" 
+
+6. Back in the browser, scroll down to "Authorized Redirect URIs" and click on "Add new uri"
 
 ### Discord
 
@@ -92,32 +104,40 @@ You need a Discord account, if you do not have one, yet, go and create one: http
 2. Click the "OAuth2" tab on the left
 3. Under "Client information" click "Reset Secret"
 4. The newly generated secret and the "Client ID" need to go in our `.env` file:
+
 ```dotenv
 OAUTH_DISCORD_ID=3245498543 # your client ID
 OAUTH_DISCORD_SECRET=xJHGApsadOPUIAsdoih # your client secret
 ```
+
 5. Back in the browser: click on "Add Redirect"
 6. enter the URL: `https://YOURINSTANCE/oauth/discord/verify`, replace `YOURINSTANCE` with your instance domain
 7. If you are on docker, restart the containers, on bare metal execute the `post-upgrade` script
 8. When you go to the login page you should see a button to "Continue with Discord"
 
 ### Authentik
+
 Self-hosted, https://goauthentik.io/
+
 ```dotenv
 OAUTH_AUTHENTIK_ID=3245498543 # your client ID
 OAUTH_AUTHENTIK_SECRET=xJHGApsadOPUIAsdoih # your client secret
 OAUTH_AUTHENTIK_BASE_URL=
 ```
 
 ### Privacy Portal
+
 https://privacyportal.org
+
 ```dotenv
 OAUTH_PRIVACYPORTAL_ID=3245498543 # your client ID
 OAUTH_PRIVACYPORTAL_SECRET=xJHGApsadOPUIAsdoih # your client secret
 ```
 
 ### Azure
+
 https://login.microsoftonline.com
+
 ```dotenv
 OAUTH_AZURE_ID=3245498543 # your client ID
 OAUTH_AZURE_SECRET=xJHGApsadOPUIAsdoih # your client secret

docs/02-admin/03-optional-features/image_metadata_cleaning.md → docs/02-admin/03-optional-features/04-image_metadata_cleaning.md

@@ -1,5 +1,7 @@
 # Image metadata cleaning with `exiftool`
 
+You could configure Mbin to remove meta-data from images.
+
 To use this feature, install `exiftool` (`libimage-exiftool-perl` package for Ubuntu/Debian)
 and make sure `exiftool` executable exist and and visible in PATH
 
@@ -16,7 +18,7 @@ EXIF_EXIFTOOL_PATH=
 EXIF_EXIFTOOL_TIMEOUT=10
 ```
 
-Available cleaning modes:
+Available cleaning modes are:
 
 - `none`: no metadata cleaning would be done.
 - `sanitize`: removes GPS and serial number metadata. this is the default for uploaded images.

docs/02-admin/03-optional-features/s3_storage.md → docs/02-admin/03-optional-features/05-s3_storage.md

@@ -4,23 +4,24 @@
 
 If you're starting a new instance, you can skip this part.
 
-To migrate to s3 storage we have to sync the media files located at `/var/www/mbin/public/media` into our s3 bucket.
+To migrate to S3 storage we have to sync the media files located at `/var/www/mbin/public/media` into our S3 bucket.
 We suggest running the sync once while your instance is still up and using the local storage for media, then shutting mbin down,
-configure it to use the s3 storage and do another sync to get all the files created during the initial sync.
+configure it to use the S3 storage and do another sync to get all the files created during the initial sync.
 
-To actually do the file sync you can use different tools, like `aws-cli`, `rclone` and others, 
-just search for it and you will find plenty tutorials on how to do that 
+To actually do the file sync you can use different tools, like `aws-cli`, `rclone` and others,
+just search for it and you will find plenty tutorials on how to do that
+
+## Configuring Mbin
 
-## Configuring mbin
 Edit your `.env` file:
 
 ```ini
 S3_KEY=$AWS_ACCESS_KEY_ID
 S3_SECRET=$AWS_SECRET_ACCESS_KEY
 S3_BUCKET=bucket-name
-# safe default for s3 deployments like minio or single zone ceph/radosgw
+# safe default for S3 deployments like minio or single zone ceph/radosgw
 S3_REGION=us-east-1
-# set if not using aws s3, note that the scheme is also required
+# set if not using aws S3, note that the scheme is also required
 S3_ENDPOINT=https://endpoint.domain.tld
 S3_VERSION=latest
 ```
@@ -51,16 +52,16 @@ oneup_flysystem:
 
 ## NGINX reverse proxy
 
-If you are using an object storage provider, we strongly advise you to use a media reverse proxy. 
-That way media URLs will not change and break links on remote instances when you decide to switch providers 
-and it hides your s3 endpoint from users of your instance.
+If you are using an object storage provider, we strongly advise you to use a media reverse proxy.
+That way media URLs will not change and break links on remote instances when you decide to switch providers
+and it hides your S3 endpoint from users of your instance.
 
-This replaces the media reverse proxy from [NGINX](../02-configuration/nginx.md).
+This replaces the media reverse proxy from [NGINX](../02-configuration/02-nginx.md).
 
 If you already had a reverse proxy for your media, then you only have to change the NGINX config,
-otherwise please follow the steps in our [media-reverse-proxy](../02-configuration/nginx.md) docs
+otherwise please follow the steps in our [media-reverse-proxy](../02-configuration/02-nginx.md) docs
 
-This config is heavily inspired by [mastodons nginx config](https://docs.joinmastodon.org/admin/optional/object-storage-proxy/)
+This config is heavily inspired by [Mastodons Nginx config](https://docs.joinmastodon.org/admin/optional/object-storage-proxy/).
 
 ```nginx
 proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=CACHE:10m inactive=7d max_size=10g;
@@ -114,7 +115,7 @@ server {
 }
 ```
 
-For it to be a usable https site you have to run certbot or supply your certificates manually.
+For it to be a usable HTTPS site you have to run `certbot` or supply your certificates manually.
 
 > [!TIP]
-> don't forget to enable http2 by adding `http2 on;` after certbot ran
+> Do not forget to enable http2 by adding `http2 on;` after certbot ran successfully.

docs/02-admin/03-optional-features/README.md

@@ -1 +1,11 @@
-# Optional Features
+# Optional Features
+
+There are several options features in Mbin, which you may want to configure.
+
+Like setting-up:
+
+- [Mercure](01-mercure.md) - Mercure is used to provide real-time data from the server towards the clients.
+- [Single sign-on (SSO)](02-sso.md) - SSO can be configured to allow registrations via other SSO providers.
+- [Captcha](03-captcha.md) - Captcha protection against spam and anti-bot.
+- [Image metadata cleaning](04-image_metadata_cleaning.md) - Clean-up and remove metadata from images using `exiftool`.
+- [S3 storage](05-s3_storage.md) - Configure an object storage service (S3) compatible bucket for storing images.

docs/02-admin/04-running-mbin/README.md

@@ -1 +1,8 @@
-# Running Mbin
+# Running Mbin
+
+When you're the server admin, you mind find the following pages useful:
+
+- [First setup](01-first_setup.md) - Helps creating your admin first account on Mbin and more...
+- [Back-up](02-backup.md) - How to back-up your databases?
+- [Upgrades](03-upgrades.md) - Where to think about when performing Mbin upgrades.
+- [Messenger jobs](04-messenger.md) - When running Symfony Messenger & RabbitMQ

docs/02-admin/FAQ.md

@@ -16,14 +16,14 @@ Have a look at our guides. A bare metal/VM setup is **recommended** at this time
 
 You can [join our Matrix community](https://matrix.to/#/#mbin:melroy.org) and ask for help, and/or make an [issue ticket](https://github.com/MbinOrg/mbin/issues) in GitHub if that adds value (always check for duplicates).
 
-See also our [contributing page](https://github.com/MbinOrg/mbin/blob/main/CONTRIBUTING.md).
+See also our [contributing page](../03-contributing/README.md).
 
 ## How can I contribute?
 
 New contributors are always _warmly welcomed_ to join us. The most valuable contributions come from helping with bug fixes and features through Pull Requests.
 As well as helping out with [translations](https://hosted.weblate.org/engage/mbin/) and documentation.
 
-Read more on our [contributing page](https://github.com/MbinOrg/mbin/blob/main/CONTRIBUTING.md).
+Read more on our [contributing page](../03-contributing/README.md).
 
 Do _not_ forget to [join our Matrix community](https://matrix.to/#/#mbin:melroy.org).
 
@@ -197,7 +197,7 @@ If you're seeing this error in logs:
 > getInstancePrivateKey(): Return value must be of type string, null returned
 
 At time of writing, `getInstancePrivateKey()` [calls out to the Redis cache](https://github.com/MbinOrg/mbin/blob/main/src/Service/ActivityPub/ApHttpClient.php#L348)
-first, so any updates to the keys requires a `DEL instance_private_key instance_public_key` (or `FLUSHDB` to be certain, as documented here: [bare metal](04-running-mbin/upgrades.md#clear-cache) and [docker](04-running-mbin/upgrades.md#clear-cache-1))
+first, so any updates to the keys requires a `DEL instance_private_key instance_public_key` (or `FLUSHDB` to be certain, as documented here: [bare metal](04-running-mbin/03-upgrades.md#clear-cache) and [docker](04-running-mbin/03-upgrades.md#clear-cache-1))
 
 ## RabbitMQ shows a really high publishing rate
 

docs/02-admin/README.md

@@ -2,7 +2,7 @@
 
 Welcome to the admin section of the Mbin documentation.
 
-You can install Mbin via
-- [bare metal](01-installation/bare_metal.md)
-- or [docker](01-installation/docker.md)
+You can install Mbin via:
 
+- [Bare metal](01-installation/01-bare_metal.md) (recommended for now)
+- or via [Docker](01-installation/02-docker.md)