adds more docs
This commit is contained in:
Christian Beutel
BIN
docs/src/assets/hero.png
Normal file
BIN
docs/src/assets/hero.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 984 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 4.1 KiB |
98
docs/src/assets/logo_dark_text.svg
Normal file
98
docs/src/assets/logo_dark_text.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 10 KiB |
@@ -1,34 +0,0 @@
|
||||
<script lang="ts">
|
||||
export let type: "button" | "submit" | "reset" | null | undefined =
|
||||
undefined;
|
||||
export let icon: string = "";
|
||||
export let extraClasses: string = "";
|
||||
export let primary: boolean = false;
|
||||
export let secondary: boolean = false;
|
||||
export let large: boolean = false;
|
||||
export let loading: boolean = false;
|
||||
export let disabled: boolean = false;
|
||||
export let tooltip: string = "";
|
||||
</script>
|
||||
|
||||
<button
|
||||
class="{extraClasses} flex items-center justify-center"
|
||||
class:btn-primary={primary}
|
||||
class:btn-secondary={secondary}
|
||||
class:btn-large={large}
|
||||
class:btn-disabled={disabled || loading}
|
||||
disabled={disabled || loading}
|
||||
class:tooltip={tooltip.length > 0}
|
||||
data-title={tooltip}
|
||||
on:click
|
||||
{type}
|
||||
>
|
||||
{#if !loading}
|
||||
{#if icon}
|
||||
<i class="fa fa-{icon} mr-2"></i>
|
||||
{/if}
|
||||
<slot />
|
||||
{:else}
|
||||
<div class="spinner"></div>
|
||||
{/if}
|
||||
</button>
|
||||
197
docs/src/components/footer.astro
Normal file
197
docs/src/components/footer.astro
Normal file
File diff suppressed because one or more lines are too long
183
docs/src/content/docs/getting-started/Installation.md
Normal file
183
docs/src/content/docs/getting-started/Installation.md
Normal file
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Detailed installation instructions for docker and bare-metal
|
||||
---
|
||||
|
||||
wanderer consists of three components:
|
||||
1. the frontend written with [SvelteKit](https://github.com/sveltejs/kit)
|
||||
2. the backend, a custom [PocketBase](https://github.com/pocketbase/pocketbase) fork
|
||||
3. the index, a standard [meilisearch](https://github.com/meilisearch/meilisearch) application
|
||||
|
||||
You can install these components in two ways.
|
||||
|
||||
## Docker
|
||||
|
||||
This is the easiest and most convenient way to install wanderer. After cloning the repository you will find a [docker-compose.yml](https://github.com/Flomp/wanderer/blob/main/docker-compose.yml) file in the root directory that will install and run all necessary components by running `docker compose up -d`.
|
||||
|
||||
:::note
|
||||
If you are not hosting wanderer at `http://localhost:3000` make sure to change `ORIGIN` environment variable to `http(s)://<your_domain>:<your_port>`. Otherwise you will run into CORS errors.
|
||||
:::
|
||||
|
||||
```docker-compose
|
||||
version: '3'
|
||||
|
||||
x-common-env: &cenv
|
||||
MEILI_URL: http://search:7700
|
||||
MEILI_MASTER_KEY: vODkljPcfFANYNepCHyDyGjzAMPcdHnrb6X5KyXQPWo
|
||||
|
||||
services:
|
||||
search:
|
||||
container_name: wanderer-search
|
||||
image: flomp/wanderer-search
|
||||
environment:
|
||||
<<: *cenv
|
||||
MEILI_NO_ANALYTICS: true
|
||||
ports:
|
||||
- 7700:7700
|
||||
networks:
|
||||
- wanderer
|
||||
volumes:
|
||||
- ./data/data.ms:/meili_data/data.ms
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: curl --fail http://localhost:7700/health || exit 1
|
||||
interval: 15s
|
||||
retries: 10
|
||||
start_period: 20s
|
||||
timeout: 10s
|
||||
db:
|
||||
container_name: wanderer-db
|
||||
image: flomp/wanderer-db
|
||||
depends_on:
|
||||
search:
|
||||
condition: service_healthy
|
||||
environment:
|
||||
<<: *cenv
|
||||
ports:
|
||||
- "8090:8090"
|
||||
networks:
|
||||
- wanderer
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- ./data/pb_data:/pb_data
|
||||
web:
|
||||
container_name: wanderer-web
|
||||
image: flomp/wanderer-web
|
||||
depends_on:
|
||||
search:
|
||||
condition: service_healthy
|
||||
db:
|
||||
condition: service_started
|
||||
environment:
|
||||
<<: *cenv
|
||||
ORIGIN: http://localhost:3000
|
||||
BODY_SIZE_LIMIT: Infinity
|
||||
PUBLIC_POCKETBASE_URL: http://db:8090
|
||||
PUBLIC_DISABLE_SIGNUP: false
|
||||
UPLOAD_FOLDER: /app/uploads
|
||||
UPLOAD_USER:
|
||||
UPLOAD_PASSWORD:
|
||||
PUBLIC_VALHALLA_URL: https://valhalla1.openstreetmap.de
|
||||
volumes:
|
||||
- ./data/uploads:/app/uploads
|
||||
ports:
|
||||
- "3000:3000"
|
||||
networks:
|
||||
- wanderer
|
||||
restart: unless-stopped
|
||||
|
||||
networks:
|
||||
wanderer:
|
||||
driver: bridge
|
||||
```
|
||||
### Networking
|
||||
All three components must be on the same network for wanderer to function properly. This is the case in the default configuration shown above. However, if you run wanderer behind a proxy like traefik, please ensure all three components can communicate.
|
||||
Notice that you must set the `ORIGIN` environment variable for the web service to the public IP or hostname including the port that wanderer is reachable at. Otherwise, you will see wanderer's frontend throw an `Cross-site POST form submissions are forbidden` error.
|
||||
|
||||
The standard configuration makes all three services publically available by forwarding their ports. For the database and the index service this is not strictly necessary. In case you do not require direct access to them you can disable their ports in the docker-compose file.
|
||||
|
||||
### Volumes
|
||||
By default, wanderer uses two volumes. One for meilisearch indices and one for all PocketBase data. In the default configuration, the data is stored in volumes. However, if you prefer to use bind mounts you can simply adapt the configuration accordingly.
|
||||
|
||||
### Environment
|
||||
The default configuration contains all necessary environment variables. However, there are more options that allow you to modify how the backend and index operate. For more details, you can take a look at the respective section of the [documentation](https://github.com/Flomp/wanderer/wiki/Configuration).
|
||||
|
||||
:::caution
|
||||
Ensure that you change the `MEILI_MASTER_KEY` to a different value if you plan to use wanderer in a production environment.
|
||||
:::
|
||||
|
||||
### Updating
|
||||
|
||||
To update all containers to a new version simply run `docker compose pull && docker compose up -d`. Make sure to read the changelog to check for breaking changes.
|
||||
|
||||
## From source
|
||||
|
||||
While not recommended it is absolutely possible to install wanderer from source.
|
||||
|
||||
### Prerequisites
|
||||
1. git installed && `git clone https://github.com/Flomp/wanderer.git`
|
||||
2. go >= 1.21.1 installed
|
||||
3. node >= 18.17.0 installed
|
||||
|
||||
### meilisearch
|
||||
wanderer uses meilisearch without any further modifications. As a result, you can simply head over to [their website](https://www.meilisearch.com/docs/learn/getting_started/installation) and follow the instructions for your preferred platform. We assume that you put the binary in the `wanderer/search` directory. If you did not, adapt the launch script below accordingly.
|
||||
|
||||
Furthermore, you will need to import the cities index manually. To do so launch meilisearch once with `--import-dump` parameter:
|
||||
```bash
|
||||
./meilisearch --import-dump migrations/migration.dump
|
||||
```
|
||||
Wait for the process to finish and terminate meilisearch afterwards.
|
||||
|
||||
### PocketBase
|
||||
wanderer uses a slightly modified version of the PocketBase backend framework. As a result, you will need to build the PocketBase binary first.
|
||||
```bash
|
||||
cd wanderer/db
|
||||
go mod tidy && go build
|
||||
```
|
||||
This will create a binary in the `wanderer/db` folder. Verify that it is there.
|
||||
|
||||
### Web
|
||||
wanderer's frontend is written in SvelteKit. We first install all dependencies and build the project.
|
||||
```bash
|
||||
cd wanderer/web
|
||||
npm ci --omit=dev
|
||||
npm run build
|
||||
```
|
||||
|
||||
This will create a directory `wanderer/web/build`. Verify that it is there.
|
||||
|
||||
### Launch
|
||||
|
||||
To launch our three services we will use a small bash script. This ensures that all necessary environment variables are set and the services are started in the correct order. All three services are executed as background tasks, but are being trapped so that terminating the bash script will also terminate all three services at once.
|
||||
|
||||
:::caution
|
||||
Caution: Ensure that you change the `MEILI_MASTER_KEY` to a different value if you plan to use wanderer in a production environment.
|
||||
:::
|
||||
|
||||
```bash
|
||||
trap "kill 0" EXIT
|
||||
|
||||
export ORIGIN=http://localhost:3000
|
||||
export MEILI_URL=http://127.0.0.1:7700
|
||||
export MEILI_MASTER_KEY=CHANGE_ME!
|
||||
export PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090
|
||||
export PUBLIC_VALHALLA_URL=https://valhalla1.openstreetmap.de
|
||||
|
||||
cd search && ./meilisearch --master-key $MEILI_MASTER_KEY &
|
||||
cd db && ./pocketbase serve &
|
||||
cd web/build && node build &
|
||||
|
||||
wait
|
||||
```
|
||||
|
||||
### Updating
|
||||
|
||||
To update wanderer to the newest version simply run `git pull origin main` and run the launch script. Make sure to read the changelog to check for breaking changes.
|
||||
|
||||
## Verify the installation
|
||||
No matter which installation method you chose, you should now be able to access wanderer on localhost:3000.
|
||||
|
||||
:::note[Bootstrapping]
|
||||
On the first launch, wanderer will create a rather large city index with over 200,000 entries in meilisearch. This process happens automatically but can take up to 2 minutes to complete. During this time the search functionality might not yet work properly.
|
||||
:::
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Example Guide
|
||||
description: A guide in my new Starlight docs site.
|
||||
---
|
||||
|
||||
Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
|
||||
Writing a good guide requires thinking about what your users are trying to do.
|
||||
|
||||
## Further reading
|
||||
|
||||
- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
|
||||
@@ -10,7 +10,7 @@ hero:
|
||||
file: ../../assets/logo_dark.svg
|
||||
actions:
|
||||
- text: Read the docs
|
||||
link: /guides/example/
|
||||
link: /getting-started/installation/
|
||||
icon: right-arrow
|
||||
variant: primary
|
||||
- text: Visit the demo
|
||||
@@ -19,7 +19,8 @@ hero:
|
||||
---
|
||||
|
||||
import { Card, CardGrid } from '@astrojs/starlight/components';
|
||||
import Button from '../../components/button.svelte';
|
||||
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
@@ -34,11 +35,22 @@ import Button from '../../components/button.svelte';
|
||||
<Card title="Advanced filters and search" icon="magnifier">
|
||||
<span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span> comes with extensive filter and search functionality right out of the box, so you can focus only on the trails relevant to you.
|
||||
</Card>
|
||||
<Card title="Full API support" icon="open-book">
|
||||
Use <span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span>'s API to interact with your trail data directly and automate the tasks that you don't want to do manually.
|
||||
<Card title="Automatic import" icon="seti:folder">
|
||||
Simply upload all your trails in one go with <span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span>'s automatic import feature.
|
||||
|
||||
[Learn more →]()
|
||||
</Card>
|
||||
<Card title="Full API support" icon="seti:json">
|
||||
Use <span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span>'s API to interact with your trail data directly and automate the tasks you don't want to do manually.
|
||||
|
||||
[API reference →]()
|
||||
</Card>
|
||||
<Card title="Privacy friendly" icon="approve-check">
|
||||
<span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span> is self-hosted and open-source. Your data stays on your machine and your machine only.
|
||||
</Card>
|
||||
<Card title="i18n" icon="translate">
|
||||
We currently support 8 different languages, with plans to add more in the near future.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
## Contributing
|
||||
@@ -47,4 +59,4 @@ Help is welcome at any time. Check out the [GitHub repository](https://github.co
|
||||
|
||||
## Support <span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span>
|
||||
|
||||
<span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span> is a passion project and will always stay free and open-source. If you like <span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span> and want to support it's development you can make a small donation and [buy me a coffee](https://buymeacoffee.com/wanderertrails).
|
||||
<span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span> is a passion project and will always stay free and open-source. If you like <span class="-tracking-[0.075em] s-y_bCXRrkrYfP">wanderer</span> and want to support it's development you can make a small donation and [buy me a coffee](https://buymeacoffee.com/wanderertrails).
|
||||
|
||||
13
docs/src/custom.css
Normal file
13
docs/src/custom.css
Normal file
@@ -0,0 +1,13 @@
|
||||
@import 'tailwindcss/utilities';
|
||||
@import 'tailwindcss/base';
|
||||
@import 'tailwindcss/components';
|
||||
|
||||
.card {
|
||||
@apply rounded-xl
|
||||
}
|
||||
|
||||
|
||||
.card .icon {
|
||||
background-color: transparent!important;
|
||||
border-color: var(--sl-color-text)!important
|
||||
}
|
||||
Reference in New Issue
Block a user