move documentation/ to docs/

This commit is contained in:
2026-03-08 20:00:08 +00:00
parent 604b52bcc7
commit 006a28ea0f
58 changed files with 41 additions and 0 deletions

View File

@@ -0,0 +1,23 @@
# Advanced Configuration
In addition to the primary configuration variables listed above, there are several optional environment variables that can be set to further customize your Voyage instance. These variables are not required for a basic setup but can enhance functionality and security.
| Name | Required | Description | Default Value | Variable Location |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ----------------- |
| `ACCOUNT_EMAIL_VERIFICATION` | No | Enable email verification for new accounts. Options are `none`, `optional`, or `mandatory` | `none` | Backend |
| `FORCE_SOCIALACCOUNT_LOGIN` | No | When set to `True`, only social login is allowed (no password login). The login page will show only social providers or redirect directly to the first provider if only one is configured. | `False` | Backend |
| `SOCIALACCOUNT_ALLOW_SIGNUP` | No | When set to `True`, signup will be allowed via social providers even if registration is disabled. | `False` | Backend |
| `OSRM_BASE_URL` | No | Base URL of the OSRM routing server used for itinerary connector distance/travel-time metrics. The public OSRM demo server is used by default. Set this to point at your own OSRM instance (e.g. `http://osrm:5000`) for higher rate limits or offline use. When the OSRM server is unreachable, the backend automatically falls back to haversine-based approximations so the itinerary UI always shows metrics. | `https://router.project-osrm.org` | Backend |
| `FIELD_ENCRYPTION_KEY` | No* | Fernet key used to encrypt user API keys at rest (integrations API key storage). Generate a 32-byte urlsafe base64 key (e.g. `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`). If missing/invalid, only API-key storage endpoints fail gracefully and the rest of the app remains available. | _(none)_ | Backend |
| `DJANGO_MCP_ENDPOINT` | No | HTTP path used for the Voyage Travel Agent MCP endpoint. Clients call this endpoint with `Authorization: Token <token>` using a DRF auth token for the target user account. | `api/mcp` | Backend |
## MCP endpoint authentication details
Voyage's MCP endpoint requires token authentication.
- Header format: `Authorization: Token <token>`
- Default endpoint path: `api/mcp`
- Override path with: `DJANGO_MCP_ENDPOINT`
- Token bootstrap endpoint for authenticated sessions: `GET /auth/mcp-token/`
For MCP usage patterns and tool-level examples, see the [Travel Agent (MCP) guide](../guides/travel_agent.md).

View File

