### Install jq on Ubuntu

Source: https://www.grampsweb.org/development/backend/queries

Install jq on Ubuntu systems using apt.

```bash
sudo apt install jq

```

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

### Run Gramps Web Locally with Docker

Source: https://www.grampsweb.org/install_setup/quickstart

Starts a new, empty Gramps Web instance accessible at http://localhost:5055. This setup is suitable for initial testing but may time out when importing large files.

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

```

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

### Install boto3 Python Library

Source: https://www.grampsweb.org/install_setup/s3

Install the boto3 library, which is required by the S3 Media Uploader Addon. Run this command in your terminal.

```bash
python3 -m pip install boto3

```

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

### Install HTTPie

Source: https://www.grampsweb.org/development/backend/queries

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

```bash
python3 -m pip install httpie

```

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

### Start Gramps Web Server with Docker Compose

Source: https://www.grampsweb.org/install_setup/deployment

Run this command in your terminal to start the Gramps Web server in detached mode. The first run will initiate a wizard for account creation, configuration, and initial data import.

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

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

### Gramps Web System Information Example

Source: https://www.grampsweb.org/help/help

This is an example of the system information you should copy and paste when reporting an issue. Obtain it from the 'System information' tab on the Settings page.

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


```

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

### Run S3 Media Uploader Addon

Source: https://www.grampsweb.org/install_setup/s3

Start the S3 Media Uploader Addon from the command line. Replace placeholders with your family tree name and S3 bucket name. The addon will attempt to create the bucket if it doesn't exist.

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

```

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

### Example Gramps Web Production Configuration

Source: https://www.grampsweb.org/install_setup/configuration

A minimal configuration file for a production environment. Ensure sensitive information like SECRET_KEY and EMAIL_HOST_PASSWORD are kept secure.

```ini
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"

```

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

### Multiple OIDC Providers Configuration

Source: https://www.grampsweb.org/install_setup/oidc

Enable multiple OIDC providers simultaneously by configuring each provider's specific settings. This example shows custom, Google, and GitHub providers.

```ini
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"

```

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

### Enable Debug Logging for Gramps

Source: https://www.grampsweb.org/administration/sync

Start Gramps from the command line with the --debug option to enable detailed logging for troubleshooting sync issues.

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

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

### Install AI Chat Dependencies

Source: https://www.grampsweb.org/install_setup/chat

Install the necessary dependencies for AI chat functionality when installing Gramps Web API via pip. This command ensures that Sentence Transformers and PyTorch are included.

```bash
pip install gramps_webapi[ai]

```

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

### Run Gramps Web with Media Folder Mount

Source: https://www.grampsweb.org/install_setup/quickstart

Runs Gramps Web locally and mounts a local directory to the container's media folder, allowing access to media files from your computer. Note that database changes are not persisted with this setup.

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

```

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

### Configure Mistral AI with Docker Compose

Source: https://www.grampsweb.org/install_setup/chat

Example configuration for using Mistral AI models via Docker Compose. Ensure you set the correct model name and 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
```

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

### Mount Configuration File in Docker Compose

Source: https://www.grampsweb.org/install_setup/configuration

Include a configuration file in your Docker Compose setup by adding this volume mount to the 'grampsweb' block. Ensure the path on the right-hand side is '/app/config/config.cfg'.

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

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

### User Database URI for Shared PostgreSQL

Source: https://www.grampsweb.org/install_setup/postgres

Configure the `USER_DB_URI` option to use a PostgreSQL database for storing user information. This example uses the `grampswebuser` database provided by the `gramps-postgres` image.

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

```

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

### Make Authenticated API Request

Source: https://www.grampsweb.org/development/backend/queries

Use the stored access token to make an authenticated GET request to the `/api/metadata/` endpoint. The `-A bearer` flag specifies bearer token authentication.

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

```

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

### Import Gramps Family Tree via Docker Compose

Source: https://www.grampsweb.org/install_setup/postgres

Use this command to import a Gramps XML file into a PostgreSQL database when running Gramps Web via Docker Compose. Ensure the file path and database connection details 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

```

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

### Enable Multi-Tree Support

Source: https://www.grampsweb.org/install_setup/multi-tree

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 for separate media file storage.

```ini
TREE = "*"

```

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

### Configure Gramps Web with S3

Source: https://www.grampsweb.org/install_setup/s3

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

