mirror/wanderer
1
0
Fork 0
mirror of https://github.com/Flomp/wanderer.git synced 2025-12-21 12:59:58 -06:00
Code Issues Packages Projects Releases Wiki Activity

Change docs (#441)

Browse Source 
* Change docs

* hide backend config & small style change

---------

Co-authored-by: Christian Beutel <>
This commit is contained in:
Jonas Plum
2025-08-22 17:56:38 +02:00
committed by GitHub
parent fdb6ef3b76
commit 05ad5ce8e0
15 changed files with 136 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/astro.config.mjs
View File

@@ -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/',
},
});

2
docs/src/components/footer.astro
View File

@@ -144,7 +144,7 @@ const isNotHomepage = Astro.locals.starlightRoute.id !== "";
<a href="#features">Features</a>
</li>
<li>
<a href="/run/changelog/">Changelog</a>
<a href="/changelog/">Changelog</a>
</li>
<li>
<a href="https://github.com/Flomp/wanderer/blob/main/LICENSE">

0
docs/src/content/docs/run/changelog.md → docs/src/content/docs/changelog.md
View File

2
docs/src/content/docs/develop/local-development.md
View File

@@ -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

43
docs/src/content/docs/run/backend-configuration.md
View File

@@ -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
<span class="-tracking-[0.075em]">wanderer</span> 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 <span class="-tracking-[0.075em]">wanderer</span> 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/).

23
docs/src/content/docs/run/backup-server.md → docs/src/content/docs/run/backend-configuration/backup-server.md
View File

@@ -3,29 +3,40 @@ title: Backing up your server
description: How to backup data
---
<span class="-tracking-[0.075em]">wanderer</span> 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 <span class="-tracking-[0.075em]">wanderer</span>. It is therefore only necessary to backup the data generated by PocketBase.
<span class="-tracking-[0.075em]">wanderer</span> 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 <span class="-tracking-[0.075em]">wanderer</span>.
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 <span class="-tracking-[0.075em]">wanderer</span> 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 <span class="-tracking-[0.075em]">wanderer</span> 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 <span class="-tracking-[0.075em]">wanderer</span> 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 <span class="-tracking-[0.075em]">wanderer</span> 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

18
docs/src/content/docs/run/backend-configuration/custom-categories.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: Custom categories
description: How to create custom trail categories
---
<span class="-tracking-[0.075em]">wanderer</span> 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".

27
docs/src/content/docs/run/backend-configuration/index.md Normal file
View File

@@ -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/).

22
docs/src/content/docs/run/backend-configuration/oauth2.md Normal file
View File

@@ -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 <span class="-tracking-[0.075em]">wanderer</span> 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.

18
docs/src/content/docs/run/backend-configuration/smtp.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: SMTP settings
description: Configure email notifications
redirectFrom:
- /run/backend-configuration/#configure-smtp-settings
---
<span class="-tracking-[0.075em]">wanderer</span> 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).

12
docs/src/content/docs/run/custom-categories.md
View File

@@ -1,12 +0,0 @@
---
title: Custom categories
description: How to create custom trail categories
---
<span class="-tracking-[0.075em]">wanderer</span> 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".

4
docs/src/content/docs/run/installation.mdx
View File

@@ -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

2
docs/src/content/docs/use/authentication.md
View File

@@ -45,6 +45,8 @@ Alternatively, <span class="-tracking-[0.075em]">wanderer</span> supports authen
If your instance offers OAuth logins, the enabled providers appear in <span class="-tracking-[0.075em]">wanderer</span>'s login form. Click the button, authorize <span class="-tracking-[0.075em]">wanderer</span>, and wait for the authentication to finish. You are now logged in and can use <span class="-tracking-[0.075em]">wanderer</span> 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?
<span class="-tracking-[0.075em]">wanderer</span> 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.

4
docs/src/custom.css
View File

@@ -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;

2
web/src/lib/components/footer.svelte
View File

@@ -36,7 +36,7 @@
<a href="https://wanderer.to/#features">{$_("features")}</a>
</li>
<li>
<a href="https://wanderer.to/run/changelog/"
<a href="https://wanderer.to/changelog/"
>{$_("changelog")}</a
>
</li>