From 05ad5ce8e08b4cc7d922cb24968fe01c53a2c182 Mon Sep 17 00:00:00 2001 From: Jonas Plum Date: Fri, 22 Aug 2025 17:56:38 +0200 Subject: [PATCH] Change docs (#441) * Change docs * hide backend config & small style change --------- Co-authored-by: Christian Beutel <> --- docs/astro.config.mjs | 40 +++++++++-------- docs/src/components/footer.astro | 2 +- docs/src/content/docs/{run => }/changelog.md | 0 .../content/docs/develop/local-development.md | 2 +- .../content/docs/run/backend-configuration.md | 43 ------------------- .../backup-server.md | 23 +++++++--- .../custom-categories.md | 18 ++++++++ .../docs/run/backend-configuration/index.md | 27 ++++++++++++ .../docs/run/backend-configuration/oauth2.md | 22 ++++++++++ .../docs/run/backend-configuration/smtp.md | 18 ++++++++ .../src/content/docs/run/custom-categories.md | 12 ------ docs/src/content/docs/run/installation.mdx | 4 +- docs/src/content/docs/use/authentication.md | 2 + docs/src/custom.css | 4 ++ web/src/lib/components/footer.svelte | 2 +- 15 files changed, 136 insertions(+), 83 deletions(-) rename docs/src/content/docs/{run => }/changelog.md (100%) delete mode 100644 docs/src/content/docs/run/backend-configuration.md rename docs/src/content/docs/run/{ => backend-configuration}/backup-server.md (57%) create mode 100644 docs/src/content/docs/run/backend-configuration/custom-categories.md create mode 100644 docs/src/content/docs/run/backend-configuration/index.md create mode 100644 docs/src/content/docs/run/backend-configuration/oauth2.md create mode 100644 docs/src/content/docs/run/backend-configuration/smtp.md delete mode 100644 docs/src/content/docs/run/custom-categories.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 7b254f60..b6256161 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -92,21 +92,18 @@ export default defineConfig({ }, { label: 'Backend configuration', - link: '/run/backend-configuration/' - }, - { - label: 'Custom categories', - link: '/run/custom-categories/' - }, - { - label: 'Backing up your server', - link: '/run/backup-server/' - }, - { - label: 'Changelog', - link: '/run/changelog/' - }] - }, { + collapsed: true, + items: [ + { label: 'Overview', link: '/run/backend-configuration/' }, + { label: 'SMTP', link: '/run/backend-configuration/smtp/' }, + { label: 'OAuth2', link: '/run/backend-configuration/oauth2/' }, + { label: 'Backing up your server', link: '/run/backend-configuration/backup-server/' }, + { label: 'Custom categories', link: '/run/backend-configuration/custom-categories/' }, + ] + } + ] + }, + { label: 'Develop wanderer', items: [ { @@ -123,12 +120,21 @@ export default defineConfig({ }, ] }, - ...openAPISidebarGroups,], + ...openAPISidebarGroups, + { + label: 'Changelog', + link: '/changelog/', + }], customCss: ['./src/custom.css', './src/tailwind.css', '@fontsource/ibm-plex-sans/400.css', '@fontsource/ibm-plex-sans/600.css', '@fontsource/ibm-plex-mono/400.css', '@fontsource/ibm-plex-mono/600.css'] }), svelte()], output: "server", vite: { plugins: [tailwindcss()] }, adapter: node({ mode: "standalone" - }) + }), + redirects: { + '/run/changelog/': '/changelog/', + '/run/backup-server/': '/run/backend-configuration/backup-server/', + '/run/custom-categories/': '/run/backend-configuration/custom-categories/', + }, }); \ No newline at end of file diff --git a/docs/src/components/footer.astro b/docs/src/components/footer.astro index 9408dcd6..f67a4c1f 100644 --- a/docs/src/components/footer.astro +++ b/docs/src/components/footer.astro @@ -144,7 +144,7 @@ const isNotHomepage = Astro.locals.starlightRoute.id !== ""; Features
  • - Changelog + Changelog
  • diff --git a/docs/src/content/docs/run/changelog.md b/docs/src/content/docs/changelog.md similarity index 100% rename from docs/src/content/docs/run/changelog.md rename to docs/src/content/docs/changelog.md diff --git a/docs/src/content/docs/develop/local-development.md b/docs/src/content/docs/develop/local-development.md index 7f5b47e7..247fa442 100644 --- a/docs/src/content/docs/develop/local-development.md +++ b/docs/src/content/docs/develop/local-development.md @@ -26,7 +26,7 @@ This will bring up a `meilisearch` instance on `http://127.0.0.1:7700`, a `Pocke ## PocketBase dashboard -It is highly advisable to create an admin user to access PocketBase's dashboard. To do so, please refer to the [backend configuration](/run/backend-configuration#setup) section of the documentation. +It is highly advisable to create an admin user to access PocketBase's dashboard. To do so, please refer to the [backend configuration](/run/backend-configuration/#setup) section of the documentation. ## Building diff --git a/docs/src/content/docs/run/backend-configuration.md b/docs/src/content/docs/run/backend-configuration.md deleted file mode 100644 index e90a7bb4..00000000 --- a/docs/src/content/docs/run/backend-configuration.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Backend configuration -description: How to access the PocketBase backend ---- -## Setup - -For many configuration options, it is necessary that you are able to access the PocketBase backend. PocketBase comes with a handy dashboard that allows you to configure basically everything in the backend. - -If you are using docker make sure to forward the internal port 8090 to a public port. With the default configuration, the PocketBase admin panel is available at `http://localhost:8090/_/`. If this is your first time visiting the panel you will need to create an admin account. -To create backend access navigate to the location of your `docker-compose.yaml` file on the server and type: -``` -docker compose exec -it db /pocketbase superuser upsert email@example.com myverysecurepassword -``` -Via the online dashboard, you will now have access with the user "email@example.com" and the password "myverysecurepassword" to all tables in the backend and can modify the underlying data directly. - -## Configure SMTP settings - -wanderer can send email notifications to users (e.g. when a user gains a new follower). This is also relevant to send password reset notifications. To enable sending email, you need to configure your SMPT settings in PocketBase. - -![Pocketbase Mail Settings](../../../assets/guides/pocketbase_mail_settings.png) - -In the pocketbase admin panel go to Settings -> Mail settings an enable "Use SMTP mail server". Enter the details of your SMTP server and send a test email to ensure your configuration is correct. On the same page you can also adjust the email template of the password reset email. - -Alternatively, you can set these options via the respective [environment variables](/run/environment-configuration/#pocketbase). - -## OAuth - -### Create an OAuth app - -This step will vary wildly from provider to provider. Please refer to your provider's documentation for the specific steps. - -No matter your provider, you will need a redirect URL. This redirect URL must have the following format: `$ORIGIN/login/redirect`. `$ORIGIN` refers to the `ORIGIN` environment variable that defines the public host at which your wanderer instance can be reached. So for the default installation, the redirect URL is `http://localhost:3000/login/redirect`. - -In any case, once you have successfully created your OAuth app you will receive a Client ID and a Client Secret. - -### Enable a provider in PocketBase -![Pocketbase OAuth](../../../assets/guides/pocketbase_oauth.png) - -In the PocketBase admin panel navigate to the `users` table. Click the gear icon at the top to open the table's settings and navigate to `Options`. In the tab `OAuth2`, add your provider and fill in the Client ID and Client Secret from the step before and save your changes. - -## More options - -To learn more about what you can do in the admin dashboard please refer to PocketBase's [documentation](https://pocketbase.io/docs/). \ No newline at end of file diff --git a/docs/src/content/docs/run/backup-server.md b/docs/src/content/docs/run/backend-configuration/backup-server.md similarity index 57% rename from docs/src/content/docs/run/backup-server.md rename to docs/src/content/docs/run/backend-configuration/backup-server.md index 2192e571..d353bea3 100644 --- a/docs/src/content/docs/run/backup-server.md +++ b/docs/src/content/docs/run/backend-configuration/backup-server.md @@ -3,29 +3,40 @@ title: Backing up your server description: How to backup data --- -wanderer has two components that persist data: meilisearch and PocketBase. However the data from meilisearch can be fully reconstructed from PocketBase. This happens automatically when you start wanderer. It is therefore only necessary to backup the data generated by PocketBase. +wanderer has two components that persist data: meilisearch and PocketBase. +However, the data from meilisearch can be fully reconstructed from PocketBase. +This happens automatically when you start wanderer. +It is therefore only necessary to back up the data generated by PocketBase. ## Backup via dashboard -![Pocketbase Backup](../../../assets/guides/pocketbase_backup.png) +![Pocketbase Backup](../../../../assets/guides/pocketbase_backup.png) + +Probably the most convenient method to back up your data is using the PocketBase admin dashbboard. -Probably the most convenient method to backup your data is using the PocketBase admin dashbboard. 1. Navigate to `Settings` -> `Backups` 2. Press the `Initialize new backup` button. 3. Give your backup a name and start it. That's it! -If you want to backup your data in regular intervals you can do so by enabling auto backups in the backup options. +If you want to back up your data in regular intervals you can do so by enabling auto backups in the backup options. ## Backup manually -Alternatively, if you require a more custom backup solution, you can simply backup the files directly on your server. All data is saved in folder called `pb_data`. If you installed wanderer via docker it is mounted as a volume. Check your `docker-compose.yml` file for its location. In there you typically find a `data.db` and `auxillary.db` file containing all table information of your instance. Furthermore, `pb_data` contains a `storage` folder holding all file upload data (e.g. GPX/image files). +Alternatively, if you require a more custom backup solution, you can simply backup the files directly on your server. +All data is saved in folder called `pb_data`. +If you installed wanderer via docker it is mounted as a volume. +Check your `docker-compose.yml` file for its location. +In there you typically find a `data.db` and `auxillary.db` file containing all table information of your instance. +Furthermore, `pb_data` contains a `storage` folder holding all file upload data (e.g. GPX/image files). You can simply copy these files to your backup location using your preferred file transfer method. ## Restore :::caution -**Important**: Restores are only supported when the **minor version** of your wanderer instance matches the minor version of the backup. For example, a backup created with version `0.17.x` can only be restored into another `0.17.x` installation. Restoring across major or minor versions is not guaranteed to work and may result in data loss or corruption. +**Important**: Restores are only supported when the **minor version** of your wanderer instance matches the minor version of the backup. +For example, a backup created with version `0.17.x` can only be restored into another `0.17.x` installation. +Restoring across major or minor versions is not guaranteed to work and may result in data loss or corruption. ::: ### Restore via dashboard diff --git a/docs/src/content/docs/run/backend-configuration/custom-categories.md b/docs/src/content/docs/run/backend-configuration/custom-categories.md new file mode 100644 index 00000000..f4da95fb --- /dev/null +++ b/docs/src/content/docs/run/backend-configuration/custom-categories.md @@ -0,0 +1,18 @@ +--- +title: Custom categories +description: How to create custom trail categories +--- + +wanderer uses categories to classify what kind of activity a trail belongs to. +Out of the box you get: Biking, Canoeing, Climbing, Hiking, Skiing and Walking. +However, you can adapt these categories to your needs or add completely new ones. + +## Modifying categories + +![Pocketbase Categories](../../../../assets/guides/pocketbase_categories.png) + +In the PocketBase admin panel, click on the `categories` table in the list on the left side. +All existing categories will be listed here. +To edit one simply click on the row, edit the data you want to change, and click "Save". +To delete a category check the box at the beginning of the row and click "Delete selected". +To create a new category click the "New record" button in the top right corner, give your new category a name and a background image, and click "Save". diff --git a/docs/src/content/docs/run/backend-configuration/index.md b/docs/src/content/docs/run/backend-configuration/index.md new file mode 100644 index 00000000..955d4249 --- /dev/null +++ b/docs/src/content/docs/run/backend-configuration/index.md @@ -0,0 +1,27 @@ +--- +title: Backend configuration +description: How to access the PocketBase backend +--- + +For many configuration options, it is necessary that you are able to access the PocketBase backend. +PocketBase comes with a handy dashboard that allows you to configure basically everything in the backend. + +If you are using docker make sure to forward the internal port 8090 to a public port. +With the default configuration, the PocketBase admin panel is available at `http://localhost:8090/_/`. +If this is your first time visiting the panel you will need to create an admin account. +To create backend access navigate to the location of your `docker-compose.yaml` file on the server and type: + +```sh +docker compose exec -it db /pocketbase superuser upsert email@example.com myverysecurepassword +``` + +Via the online dashboard, you will now have access with the user "email@example.com" and the password "myverysecurepassword" to all tables in the backend and can modify the underlying data directly. + +For specific configuration guides see: + +- [SMTP settings](./smtp/) +- [OAuth2 providers](./oauth2/) +- [Backup server](./backup-server/) +- [Custom categories](./custom-categories/) + +To learn more about what you can do in the admin dashboard please refer to PocketBase's [documentation](https://pocketbase.io/docs/). diff --git a/docs/src/content/docs/run/backend-configuration/oauth2.md b/docs/src/content/docs/run/backend-configuration/oauth2.md new file mode 100644 index 00000000..6ce17f44 --- /dev/null +++ b/docs/src/content/docs/run/backend-configuration/oauth2.md @@ -0,0 +1,22 @@ +--- +title: OAuth2 +description: Enable OAuth2 providers +redirectFrom: + - /run/backend-configuration/#oauth +--- + +### Create an OAuth app + +This step will vary wildly from provider to provider. Please refer to your provider's documentation for the specific steps. + +No matter your provider, you will need a redirect URL. This redirect URL must have the following format: `$ORIGIN/login/redirect`. +`$ORIGIN` refers to the `ORIGIN` environment variable that defines the public host at which your wanderer instance can be reached. +So for the default installation, the redirect URL is `http://localhost:3000/login/redirect`. + +In any case, once you have successfully created your OAuth app you will receive a Client ID and a Client Secret. + +### Enable a provider in PocketBase +![Pocketbase OAuth](../../../../assets/guides/pocketbase_oauth.png) + +In the PocketBase admin panel navigate to the `users` table. Click the gear icon at the top to open the table's settings and navigate to `Options`. +In the tab `OAuth2`, add your provider and fill in the Client ID and Client Secret from the step before and save your changes. diff --git a/docs/src/content/docs/run/backend-configuration/smtp.md b/docs/src/content/docs/run/backend-configuration/smtp.md new file mode 100644 index 00000000..e6b390e7 --- /dev/null +++ b/docs/src/content/docs/run/backend-configuration/smtp.md @@ -0,0 +1,18 @@ +--- +title: SMTP settings +description: Configure email notifications +redirectFrom: + - /run/backend-configuration/#configure-smtp-settings +--- + +wanderer can send email notifications to users (e.g. when a user gains a new follower). +This is also relevant to send password reset notifications. +To enable sending email, you need to configure your SMPT settings in PocketBase. + +![Pocketbase Mail Settings](../../../../assets/guides/pocketbase_mail_settings.png) + +In the pocketbase admin panel go to Settings -> Mail settings an enable "Use SMTP mail server". +Enter the details of your SMTP server and send a test email to ensure your configuration is correct. +On the same page you can also adjust the email template of the password reset email. + +Alternatively, you can set these options via the respective [environment variables](/run/environment-configuration/#pocketbase). diff --git a/docs/src/content/docs/run/custom-categories.md b/docs/src/content/docs/run/custom-categories.md deleted file mode 100644 index 699bf84f..00000000 --- a/docs/src/content/docs/run/custom-categories.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Custom categories -description: How to create custom trail categories ---- - -wanderer uses categories to classify what kind of activity a trail belongs to. Out of the box you get: Biking, Canoeing, Climbing, Hiking, Skiing and Walking. However, you can adapt these categories to your needs or add completely new ones. - -## Modifying categories - -![Pocketbase Categories](../../../assets/guides/pocketbase_categories.png) - -In the PocketBase admin panel, click on the `categories` table in the list on the left side. All existing categories will be listed here. To edit one simply click on the row, edit the data you want to change, and click "Save". To delete a category check the box at the beginning of the row and click "Delete selected". To create a new category click the "New record" button in the top right corner, give your new category a name and a background image, and click "Save". diff --git a/docs/src/content/docs/run/installation.mdx b/docs/src/content/docs/run/installation.mdx index c56df744..a30be7f0 100644 --- a/docs/src/content/docs/run/installation.mdx +++ b/docs/src/content/docs/run/installation.mdx @@ -177,7 +177,7 @@ docker compose pull docker compose up -d ``` -Always consult the [changelog](/run/changelog) before updating, in case of breaking changes. +Always consult the [changelog](/changelog) before updating, in case of breaking changes. ## Installation from Source @@ -274,7 +274,7 @@ To update to the latest version: git pull origin main ``` -Then re-run the launch script. Always review the [changelog](/run/changelog) for breaking changes. +Then re-run the launch script. Always review the [changelog](/changelog) for breaking changes. ## Verify the Installation diff --git a/docs/src/content/docs/use/authentication.md b/docs/src/content/docs/use/authentication.md index d016363e..b2bc416b 100644 --- a/docs/src/content/docs/use/authentication.md +++ b/docs/src/content/docs/use/authentication.md @@ -45,6 +45,8 @@ Alternatively, wanderer supports authen If your instance offers OAuth logins, the enabled providers appear in wanderer's login form. Click the button, authorize wanderer, and wait for the authentication to finish. You are now logged in and can use wanderer like any other user. +For instructions on enabling OAuth2 providers for your own instance, see the [OAuth2 setup guide](/run/backend-configuration/oauth2/). + ## Forgot your password? wanderer offers the option to send password reset emails in case a user forgets his password. You can click the "Forgot password" link in the login form. After requesting the reset the user will receive an email with a unique link to reset their password. \ No newline at end of file diff --git a/docs/src/custom.css b/docs/src/custom.css index 3507933a..c86b45a6 100644 --- a/docs/src/custom.css +++ b/docs/src/custom.css @@ -13,6 +13,10 @@ @apply list-decimal list-inside ml-4 } +details details .group-label span { + font-size: var(--sl-text-sm); + font-weight: 400; +} .card .icon { background-color: transparent !important; diff --git a/web/src/lib/components/footer.svelte b/web/src/lib/components/footer.svelte index 8fcc04f8..b01c2b7a 100644 --- a/web/src/lib/components/footer.svelte +++ b/web/src/lib/components/footer.svelte @@ -36,7 +36,7 @@ {$_("features")}
  • - {$_("changelog")}