@@ -0,0 +1,10 @@
# Umami Analytics (optional)
Umami Analytics is a free, open-source, and privacy-focused web analytics tool that can be used as an alternative to Google Analytics. Learn more about Umami Analytics [here](https://umami.is/).
To enable Umami Analytics for your Voyage instance, you can set the following variables in your `docker-compose.yml` under the `web` service:
```yaml
PUBLIC_UMAMI_SRC=https://cloud.umami.is/script.js # If you are using the hosted version of Umami
PUBLIC_UMAMI_WEBSITE_ID=
```

View File

@@ -0,0 +1,10 @@
# Disable Registration
To disable registration, you can set the following variable in your docker-compose.yml under the server service:
```yaml
environment:
- DISABLE_REGISTRATION=True
# OPTIONAL: Set the message to display when registration is disabled
- DISABLE_REGISTRATION_MESSAGE='Registration is disabled for this instance of Voyage.'
```

View File

@@ -0,0 +1,34 @@
# Change Email Backend
To change the email backend, you can set the following variable in your docker-compose.yml under the server service:
## Using Console (default)
```yaml
environment:
- EMAIL_BACKEND=console
```
## With SMTP
```yaml
environment:
- EMAIL_BACKEND=email
- EMAIL_HOST=smtp.gmail.com
- EMAIL_USE_TLS=True
- EMAIL_PORT=587
- EMAIL_USE_SSL=False
- EMAIL_HOST_USER=user
- EMAIL_HOST_PASSWORD=password
- DEFAULT_FROM_EMAIL=user@example.com
```
## Customizing Emails
By default, the email will display `[example.com]` in the subject. You can customize this in the admin site.
1. Go to the admin site (serverurl/admin)
2. Click on `Sites`
3. Click on first site, it will probably be `example.com`
4. Change the `Domain name` and `Display name` to your desired values
5. Click `Save`

View File

@@ -0,0 +1,42 @@
# Google Maps Integration
To enable Google Maps integration in Voyage, you'll need to create a Google Maps API key. This key allows Voyage to use Google Maps services such as geocoding and location search throughout the application.
Follow the steps below to generate your own API key:
## Google Cloud Console Setup
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create an account if you don't have one in order to access the console.
3. Click on the project dropdown in the top bar.
4. Click **New Project**.
5. Name your project (e.g., `Voyage Maps`) and click **Create**.
6. Once the project is created, ensure it is selected in the project dropdown.
7. Click on the **Navigation menu** (three horizontal lines in the top left corner).
8. Navigate to **Google Maps Platform**.
9. Once in the Maps Platform, click on **Keys & Credentials** in the left sidebar.
10. Click on **Create credentials** and select **API key**.
11. A dialog will appear with your new API key. Copy this key for later use.
> [!Note]
> When creating the API Key, you can choose which APIs it can use.
> For versions *v0.10.0* and _lower_, you need the *Geocoding* and *Places* APIs.
> For versions _higher_ than v0.10.0, You'll need *Geocoding* and *Places (New)*.
> Note that the latter isn't enabled by default!
<!-- To prevent misuse:
1. Click the **Edit icon** next to your new API key.
2. Under **Application restrictions**, choose one:
- Choose **Websites** as the restriction type.
- Add the domain of the Voyage **backend** (e.g., `https://your-voyage-backend.com`). -->
## Configuration in Voyage
Set the API key in your environment file or configuration under the backend service of Voyage. This is typically done in the `docker-compose.yml` file or directly in your environment variables `.env` file.
```env
GOOGLE_MAPS_API_KEY=your_api_key_here
```
Once this is set, Voyage will be able to utilize Google Maps services for geocoding and location searches instead of relying on the default OpenStreetMap services.

View File

@@ -0,0 +1,29 @@
# Immich Integration
### What is Immich?
<!-- immich banner -->
![Immich Banner](https://repository-images.githubusercontent.com/455229168/ebba3238-9ef5-4891-ad58-a3b0223b12bd)
Immich is a self-hosted, open-source platform that allows users to backup and manage their photos and videos similar to Google Photos, but with the advantage of storing data on their own private server, ensuring greater privacy and control over their media.
- [Immich Website and Documentation](https://immich.app/)
- [GitHub Repository](https://github.com/immich-app/immich)
### How to integrate Immich with Voyage?
To integrate Immich with Voyage, you need to have an Immich server running and accessible from where Voyage is running.
1. Obtain the Immich API Key from the Immich server.
- In the Immich web interface, click on your user profile picture, go to `Account Settings` > `API Keys`.
- Click `New API Key` and name it something like `Voyage`.
- Make sure the key has the following permissions: `asset.read, album.read, asset.view, library.read, user.read`
- Copy the generated API Key, you will need it in the next step.
2. Go to the Voyage web interface, click on your user profile picture, go to `Settings` and scroll down to the `Immich Integration` section.
- Enter the URL of your Immich server, e.g. `https://immich.example.com/api`. Note that `localhost` or `127.0.0.1` will probably not work because Immich and Voyage are running on different docker networks. It is recommended to use the IP address of the server where Immich is running ex `http://my-server-ip:port` or a domain name.
- Paste the API Key you obtained in the previous step.
- Click `Enable Immich` to save the settings.
3. Now, when you are adding images to an adventure, you will see an option to search for images in Immich or upload from an album.
Enjoy the privacy and control of managing your travel media with Immich and Voyage! 🎉

View File

@@ -0,0 +1,16 @@
# Social Authentication
Voyage support authentication via 3rd party services and self-hosted identity providers. Once these services are enabled, users can log in to Voyage using their accounts from these services and link existing Voyage accounts to these services for easier access.
The steps for each service varies so please refer to the specific service's documentation for more information.
## Supported Services
- [Authentik](social_auth/authentik.md) (self-hosted)
- [GitHub](social_auth/github.md)
- [Open ID Connect](social_auth/oidc.md)
- [Authelia](https://www.authelia.com/integration/openid-connect/voyage/)
## Linking Existing Accounts
If you already have an Voyage account and would like to link it to a 3rd party service, you can do so by logging in to Voyage and navigating to the `Account Settings` page. From there, scroll down to `Social and OIDC Authentication` and click the `Launch Account Connections` button. If identity providers have been enabled on your instance, you will see a list of available services to link to.

View File

@@ -0,0 +1,70 @@
# Authentik OIDC Authentication
<img src="https://repository-images.githubusercontent.com/230885748/19f01d00-8e26-11eb-9a14-cf0d28a1b68d" alt="Authentik Logo" width="400" />
Authentik is a self-hosted identity provider that supports OpenID Connect and OAuth2. Voyage can be configured to use Authentik as an identity provider for social authentication. Learn more about Authentik at [goauthentik.io](https://goauthentik.io/).
Once Authentik is configured by the administrator, users can log in to Voyage using their Authentik account and link existing Voyage accounts to Authentik for easier access.
# Configuration
To enable Authentik as an identity provider, the administrator must first configure Authentik to allow Voyage to authenticate users.
### Authentik Configuration
1. Log in to Authentik and navigate to the `Providers` page and create a new provider.
2. Select `OAuth2/OpenID Provider` as the provider type.
3. Name it `Voyage` or any other name you prefer.
4. Set the `Redirect URI` of type `Regex` to `^http://<voyage-server-url>/accounts/oidc/.*$` where `<voyage-url>` is the URL of your Voyage Server service.
5. Copy the `Client ID` and `Client Secret` generated by Authentik, you will need these to configure Voyage.
6. Create an application in Authentik and assign the provider to it, name the `slug` `voyage` or any other name you prefer.
7. If you want the logo, you can find it [here](https://voyage.app/voyage.png).
### Voyage Configuration
This configuration is done in the [Admin Panel](../../guides/admin_panel.md). You can either launch the panel directly from the `Settings` page or navigate to `/admin` on your Voyage server.
1. Login to Voyage as an administrator and navigate to the `Settings` page.
2. Scroll down to the `Administration Settings` and launch the admin panel.
3. In the admin panel, navigate to the `Social Accounts` section and click the add button next to `Social applications`. Fill in the following fields:
- Provider: `OpenID Connect`
- Provider ID: Authentik Client ID
- Name: `Authentik`
- Client ID: Authentik Client ID
- Secret Key: Authentik Client Secret
- Key: can be left blank
- Settings: (make sure http/https is set correctly)
```json
{
"server_url": "http://<authentik_url>/application/o/[YOUR_SLUG]/"
}
```
::: warning
`localhost` is most likely not a valid `server_url` for Authentik in this instance because `localhost` is the server running Voyage, not Authentik. You should use the IP address of the server running Authentik or the domain name if you have one.
- Sites: move over the sites you want to enable Authentik on, usually `example.com` and `www.example.com` unless you renamed your sites.
#### What it Should Look Like
![Authentik Social Auth Configuration](/authentik_settings.png)
4. Save the configuration.
Ensure that the Authentik server is running and accessible by Voyage. Users should now be able to log in to Voyage using their Authentik account.
## Linking to Existing Account
If a user has an existing Voyage account and wants to link it to their Authentik account, they can do so by logging in to their Voyage account and navigating to the `Settings` page. There is a button that says `Launch Account Connections`, click that and then choose the provider to link to the existing account.
## Troubleshooting
### 404 error when logging in.
Ensure the `<voyage-server-url>/accounts` path is routed to the backend, as it shouldn't hit the frontend when it's properly configured.
### Authentik - No Permission
In the Authentik instance, check access to the Voyage application from a specific user by using the Check Access/Test button on the Application dashboard. If the user doesn't have access, you can add an existing user/group policy to give your specific user/group access to the Voyage application.

View File

@@ -0,0 +1,49 @@
# GitHub Social Authentication
Voyage can be configured to use GitHub as an identity provider for social authentication. Users can then log in to Voyage using their GitHub account.
# Configuration
To enable GitHub as an identity provider, the administrator must first configure GitHub to allow Voyage to authenticate users.
### GitHub Configuration
1. Visit the GitHub OAuth Apps Settings page at [https://github.com/settings/developers](https://github.com/settings/developers).
2. Click on `New OAuth App`.
3. Fill in the following fields:
- Application Name: `Voyage` or any other name you prefer.
- Homepage URL: `<voyage-frontend-url>` where `<voyage-frontend-url>` is the URL of your Voyage Frontend service.
- Application Description: `Voyage` or any other description you prefer.
- Authorization callback URL: `http://<voyage-backend-url>/accounts/github/login/callback/` where `<voyage-backend-url>` is the URL of your Voyage Backend service.
- If you want the logo, you can find it [here](https://voyage.app/voyage.png).
### Voyage Configuration
This configuration is done in the [Admin Panel](../../guides/admin_panel.md). You can either launch the panel directly from the `Settings` page or navigate to `/admin` on your Voyage server.
1. Login to Voyage as an administrator and navigate to the `Settings` page.
2. Scroll down to the `Administration Settings` and launch the admin panel.
3. In the admin panel, navigate to the `Social Accounts` section and click the add button next to `Social applications`. Fill in the following fields:
- Provider: `GitHub`
- Provider ID: GitHub Client ID
- Name: `GitHub`
- Client ID: GitHub Client ID
- Secret Key: GitHub Client Secret
- Key: can be left blank
- Settings: can be left blank
- Sites: move over the sites you want to enable Authentik on, usually `example.com` and `www.example.com` unless you renamed your sites.
4. Save the configuration.
Users should now be able to log in to Voyage using their GitHub account, and link it to existing accounts.
## Linking to Existing Account
If a user has an existing Voyage account and wants to link it to their Github account, they can do so by logging in to their Voyage account and navigating to the `Settings` page. There is a button that says `Launch Account Connections`, click that and then choose the provider to link to the existing account.
#### What it Should Look Like
![Authentik Social Auth Configuration](/github_settings.png)

View File

@@ -0,0 +1,7 @@
# OIDC Social Authentication
Voyage can be configured to use OpenID Connect (OIDC) as an identity provider for social authentication. Users can then log in to Voyage using their OIDC account.
The configuration is basically the same as [Authentik](./authentik.md), but you replace the client and secret with the OIDC client and secret provided by your OIDC provider. The `server_url` should be the URL of your OIDC provider where you can find the OIDC configuration.
Each provider has a different configuration, so you will need to check the documentation of your OIDC provider to find the correct configuration.

View File

@@ -0,0 +1,143 @@
# Pocket ID OIDC Authentication
<img src="https://pocket-id.org/logo.png" alt="Pocket ID Logo" width="400" />
Pocket ID is a lightweight, self-hosted OpenID Connect (OIDC) identity provider. Voyage can be configured to use Pocket ID for social authentication using its built-in OpenID Connect support.
Once Pocket ID is configured by an administrator, users can sign in to Voyage using their Pocket ID account and optionally link it to an existing Voyage account.
---
# Configuration
To enable Pocket ID as an identity provider, both Pocket ID and Voyage must be configured correctly. The most important (and least obvious) part of this setup is the **callback URL**, which must match Voyages internal OIDC routing.
---
## Pocket ID Configuration
1. Log in to your Pocket ID admin interface.
2. Navigate to **Clients** and create a new client.
3. Name the client something like `Voyage`.
4. Set the **Redirect / Callback URL** to:
```
https://<voyage-backend.example.com>/accounts/oidc/<CLIENT_ID>/login/callback/
```
- Replace `<voyage-backend.example.com>` with the **backend** URL of your Voyage instance.
- Replace `<CLIENT_ID>` with the **Pocket ID client ID** exactly as generated.
- This path is required and currently not auto-documented by Pocket ID or Voyage.
5. Ensure the client type is **Confidential**.
6. Copy the generated **Client ID** and **Client Secret** — you will need both for Voyage.
---
## Voyage Configuration
This configuration is done in the [Admin Panel](../../guides/admin_panel.md). You can launch it from the `Settings` page or navigate directly to `/admin` on your Voyage server.
1. Log in to Voyage as an administrator.
2. Navigate to **Settings** → **Administration Settings** and launch the admin panel.
3. Go to **Social Accounts**.
4. Under **Social applications**, click **Add**.
5. Fill in the fields as follows:
### Social Application Settings
- **Provider**: `OpenID Connect`
- **Provider ID**: Pocket ID Client ID
- **Name**: `Pocket ID`
- **Client ID**: Pocket ID Client ID
- **Secret Key**: Pocket ID Client Secret
- **Key**: _(leave blank)_
- **Settings**:
```json
{
"server_url": "https://<pocketid-url>/.well-known/openid-configuration"
}
```
- Replace `<pocketid-url>` with the base URL of your Pocket ID instance.
::: warning
Do **not** use `localhost` unless Pocket ID is running on the same machine and is resolvable from inside the Voyage container or service. Use a domain name or LAN IP instead.
:::
- **Sites**: Move the sites you want Pocket ID enabled on (usually `example.com` and `www.example.com`).
6. Save the configuration.
Ensure Pocket ID is running and reachable by Voyage.
---
## What It Should Look Like
Once configured correctly:
- Pocket ID appears as a login option on the Voyage login screen.
- Logging in redirects to Pocket ID, then back to Voyage without errors.
---
## Linking to an Existing Account
If a user already has an Voyage account:
1. Log in to Voyage normally.
2. Go to **Settings**.
3. Click **Launch Account Connections**.
4. Choose **Pocket ID** to link the identity to the existing account.
This allows future logins using Pocket ID without creating a duplicate account.
---
## Troubleshooting
### 404 Error After Login
Ensure that:
- `/accounts` routes are handled by the **backend**, not the frontend.
- Your reverse proxy (Nginx, Traefik, Caddy, etc.) forwards `/accounts/*` correctly.
---
### Invalid Redirect URI
- Double-check that the callback URL in Pocket ID exactly matches:
```
/accounts/oidc/<CLIENT_ID>/login/callback/
```
- The `<CLIENT_ID>` must match the value used in the Voyage social application.
---
### Cannot Reach Pocket ID
- Verify that the `.well-known/openid-configuration` endpoint is accessible from the Voyage server.
- Test by opening:
```
https://<pocketid-url>/.well-known/openid-configuration
```
in a browser.
---
## Notes
- Pocket ID configuration is very similar to Authentik.
- The main difference is the **explicit callback URL requirement** and the use of the `.well-known/openid-configuration` endpoint as the `server_url`.
- This setup works with Docker, Docker Compose, and bare-metal deployments as long as networking i

View File

@@ -0,0 +1,43 @@
# Strava Integration
Strava is a popular platform for athletes to track their activities, share their workouts, and connect with other fitness enthusiasts. Integrating Strava with Voyage allows you to import your Strava activities directly into your vists, making it easier to keep track of your outdoor experiences.
To enable Strava integration in Voyage, you'll need to create a Strava API application. This application will provide you with the necessary client ID and client secret to authenticate with the Strava API.
Follow the steps below to generate your own Strava API credentials:
## Strava API Application Setup
1. Login to your Strava account at [Strava](https://www.strava.com/).
2. Go to the [Strava API Applications page](https://www.strava.com/settings/api).
3. Click on **Create a New Application**.
4. Fill in the application details:
- **Application Name**: Voyage Strava Integration
- **Website**: Your Voyage instance URL (e.g., `https://your-voyage-instance.com`)
- **Authorization Callback Domain**: Your Voyage instance domain (e.g., `your-voyage-instance.com`)
5. Agree to the Strava API Terms
6. Click **Create** to generate your application.
7. After creation, you will see your **Client ID** and **Client Secret**. Keep these credentials safe as you will need them to configure Voyage.
## Configuration in Voyage
8. Once you have your Strava API credentials, you can configure Voyage to use them. Open your `.env` file in the root of your Voyage project and add the following lines:
```env
STRAVA_CLIENT_ID=your_client_id_here
STRAVA_CLIENT_SECRET=your_client_secret_here
```
9. After adding these lines, save the file and restart your Voyage server to apply the changes.
10. Navigate to Voyage's settings page, click the integration tab, and find the Strava section.
11. Click the **Connect Account** button. This will redirect you to Strava's authorization page.
12. Log in to your Strava account and authorize Voyage to access your Strava data.
13. After authorization, you will be redirected back to Voyage, and your Strava account will be linked.
## Importing Strava Activities
The Strava integration appears on the visit create/edit part of the location edit popup. Once a visit is added, there will be a button on it to search for Strava activities. Clicking this button will search then you can import the activity into the visit. The imported activity will include details such as distance, duration, elevation gain, and more.
**Note**: Due to API limitations on Strava's side, when you import an activity, there will be a button that says **Download GPX** then you can download the GPX file of the activity and drop it into the input field of the visit. This manual action is necessary because Strava does not provide a direct way to import GPX files into Voyage.
Enjoy tracking your adventures with Strava and Voyage! If you encounter any issues or have questions about the integration, feel free to reach out to the Voyage community!

View File

@@ -0,0 +1,43 @@
# Updating
Updating Voyage when using docker can be quite easy. Run a collections backup before upgrading, then pull the latest version and restart the containers.
## Pre-upgrade backup (recommended)
Before running migrations or updating containers, export a collections snapshot:
```bash
docker compose exec server python manage.py export_collections_backup
```
You can also provide a custom output path:
```bash
docker compose exec server python manage.py export_collections_backup --output /code/backups/collections_backup_pre_upgrade.json
```
The backup file includes a timestamp, record counts, and snapshot data for:
- `Collection`
- `CollectionItineraryItem`
Note: Make sure you are in the same directory as your `docker-compose.yml` file.
```bash
docker compose pull
docker compose up -d
```
## Updating the Region Data
Region and Country data in Voyage is provided by an open source project: [dr5hn/countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database). If you would like to update the region data in your Voyage instance, you can do so by running the following command. This will make sure your database is up to date with the latest region data for your version of Voyage. For security reasons, the region data is not automatically updated to the latest and is release version is controlled in the `settings.py` file.
```bash
docker exec -it <container> bash
```
Once you are in the container run the following command to resync the region data.
```bash
python manage.py download-countries --force
```

View File

@@ -0,0 +1,26 @@
# Wanderer Integration
[Wanderer](https://wanderer.to) is a self-hosted trail database. Integrating Wanderer with Voyage allows you to import trails directly into your locations, making it easier to plan and track your outdoor adventures.
## Wanderer Integration Setup
1. Navigate to the Voyage settings page.
2. Click on the **Integrations** tab.
3. Find the **Wanderer** section and input the URL of your Wanderer instance, your username, and password.
4. Click the **Connect Account** button to authenticate with your Wanderer instance.
### Important Notes
1. The URL to the Wanderer server must be accessible from the Voyage server. This means values like `localhost` or `127.0.0.1` will likely cause some issues.
2. Voyage **does not store your Wanderer credentials**. They are only used to fetch an authorization token for the Wanderer API. This token will last for around 2 weeks before needing to be refreshed. Using the token refreshes the token for another 2 weeks. Should the token expire, you will need to re-enter your credentials in the Voyage settings page.
## Importing Wanderer Trails
1. Open the create/edit location popup in Voyage.
2. Naviage to the **Media** tab and scroll down to the **Trail Managment** section.
3. Click the **Add Wanderer Trail** button.
4. A search input will appear. Type in the name of the trail you want to import.
5. Select the desired trail from the search results and click the link icon to import it into your location.
6. The imported trail will be added to your location's trails list, and you can view its details, including distance, elevation gain, and more.
Enjoy exploring new trails with Wanderer and Voyage! If you encounter any issues or have questions about the integration, feel free to reach out to the Voyage community!