### Install Dependencies and Serve Documentation

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/AGENTS.md

Installs project dependencies using pip and starts a local live-reloading preview of the MkDocs site. It's recommended to use a virtual environment for installation.

```bash
python -m pip install -r requirements.txt   # ideally in a virtualenv
mkdocs serve -a localhost:8211 -o           # live-reloading preview
```

--------------------------------

### Install jq on Ubuntu

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/development/backend/queries.md

Install the jq command-line JSON processor on Ubuntu systems.

```bash
sudo apt install jq
```

--------------------------------

### Run Gramps Web Locally with Docker

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/quickstart.md

Use this command to start a new, empty Gramps Web instance accessible at http://localhost:5055. This setup is suitable for initial testing.

```bash
docker run -p "5055:5000" -e TREE=new ghcr.io/gramps-project/grampsweb:latest
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/README.md

Installs the required Python dependencies for serving the documentation locally. It is recommended to do this within a virtual environment.

```bash
python -m pip install -r requirements.txt
```

--------------------------------

### Run MkDocs Development Server

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/CONTRIBUTING.md

Start the local development server to preview your changes. The server automatically reloads when Markdown files are modified.

```bash
python -m mkdocs serve -a localhost:8211
```

--------------------------------

### Install boto3 Python Library

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/s3.md

Install the boto3 library required for S3 integration. This is a prerequisite for using the S3 Media Uploader Addon.

```bash
python3 -m pip install boto3
```

--------------------------------

### Install HTTPie

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/development/backend/queries.md

Install HTTPie using pip. Ensure you are using version 3.0.0 or newer.

```bash
python3 -m pip install httpie
```

--------------------------------

### Gramps Web System Information

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/help/help.md

This is an example of the system information you should copy and paste when reporting an issue. It helps developers understand your setup and version details.

```text
Gramps 5.1.6
Gramps Web API 1.5.1
Gramps.js 24.1.0
locale: en
multi-tree: false
task queue: true
```

--------------------------------

### Install Gramps Web API with AI dependencies

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/chat.md

Install the Gramps Web API with AI capabilities using pip. This command installs the necessary libraries for AI chat functionality.

```bash
pip install gramps_webapi[ai]
```

--------------------------------

### Run S3 Media Uploader Addon

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/s3.md

Start the S3 Media Uploader Addon to upload existing media files to your S3 bucket. Replace placeholders with your family tree name and bucket name.

```bash
gramps -O "My Family Tree" -a tool \
    -p "name=s3uploader,bucket_name=my_bucket_name"
```

--------------------------------

### Build Gramps Web Snapshot with Packer

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/examples/digitalocean-1click/README.md

Use this command to build the Gramps Web DigitalOcean 1-click app snapshot using Packer. Ensure you have Packer installed and configured.

```bash
packer build grampsweb.json
```

--------------------------------

### User Database URI for Shared PostgreSQL

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/postgres.md

This is an example of a database URL to configure the user database to use a PostgreSQL instance. It specifies the user, password, host, port, and database name for the user database.

```string
postgresql://grampswebuser:postgres_password_gramps_user@postgres_gramps:5432/grampswebuser
```

--------------------------------

### Start Gramps Web Server with Docker Compose

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/deployment.md

Command to start the Gramps Web server in detached mode using Docker Compose. This command should be run in the directory containing your docker-compose.yml file.

```bash
docker compose up -d
```

--------------------------------

### Docker Compose Configuration for Mistral AI

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/chat.md

Example configuration for using Mistral AI with Gramps Web via Docker Compose. Ensure to replace 'your-mistral-api-key-here' with your actual API key.

```yaml
environment:
  GRAMPSWEB_LLM_MODEL: mistral:mistral-large-latest
  MISTRAL_API_KEY: your-mistral-api-key-here
  GRAMPSWEB_VECTOR_EMBEDDING_MODEL: sentence-transformers/distiluse-base-multilingual-cased-v2
```

--------------------------------

### Enable Debug Logging for Sync

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/administration/sync.md

Start Gramps from the command line with the debug option to enable detailed logging for the Gramps Web Sync Addon. This helps in identifying the root cause of issues.

```bash
gramps --debug grampswebsync
```

--------------------------------

### Configure PostgreSQL Connection String

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/postgres.md

Set the SEARCH_INDEX_DB_URI configuration option to this value to connect Gramps Web to a PostgreSQL database for the search index. Ensure the credentials and host details are correct for your setup.

```text
postgresql://gramps:postgres_password_gramps@postgres_gramps:5432/gramps
```

--------------------------------

### Mount Configuration File in Docker Compose

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/configuration.md

Include a configuration file in your Docker Compose setup by adding a volume mount to the grampsweb service. Ensure the path inside the container remains '/app/config/config.cfg'.

```yaml
      - /path/to/config.cfg:/app/config/config.cfg