```ini
MEDIA_BASE_DIR: s3://my_bucket_name

```

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

### Telemetry Data Payload Example

Source: https://www.grampsweb.org/install_setup/telemetry

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

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

```

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

### Get User Permissions

Source: https://www.grampsweb.org/development/frontend/architecture

The getPermissions function retrieves the user's authorization scope from the access token claims. This is used to conditionally enable/disable features based on user roles.

```javascript
getPermissions
```

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

### Basic config.js Structure

Source: https://www.grampsweb.org/install_setup/frontend-config

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

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

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

### Set up Ollama Service with Docker Compose

Source: https://www.grampsweb.org/install_setup/chat

Configuration for running an Ollama service locally using Docker Compose. This allows Gramps Web to connect to a local LLM.

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

volumes:
    ollama_data:
```

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

### Check Available Memory with free

Source: https://www.grampsweb.org/install_setup/cpu-limited

Use this command on Linux to view the amount of free and used memory and swap space on your system. This helps in understanding memory constraints.

```bash
free -h

```

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

### Configure Python Keyring for Gnome

Source: https://www.grampsweb.org/administration/sync

This configuration file is needed for Python keyring to work correctly on many Gnome desktop environments, addressing a known bug.

```ini
[backend]
default-keyring=keyring.backends.SecretService.Keyring

```

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

### Fetch Access Token

Source: https://www.grampsweb.org/development/backend/queries

Query the token endpoint to obtain an access token for API authentication. Replace `localhost:5555` with your development instance address if different.

```bash
http POST http://localhost:5555/api/token/ username=owner password=owner

```

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

### Store Access Token in Environment Variable

Source: https://www.grampsweb.org/development/backend/queries

Fetch an access token and store it in the `ACCESS_TOKEN` environment variable using jq for subsequent authenticated API calls. Access tokens expire after 15 minutes.

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

```

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

### Built-in Provider Configuration (Google)

Source: https://www.grampsweb.org/install_setup/oidc

Configure Gramps Web to use Google as an OIDC provider. Set the Google client ID and client secret.

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

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

```

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

### Run Gramps Web User Management Command

Source: https://www.grampsweb.org/install_setup/users

Use this command to manage users when using Docker Compose. Replace COMMAND with 'add' or 'delete' and [ARGS] with specific arguments. Use --help for detailed options.

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

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

### Configure Web API for PostgreSQL

Source: https://www.grampsweb.org/install_setup/postgres

Add these environment variables to the `grampsweb` service in your `docker-compose.yml` to connect the Web API to the PostgreSQL database. The tree name defaults to the database name, and credentials must match the PostgreSQL container.

```yaml
      # the PostgreSQL addon assumes the tree name to be
      # equal to the database name and here the default
      # database name of the PostgreSQL image is used
      TREE: postgres
      # The credentials must agree with the ones used for
      # the PostgreSQL container
      POSTGRES_USER: gramps
      POSTGRES_PASSWORD: postgres_password_gramps

```

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

### List Available Trees

Source: https://www.grampsweb.org/install_setup/multi-tree

Use this command to list the names and IDs of existing trees in the Gramps database directory.

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

```

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

### Monitor Gramps Web and PostgreSQL Logs

Source: https://www.grampsweb.org/install_setup/postgres

Use these Docker Compose commands to view the log output for Gramps Web and the PostgreSQL server. This is essential for diagnosing issues.

```bash
docker compose logs grampsweb
```

```bash
docker compose logs postgres_grampsweb
```

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

### Docker Compose for PostgreSQL Server

Source: https://www.grampsweb.org/install_setup/postgres

Configure your docker-compose.yml to run a PostgreSQL server using the gramps-postgres image. This image includes necessary locales for Gramps and sets up separate 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

```

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

### Custom OIDC Provider Configuration (Keycloak)

Source: https://www.grampsweb.org/install_setup/oidc

Configure Gramps Web to use a custom OIDC provider, such as Keycloak. Set OIDC_ENABLED to True and provide issuer, client ID, and secret. Optional settings include auto-redirect, disabling local auth, and role mapping.

```ini
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"

```

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

### Docker Compose Configuration for Gramps Web

Source: https://www.grampsweb.org/install_setup/deployment

Create this file to configure and deploy Gramps Web using Docker Compose. It sets up six named volumes for data persistence. Warning: This configuration exposes the API on port 80 without SSL/TLS, making it insecure for public internet access.

