Gramps Web

https://www.grampsweb.org
Admin
Gramps Web is a free, open-source genealogy system for building and collaborating on family trees...
Tokens:21,467
Snippets:388
Trust Score:8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install jq on Ubuntu

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

Install jq on Ubuntu systems using apt.

```bash
sudo apt install jq

```

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

### Initiate OIDC Login for Multi-Tree Setup

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

Use this endpoint to start the OIDC login process on a multi-tree server, specifying the provider and the target tree ID.

```http
GET /api/oidc/login/?provider=<id>&tree=<tree_id>
```

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

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

```

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

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

```

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

### Configure Multiple OIDC Providers

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

Example showing how to enable multiple OIDC providers simultaneously by combining their respective configuration variables.

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

# Microsoft OAuth
OIDC_MICROSOFT_CLIENT_ID="your-microsoft-client-id"
OIDC_MICROSOFT_CLIENT_SECRET="your-microsoft-client-secret"
```

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

### Configure Mistral AI via Docker Compose

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

Example environment variable configuration for using Mistral AI models within a Docker Compose setup.

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

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

### 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"

```

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

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

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

### Install Gramps Web API AI dependencies

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

Use this command to install the necessary libraries for AI chat functionality when using pip.

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

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

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


```

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

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

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

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

```

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

### 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/

```

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

### Configure Custom OIDC Provider (Keycloak)

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

Environment variables for setting up a custom OIDC provider, including optional role mapping and email configuration.

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

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

### Configure Built-in Google Provider

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

Minimal configuration required to enable Google OAuth authentication.

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

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

### 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 = "*"

```

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

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

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

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

```

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

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

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

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

```

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

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

```

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

### Minimal Production Configuration

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

Defines essential environment variables for a production deployment of Gramps Web.

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

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

### 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')

```

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

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

```

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

### Mounting a configuration file in Docker Compose

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

Add this volume mapping to the grampsweb service block to link a local configuration file to the container.

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

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

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

```

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

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

```

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

### Generating a secure secret key

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

Use this command to generate a cryptographically secure secret key for the Flask application.

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

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

### 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)
```
Tokens:
Raw