```

--------------------------------

### Docker Compose Service for Ollama

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/chat.md

Configuration for adding an Ollama service to your Docker Compose setup for running LLMs locally. This includes setting up the service image, container name, port mapping, and data volume.

```yaml
services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

volumes:
    ollama_data:
```

--------------------------------

### CSV format for DNA match data

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/user-guide/dna-matches.md

This is a minimal example of the expected CSV format for raw DNA match data. Ensure your data includes these columns: Chromosome, Start Location, End Location, Centimorgans, and SNPs.

```csv
Chromosome,Start Location,End Location,Centimorgans,SNPs
6,6358001,18115715,19.6,7424
7,150135758,154205894,10.9,2816
```

--------------------------------

### Check available memory with free

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/cpu-limited.md

Use this command to view the amount of memory and swap space currently available on your system.

```bash
free -h
```

--------------------------------

### Enable Multi-Tree Support

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/multi-tree.md

Set the TREE configuration option to '*' to enable access to all trees in the server's Gramps database directory. Ensure MEDIA_PREFIX_TREE is set to True to maintain media file separation.

```python
TREE = "*"
```

--------------------------------

### Minimal Production Configuration

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/configuration.md

A basic configuration file suitable for production environments. Ensure sensitive values like SECRET_KEY and EMAIL_HOST_PASSWORD are kept secure.

```python
TREE="My Family Tree"
BASE_URL="https://mytree.example.com"
SECRET_KEY="..."  # your secret key
USER_DB_URI="sqlite:////path/to/users.sqlite"
EMAIL_HOST="mail.example.com"
EMAIL_PORT=465
EMAIL_USE_SSL=True  # Use implicit SSL for port 465
EMAIL_HOST_USER="gramps@example.com"
EMAIL_HOST_PASSWORD="..." # your SMTP password
DEFAULT_FROM_EMAIL="gramps@example.com"
```

--------------------------------

### Telemetry Data Payload Example

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/telemetry.md

This JSON payload represents the anonymized telemetry data sent by Gramps Web. It includes unique identifiers for the server and tree, along with a timestamp.

```json
{
  "server_uuid": "c04325bfa7ae4578bcf134ec8fc046a7",
  "tree_uuid": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "timestamp": 1701234567,
}
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/README.md

Serves the Gramps Web documentation locally and opens it in the browser. The documentation will be available at localhost on port 8211.

```bash
mkdocs serve -a localhost:8211 -o
```

--------------------------------

### Basic Frontend Configuration Structure

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/frontend-config.md

This is the basic structure for the `config.js` file. All configuration options should be placed within the `window.grampsjsConfig` object.

```javascript
window.grampsjsConfig = {
    option: value
}
```

--------------------------------

### Make Authenticated API Call

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/development/backend/queries.md

Make a GET request to the metadata endpoint using the stored bearer token for authentication. Access tokens typically expire after 15 minutes.

```bash
http -A bearer -a $ACCESS_TOKEN GET http://localhost:5555/api/metadata/
```

--------------------------------

### Docker Logs for Gramps Web

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/administration/sync.md

Retrieve the latest log entries for the Gramps Web and Gramps Web Celery services when using Docker. This is useful for diagnosing issues with self-hosted installations.

```bash
docker compose logs --tail 100 grampsweb
```

```bash
docker compose logs --tail 100 grampsweb-celery
```

--------------------------------

### Manage Users via Command Line

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/users.md

Use this command to add or delete users when using Docker Compose. Refer to --help for available arguments.

```bash
docker compose run grampsweb python3 -m gramps_webapi user COMMAND [ARGS]
```

--------------------------------

### Configure Gramps Web with S3

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/s3.md

Set the MEDIA_BASE_DIR configuration option to point to your S3 bucket. This tells Gramps Web where to find media files.

```yaml
env:
  AWS_ACCESS_KEY_ID: my_access_key_id
  AWS_SECRET_ACCESS_KEY: my_secret_access_key
  MEDIA_BASE_DIR: s3://my_bucket_name
  AWS_DEFAULT_REGION: eu-central-1
```

--------------------------------

### Import Gramps XML to PostgreSQL via Docker

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/postgres.md

Use this command to import a Gramps XML file into a PostgreSQL database when running Gramps Web via Docker Compose. Ensure the paths and credentials match your setup.

```bash
docker compose run --entrypoint "" grampsweb \
    gramps -C postgres \
    -i /root/.gramps/grampsdb/my_tree.gramps \
    --config=database.path:/root/.gramps/grampsdb \
    --config=database.backend:postgresql \
    --config=database.host:postgres_gramps \
    --config=database.port:5432 \
    --username=gramps --password=postgres_password_gramps
```

--------------------------------

### Multiple OIDC Providers Configuration

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/oidc.md

Enable multiple OIDC providers simultaneously by configuring each provider's credentials and settings.

