diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 1c0f8118..62762808 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -84,7 +84,11 @@ export default defineConfig({ items: [ { label: 'Installation', - link: '/run/installation/' + items: [ + { label: 'Quickstart', link: '/run/installation/quick' }, + { label: 'Manual Docker Setup', link: '/run/installation/docker' }, + { label: 'Install from Source', link: '/run/installation/from-source' }, + ] }, { label: 'Environment configuration', diff --git a/docs/public/setup.sh b/docs/public/setup.sh new file mode 100644 index 00000000..716e5c8e --- /dev/null +++ b/docs/public/setup.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Detect OS for sed compatibility +if [[ "$OSTYPE" == "darwin"* ]]; then + SED_INPLACE() { sed -i '' "$@"; } +else + SED_INPLACE() { sed -i "$@"; } +fi + +# prompt for environment type +read -r -p "Is this a local development setup? (y/n): " is_dev + +if [[ "${is_dev}" =~ ^[Yy]$ ]]; then + origin="http://localhost:3000" + public_disable_signup=false +else + read -r -p "Enter the domain (e.g., example.com): " domain + origin="https://${domain}" + read -r -p "Allow public signups? (y/n): " allow_signups + if [[ "${allow_signups}" =~ ^[Yy]$ ]]; then + public_disable_signup=false + else + public_disable_signup=true + fi +fi + +# generate secrets +meili_key=$(openssl rand -hex 32) +pocket_key=$(openssl rand -hex 16) + +# Download docker-compose.yml using curl or wget +if command -v wget >/dev/null 2>&1; then + wget -O docker-compose.yml https://raw.githubusercontent.com/Flomp/wanderer/refs/heads/main/docker-compose.yml +elif command -v curl >/dev/null 2>&1; then + curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/Flomp/wanderer/refs/heads/main/docker-compose.yml +else + echo "Error: neither wget nor curl is installed." >&2 + exit 1 +fi + +# update docker-compose.yml with secrets and configuration +SED_INPLACE "s/MEILI_MASTER_KEY:.*/MEILI_MASTER_KEY: ${meili_key}/" docker-compose.yml +SED_INPLACE "s/POCKETBASE_ENCRYPTION_KEY:.*/POCKETBASE_ENCRYPTION_KEY: ${pocket_key}/" docker-compose.yml +SED_INPLACE "s|ORIGIN:.*|ORIGIN: ${origin}|" docker-compose.yml +SED_INPLACE "s/PUBLIC_DISABLE_SIGNUP: .*/PUBLIC_DISABLE_SIGNUP: \"${public_disable_signup}\"/" docker-compose.yml + +echo "✅ Setup complete. Run 'docker compose up -d' to start the services." diff --git a/docs/src/content/docs/run/installation.mdx b/docs/src/content/docs/run/installation/docker.mdx similarity index 58% rename from docs/src/content/docs/run/installation.mdx rename to docs/src/content/docs/run/installation/docker.mdx index c5e913b0..0a89c311 100644 --- a/docs/src/content/docs/run/installation.mdx +++ b/docs/src/content/docs/run/installation/docker.mdx @@ -1,18 +1,9 @@ --- -title: Installation -description: Detailed installation instructions for Docker and bare-metal +title: Manual Docker Setup +description: Detailed installation instructions for Docker --- -import { version } from '../../../../package.json'; -wanderer is composed of three key components: - -1. A frontend built with [SvelteKit](https://github.com/sveltejs/kit) -2. A backend, which is a custom fork of [PocketBase](https://github.com/pocketbase/pocketbase) -3. An index service, powered by [Meilisearch](https://github.com/meilisearch/meilisearch) - -You can install these components either via Docker (recommended) or from source. - ---- +You can install wanderer components either via Docker ([Quick Setup](./quick) or [Manual Setup](./docker)) or [from source](./installation-from-source). ## Prerequisites @@ -29,9 +20,7 @@ Do not share this key with anyone! Once you have set the encryption key, you can proceed to install wanderer. -## Installation via Docker - -This is the easiest and most convenient way to install wanderer. +## Start 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. This file sets up all necessary components. Start everything by running: @@ -39,7 +28,7 @@ After cloning the repository, you will find a [`docker-compose.yml`](https://git docker compose up -d ``` -### Configuration Notes +## Configuration Notes If you're not hosting wanderer at `http://localhost:3000`, update the `ORIGIN` environment variable accordingly: @@ -49,7 +38,7 @@ ORIGIN=http(s)://: If this is not set correctly, you may encounter CORS-related issues. -### Docker Compose Overview +## Docker Compose Overview Here's a minimal `docker-compose.yml` example with explanations: @@ -145,7 +134,7 @@ networks: driver: bridge ``` -### Networking +## Networking All services must be part of the same Docker network. This is handled by the default `wanderer` network in the configuration above. @@ -153,7 +142,7 @@ Make sure to set the `ORIGIN` environment variable to the full public URL (inclu > Cross-site POST form submissions are forbidden -### Volumes +## Volumes By default, two volumes are mounted: @@ -162,7 +151,7 @@ By default, two volumes are mounted: These can be changed to bind mounts or other volume strategies if needed. -### Environment +## Environment The default Docker configuration defines all necessary environment variables. You can extend or override them as needed. For advanced options, refer to the [environment configuration documentation](/run/environment-configuration). @@ -170,7 +159,7 @@ The default Docker configuration defines all necessary environment variables. Yo Ensure you replace the default `MEILI_MASTER_KEY` with a strong, unique value in production environments. Also, remember to set the `POCKETBASE_ENCRYPTION_KEY` to the key you generated [before](#prerequisites). ::: -### Updating +## Updating To update your instance to the latest version: @@ -181,110 +170,6 @@ docker compose up -d Always consult the [changelog](/changelog) before updating, in case of breaking changes. -## Installation from Source - -While not as convenient as Docker, you can also install wanderer from source. - -### Prerequisites - -1. Clone the repository: - -```bash -git clone https://github.com/Flomp/wanderer.git --branch v{version} --single-branch -``` -2. Install dependencies: - - **Go** ≥ 1.23.0 - - **Node.js** ≥ 18.17.0 - - **npm** ≥ 8.15.0 - -### meilisearch - -wanderer uses a standard Meilisearch binary. Download and install it according to your platform: - -https://www.meilisearch.com/docs/learn/getting_started/installation - -Place the binary in `wanderer/search`. If you choose a different location, update your scripts accordingly. - -### PocketBase - -wanderer uses a customized fork of PocketBase. You must build it before launching: - -```bash -cd wanderer/db -go mod tidy && go build -``` - -This will generate a `pocketbase` binary in the `wanderer/db` folder. - -### Web - -Build the frontend using: - -```bash -cd wanderer/web -npm ci --omit=dev -npm run build -``` - -You should see a `build/` directory in `wanderer/web`. - -If `vitest` is not installed, add it manually: - -```bash -npm i -s vitest -``` - -### Launch - -You can launch all three services using a shell script that sets environment variables and ensures proper startup order: - -```bash -trap "kill 0" EXIT - -# Required configuration -export ORIGIN=http://localhost:3000 -export MEILI_URL=http://127.0.0.1:7700 -export MEILI_MASTER_KEY=YOU_SHOULD_DEFINITELY_CHANGE_ME -export PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090 -export PUBLIC_VALHALLA_URL=https://valhalla1.openstreetmap.de -export POCKETBASE_ENCRYPTION_KEY=YOUR_ENCRYPTION_KEY_HERE - -# Optional configuration -# export MEILI_NO_ANALYTICS=true -# export BODY_SIZE_LIMIT=Infinity -# export PUBLIC_DISABLE_SIGNUP=false -# export UPLOAD_FOLDER=/app/uploads -# export UPLOAD_USER= -# export UPLOAD_PASSWORD= - -cd search && ./meilisearch --master-key $MEILI_MASTER_KEY & -cd db && ./pocketbase serve & -cd web && node build & - -wait -``` - -:::caution -Make sure you replace `MEILI_MASTER_KEY` with a secure value before going to production. Also, remember to set the `POCKETBASE_ENCRYPTION_KEY` to the key you generated [before](#prerequisites). -::: - -### Updating - -To update to the latest version stop the running application and run: - -```bash -git pull origin main - -cd wanderer/db -go mod tidy && go build - -cd wanderer/web -npm ci --omit=dev -npm run build -``` - -Then re-run the launch script. Always review the [changelog](/changelog) for breaking changes. - ## Verify the Installation Regardless of the installation method, once everything is running you should be able to access wanderer at: diff --git a/docs/src/content/docs/run/installation/from-source.mdx b/docs/src/content/docs/run/installation/from-source.mdx new file mode 100644 index 00000000..e19cf65d --- /dev/null +++ b/docs/src/content/docs/run/installation/from-source.mdx @@ -0,0 +1,116 @@ +--- +title: Installation from Source +description: For advanced users who want to build or customize wanderer. +--- + +You can install wanderer components either via Docker ([Quick Setup](./quick) or [Manual Setup](./docker)) or [from source](./installation-from-source). + +## Prerequisites + +1. Clone the repository: + +```bash +git clone https://github.com/Flomp/wanderer.git --branch v{version} --single-branch +``` +2. Install dependencies: + - **Go** ≥ 1.23.0 + - **Node.js** ≥ 18.17.0 + - **npm** ≥ 8.15.0 + +## meilisearch + +wanderer uses a standard Meilisearch binary. Download and install it according to your platform: + +https://www.meilisearch.com/docs/learn/getting_started/installation + +Place the binary in `wanderer/search`. If you choose a different location, update your scripts accordingly. + +## PocketBase + +wanderer uses a customized fork of PocketBase. You must build it before launching: + +```bash +cd wanderer/db +go mod tidy && go build +``` + +This will generate a `pocketbase` binary in the `wanderer/db` folder. + +## Web + +Build the frontend using: + +```bash +cd wanderer/web +npm ci --omit=dev +npm run build +``` + +You should see a `build/` directory in `wanderer/web`. + +If `vitest` is not installed, add it manually: + +```bash +npm i -s vitest +``` + +## Launch + +You can launch all three services using a shell script that sets environment variables and ensures proper startup order: + +```bash +trap "kill 0" EXIT + +# Required configuration +export ORIGIN=http://localhost:3000 +export MEILI_URL=http://127.0.0.1:7700 +export MEILI_MASTER_KEY=YOU_SHOULD_DEFINITELY_CHANGE_ME +export PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090 +export PUBLIC_VALHALLA_URL=https://valhalla1.openstreetmap.de +export POCKETBASE_ENCRYPTION_KEY=YOUR_ENCRYPTION_KEY_HERE + +# Optional configuration +# export MEILI_NO_ANALYTICS=true +# export BODY_SIZE_LIMIT=Infinity +# export PUBLIC_DISABLE_SIGNUP=false +# export UPLOAD_FOLDER=/app/uploads +# export UPLOAD_USER= +# export UPLOAD_PASSWORD= + +cd search && ./meilisearch --master-key $MEILI_MASTER_KEY & +cd db && ./pocketbase serve & +cd web && node build & + +wait +``` + +:::caution +Make sure you replace `MEILI_MASTER_KEY` with a secure value before going to production. Also, remember to set the `POCKETBASE_ENCRYPTION_KEY` to the key you generated [before](#prerequisites). +::: + +## Updating + +To update to the latest version stop the running application and run: + +```bash +git pull origin main + +cd wanderer/db +go mod tidy && go build + +cd wanderer/web +npm ci --omit=dev +npm run build +``` + +Then re-run the launch script. Always review the [changelog](/changelog) for breaking changes. + +## Verify the Installation + +Regardless of the installation method, once everything is running you should be able to access wanderer at: + +``` +http://localhost:3000 +``` + +If you see the UI and no errors in the logs, you're all set! diff --git a/docs/src/content/docs/run/installation/quick.mdx b/docs/src/content/docs/run/installation/quick.mdx new file mode 100644 index 00000000..518278be --- /dev/null +++ b/docs/src/content/docs/run/installation/quick.mdx @@ -0,0 +1,27 @@ +--- +title: Quickstart +description: The fastest way to try wanderer. Runs everything with Docker in just two commands. +--- + +You can install wanderer components either via Docker ([Quick Setup](./quick) or [Manual Setup](./docker)) or [from source](./installation-from-source). + +For a quick setup, you can run the following command in your terminal. +This will create a `docker-compose.yml` file and start the services. + +```bash +/bin/bash -c "$(curl -fsSL https://wanderer.to/setup.sh)" +docker compose up -d +``` + +After a few seconds, you should be able to access wanderer at [http://localhost:3000](http://localhost:3000) or your chosen domain. + +## Updating + +To update your instance to the latest version: + +```bash +docker compose pull +docker compose up -d +``` + +Always consult the [changelog](/changelog) before updating, in case of breaking changes.