```yaml
version: "3.8"
services:
  grampsweb:
    image: "grampsweb/grampsweb:latest"
    container_name: "grampsweb"
    ports:
      - "80:80"
    volumes:
      - gramps_config:/app/config
      - gramps_media:/app/media
      - gramps_database:/app/database
      - gramps_logs:/app/logs
      - gramps_sessions:/app/sessions
      - gramps_thumbnails:/app/thumbnails
volumes:
  gramps_config:
  gramps_media:
  gramps_database:
  gramps_logs:
  gramps_sessions:
  gramps_thumbnails:

```

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

### Update Gramps Web with Docker Compose

Source: https://www.grampsweb.org/install_setup/update

Run these commands in the folder containing your docker-compose.yml file to update to the latest version. Always check release notes for potential breaking changes.

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

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

### View Gramps Web Server Logs (Docker)

Source: https://www.grampsweb.org/administration/sync

Retrieve the latest 100 lines of logs from the Gramps Web and Gramps Web Celery containers when using Docker for debugging.

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

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

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

### Configure S3-Compatible Storage

Source: https://www.grampsweb.org/install_setup/s3

To use an S3-compatible object storage service other than AWS, set the AWS_ENDPOINT_URL environment variable. This is useful for services like GCP or for local testing.

```bash
export AWS_ENDPOINT_URL=your_endpoint_url

```

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

### Assign Users to a Specific Tree

Source: https://www.grampsweb.org/install_setup/multi-tree

Use this command to assign existing users to a specific tree when enabling multi-tree support. Replace TREE_ID with the actual ID of the target tree.

```python
python -m gramps_webapi --config /app/config/config.cfg user fill-tree TREE_ID

```

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

### Export AWS Credentials

Source: https://www.grampsweb.org/install_setup/s3

Set your AWS access key ID and secret access key as environment variables. These are required for authentication with AWS S3.

```bash
export AWS_ACCESS_KEY_ID=my_access_key_id
export AWS_SECRET_ACCESS_KEY=my_secret_access_key

```

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

### Define a Web Component

Source: https://www.grampsweb.org/development/frontend/architecture

This is the standard way to define a new custom HTML element using LitElement. Ensure the class extends LitElement and is registered with customElements.define.

```javascript
class GrampsjsSomeElement extends LitElement
```

```javascript
customElements.define('grampsjs-some-element', GrampsjsSomeElement)
```

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

### Check CPU Cores with lscpu

Source: https://www.grampsweb.org/install_setup/cpu-limited

Use this command on Linux to determine the number of CPU cores available on your system. This information can help in deciding the optimal number of workers.

```bash
lscpu | grep CPU

```

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

### Filter Objects by Media Reference Count

Source: https://www.grampsweb.org/user-guide/gql

This query selects objects that have a minimum number of media references associated with them.

```GQL
media_list.length >= 10
```

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

### Docker Compose Environment Variables for S3

Source: https://www.grampsweb.org/install_setup/s3

When using Docker Compose, define S3 credentials and the media base directory in the environment block. Include AWS_DEFAULT_REGION for your S3 bucket's region.

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

```

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

### API Data Exchange Methods

Source: https://www.grampsweb.org/development/frontend/architecture

These methods in src/api.js handle communication with the backend API, including automatic authentication. Use apiGet for retrieval, apiPut for updates, and apiPost for creating new data.

```javascript
apiGet
```

```javascript
apiPut
```

```javascript
apiPost
```

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

### Generate a Secure Secret Key

Source: https://www.grampsweb.org/install_setup/configuration

Use this Python command to generate a secure, random secret key for Flask. This key is essential for security and should not be shared publicly.

```python
python3 -c "import secrets;print(secrets.token_urlsafe(32))"
```

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

### Search Index Database URI for PostgreSQL

Source: https://www.grampsweb.org/install_setup/postgres

Set the `SEARCH_INDEX_DB_URI` configuration option to use a PostgreSQL database for the search index. This allows the search index to coexist with genealogical data in the same database.

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

```

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

### Enter DNA Match Data

Source: https://www.grampsweb.org/user-guide/dna-matches

Paste raw DNA match data as a comma or tab-separated table. Ensure columns include chromosome number, start/end location, centimorgans, and SNPs.

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

```