```python
TREE="My Family Tree"
BASE_URL="https://mytree.example.com"
SECRET_KEY="..."  # your secret key
USER_DB_URI="sqlite:////path/to/users.sqlite"

# Custom provider
OIDC_ENABLED=True
OIDC_ISSUER="https://auth.example.com/realms/myrealm"
OIDC_CLIENT_ID="gramps-web"
OIDC_CLIENT_SECRET="your-client-secret"
OIDC_NAME="Company SSO"

# Google OAuth
OIDC_GOOGLE_CLIENT_ID="your-google-client-id"
OIDC_GOOGLE_CLIENT_SECRET="your-google-client-secret"

# GitHub OAuth
OIDC_GITHUB_CLIENT_ID="your-github-client-id"
OIDC_GITHUB_CLIENT_SECRET="your-github-client-secret"
```

--------------------------------

### Run Gramps Web with Mounted Media Folder

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/quickstart.md

Mount your local Gramps media folder into the Docker container to use media files. Note that this does not persist database changes across restarts.

```bash
docker run -p "5055:5000" -e TREE=new \
  -v /path/to/my/gramps_media_folder:/app/media \
  ghcr.io/gramps-project/grampsweb:latest
```

--------------------------------

### Monitor Docker Logs for Gramps Web and PostgreSQL

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/postgres.md

Use these commands to view the log output for the Gramps Web and PostgreSQL containers when troubleshooting issues. This helps in identifying errors or understanding the current state of the services.

```bash
docker compose logs grampsweb
```

```bash
docker compose logs postgres_grampsweb
```

--------------------------------

### List Available Trees

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/multi-tree.md

Use this command to list all accessible Gramps trees and their IDs from the server's database directory.

```bash
python -m gramps_webapi --config /app/config/config.cfg tree list
```

--------------------------------

### Custom OIDC Provider Configuration (Keycloak)

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/oidc.md

Configure Gramps Web to use a custom OIDC provider like Keycloak. Includes basic settings, scopes, and optional role mapping.

```python
TREE="My Family Tree"
BASE_URL="https://mytree.example.com"
SECRET_KEY="..."  # your secret key
USER_DB_URI="sqlite:////path/to/users.sqlite"

# Custom OIDC Configuration
OIDC_ENABLED=True
OIDC_ISSUER="https://auth.example.com/realms/myrealm"
OIDC_CLIENT_ID="gramps-web"
OIDC_CLIENT_SECRET="your-client-secret"
OIDC_NAME="Family SSO"
OIDC_SCOPES="openid email profile"
OIDC_AUTO_REDIRECT=True  # Optional: automatically redirect to SSO login
OIDC_DISABLE_LOCAL_AUTH=True  # Optional: disable username/password login

# Optional: Role mapping from OIDC groups to Gramps roles
OIDC_ROLE_CLAIM="groups"  # or "roles" depending on your provider
OIDC_GROUP_ADMIN="gramps-admins"
OIDC_GROUP_EDITOR="gramps-editors"
OIDC_GROUP_MEMBER="gramps-members"

EMAIL_HOST="mail.example.com"
EMAIL_PORT=465
EMAIL_USE_TLS=True
EMAIL_HOST_USER="gramps@example.com"
EMAIL_HOST_PASSWORD="..." # your SMTP password
DEFAULT_FROM_EMAIL="gramps@example.com"
```

--------------------------------

### Translate Content with OpenAI API

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/CONTRIBUTING.md

Use this script to translate specific files or all files in the project. Ensure your OpenAI API key is set in the .env file.

```bash
cp .env.example .env
# Add your API key to .env
```

```bash
# Translate specific file
python translate.py --file user-guide/blog.md --lang de
```

```bash
# Translate all files
python translate.py --lang all
```

--------------------------------

### Store Access Token in Environment Variable

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/development/backend/queries.md

Fetch an access token and store it in the ACCESS_TOKEN environment variable using jq for parsing. This token can then be used for subsequent authenticated API requests.

```bash
export ACCESS_TOKEN=$(http POST http://localhost:5555/api/token/ \
  username=owner password=owner | jq -r '.access_token')
```

--------------------------------

### Run Translation Script

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/CONTRIBUTING.md

Execute the `translate.py` script with the `--lang` argument to generate translations for a specified language.

```bash
python translate.py --lang es
```

--------------------------------

### Docker Compose for PostgreSQL Server

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/postgres.md

Configure your docker-compose.yml to run a PostgreSQL server using the specialized gramps-postgres image. This image includes necessary locales for Gramps and separates databases for genealogical data and user authentication.

```yaml
  postgres_gramps:
    image: ghcr.io/davidmstraub/gramps-postgres:latest
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: postgres_password_admin
      POSTGRES_PASSWORD_GRAMPS: postgres_password_gramps
      POSTGRES_PASSWORD_GRAMPS_USER: postgres_password_gramps_user
    volumes:
      - postgres_data:/var/lib/postgresql/data
```

--------------------------------

### Filter Objects by Media Reference Count

Source: https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/user-guide/gql.md

Retrieves objects of any class that have a minimum number of media references.

```sql
media_list.length >= 10
```