# ngit-grasp Configuration # # Configuration Priority (highest to lowest): # 1. CLI flags (e.g., --domain example.com) # 2. Environment variables (e.g., NGIT_DOMAIN=example.com) # 3. This .env file # 4. Built-in defaults # # Run `ngit-grasp --help` for all CLI options # ============================================================================ # REQUIRED # ============================================================================ # Domain where this instance is hosted (required, used in GRASP validation) # CLI: --domain # No default - must be set # NGIT_DOMAIN= # ============================================================================ # SERVER CONFIGURATION # ============================================================================ # Server bind address (IP:PORT) # CLI: --bind-address
# Default: 127.0.0.1:7334 # NGIT_BIND_ADDRESS=127.0.0.1:7334 # ============================================================================ # RELAY INFORMATION (NIP-11) # ============================================================================ # Relay operator's nsec (private key) for signing and authentication # Used for: # - NIP-11 relay information document (pubkey field derived from this nsec) # - NIP-42 authentication when syncing from other relays # - Future: signing events, WoT-based rate limiting of syncing relays # # CLI: --relay-owner-nsec # Default: Loaded from/saved to .relay-owner.nsec file in current directory # If file doesn't exist, a new key is generated and saved automatically # NGIT_RELAY_OWNER_NSEC=nsec1... # Relay name shown in NIP-11 information document # CLI: --relay-name # Default: ${domain} grasp relay (e.g., "gitnostr.com grasp relay") # NGIT_RELAY_NAME=My GRASP Relay # Relay description shown in NIP-11 information document # CLI: --relay-description # Default: Git Nostr Relay - a grasp implementation # NGIT_RELAY_DESCRIPTION="A GRASP-compliant Git relay with Nostr authorization" # ============================================================================ # STORAGE # ============================================================================ # Path to store Git repositories # CLI: --git-data-path # Default: ./data/git # NGIT_GIT_DATA_PATH=./data/git # Path to store Nostr relay data # CLI: --relay-data-path # Default: ./data/relay # NGIT_RELAY_DATA_PATH=./data/relay # Database backend for Nostr events # CLI: --database-backend # Options: lmdb, memory, nostrdb # Default: lmdb # - lmdb: LMDB backend (persistent, general purpose) - RECOMMENDED # - memory: In-memory database (fastest, no persistence, uses temp dirs) # - nostrdb: NostrDB backend (persistent, Nostr-optimized) [Not yet implemented] # # Note: When using 'memory' backend, git_data_path and relay_data_path # are automatically set to temporary directories for ephemeral testing. # NGIT_DATABASE_BACKEND=lmdb # ============================================================================ # METRICS # ============================================================================ # Enable Prometheus metrics endpoint at /metrics # CLI: --metrics-enabled # Default: true # NGIT_METRICS_ENABLED=true # Connections per IP before flagging as potential abuse in metrics # (display only, no rate limiting - purely for monitoring visibility) # CLI: --metrics-connection-per-ip-abuse-threshold # Default: 10 # NGIT_METRICS_CONNECTION_PER_IP_ABUSE_THRESHOLD=10 # Number of top bandwidth repositories to track in metrics # CLI: --metrics-top-n-repos # Default: 10 # NGIT_METRICS_TOP_N_REPOS=10 # ============================================================================ # LOGGING # ============================================================================ # Log level for application logging # CLI: --log-level # Default: info # Options: error, warn, info, debug, trace # Can also use filter expressions: ngit_grasp=debug,actix_web=info # NGIT_LOG_LEVEL=info # ============================================================================ # PROACTIVE SYNC (GRASP-02) # ============================================================================ # Bootstrap relay URL for initial sync (optional) # Additional relays are automatically discovered from repository announcements # that list our service domain. # CLI: --sync-bootstrap-relay-url # Default: (none - relay discovery from stored announcements only) # NGIT_SYNC_BOOTSTRAP_RELAY_URL=wss://relay.example.com # Maximum backoff time in seconds for sync relay reconnection # CLI: --sync-max-backoff-secs # Default: 3600 (1 hour) # NGIT_SYNC_MAX_BACKOFF_SECS=3600 # Interval in seconds for checking disconnected relays and attempting reconnection # Set to lower value for faster reconnection testing # CLI: --sync-disconnect-check-interval-secs # Default: 60 # NGIT_SYNC_DISCONNECT_CHECK_INTERVAL_SECS=60 # Base backoff time in seconds for relay reconnection # Used for exponential backoff: base * 2^(failures-1) # Set to 1 for faster test cycles # Note: The connection timeout is capped at this value # CLI: --sync-base-backoff-secs # Default: 5 # NGIT_SYNC_BASE_BACKOFF_SECS=5 # Disable NIP-77 negentropy sync (use REQ+EOSE instead) # When enabled, sync will use REQ+EOSE instead of negentropy for history sync # Primarily useful for testing that sync works without negentropy support # CLI: --sync-disable-negentropy # Default: false # NGIT_SYNC_DISABLE_NEGENTROPY=false # ============================================================================ # REJECTED EVENTS INDEX # ============================================================================ # Hot cache duration in seconds for rejected announcements # Stores full event objects for immediate re-processing when dependencies resolve # Too short (<30s): Miss events from slow relays # Too long (>5min): Waste memory # CLI: --rejected-hot-cache-duration-secs # Default: 120 (2 minutes) # NGIT_REJECTED_HOT_CACHE_DURATION_SECS=120 # Cold index expiry in seconds for rejected announcements # Stores metadata only to prevent repeated downloads of rejected events # CLI: --rejected-cold-index-expiry-secs # Default: 604800 (7 days) # NGIT_REJECTED_COLD_INDEX_EXPIRY_SECS=604800 # Hours before removing relay from naughty list # Relays with persistent infrastructure issues (DNS, TLS, protocol errors) are # tracked separately and retried after this expiration period # CLI: --naughty-list-expiration-hours # Default: 12 # NGIT_NAUGHTY_LIST_EXPIRATION_HOURS=12 # ============================================================================ # GRASP-05 ARCHIVE MODE # ============================================================================ # Accept all repository announcements (⚠️ WARNING: Storage/bandwidth risk) # When enabled, any repository can be mirrored to this relay # CLI: --archive-all # Default: false # NGIT_ARCHIVE_ALL=false # Whitelist specific repos/pubkeys/identifiers for archiving # Comma-separated list supporting three formats: # - Archive all repos from this pubkey # / - Archive specific repo # - Archive repos with this identifier (any pubkey) # # CLI: --archive-whitelist # Default: (empty) # Examples: # NGIT_ARCHIVE_WHITELIST=npub1alice... # NGIT_ARCHIVE_WHITELIST=npub1alice...,npub1bob.../linux # NGIT_ARCHIVE_WHITELIST=bitcoin-core,linux,rust # NGIT_ARCHIVE_WHITELIST= # Archive GRASP services: comma-separated list of GRASP server domains to archive # Archives all repositories from the specified GRASP server domains # Must be bare domains only (e.g., git.example.com, NOT wss://git.example.com) # Mutually exclusive with NGIT_ARCHIVE_ALL and NGIT_ARCHIVE_WHITELIST # Automatically sets NGIT_ARCHIVE_READ_ONLY to true by default # CLI: --archive-grasp-services # Default: (empty) # Examples: # NGIT_ARCHIVE_GRASP_SERVICES=git.example.com # NGIT_ARCHIVE_GRASP_SERVICES=git.example.com,git.nostr.dev,relay.gitnostr.com # NGIT_ARCHIVE_GRASP_SERVICES= # Archive read-only mode (relay is read-only sync of archived repositories) # When true: # - NIP-11 includes GRASP-05 in supported_grasps # - NIP-11 curation field describes archive scope # - Repository announcements not listing this service are accepted per whitelist/archive-all # When false: # - Archive mode disabled (standard GRASP-01 operation) # # CLI: --archive-read-only # Default: true if NGIT_ARCHIVE_ALL, NGIT_ARCHIVE_WHITELIST, or NGIT_ARCHIVE_GRASP_SERVICES is set, false otherwise # Note: Setting to true without archive config causes startup error # Note: Cannot be used with NGIT_REPOSITORY_WHITELIST (mutually exclusive) # NGIT_ARCHIVE_READ_ONLY= # ============================================================================ # REPOSITORY WHITELIST # ============================================================================ # Whitelist specific repos/pubkeys/identifiers for GRASP-01 acceptance # Comma-separated list supporting three formats (same as archive whitelist): # - Accept all repos from this pubkey (if they list our service) # / - Accept specific repo (if it lists our service) # - Accept repos with this identifier (if they list our service) # # Difference from archive whitelist: # - Repository whitelist: Announcements MUST list our service AND match whitelist # - Archive whitelist: Announcements don't need to list our service, just match whitelist # # CLI: --repository-whitelist # Default: (empty - all repos listing our service are accepted) # Examples: # NGIT_REPOSITORY_WHITELIST=npub1alice... # NGIT_REPOSITORY_WHITELIST=npub1alice...,npub1bob.../linux # NGIT_REPOSITORY_WHITELIST=bitcoin-core,linux,rust # Note: Cannot be used with NGIT_ARCHIVE_READ_ONLY=true (mutually exclusive) # Note: When set, NIP-11 curation field will indicate curated repository acceptance # NGIT_REPOSITORY_WHITELIST= # ============================================================================ # REPOSITORY BLACKLIST # ============================================================================ # Blacklist specific repos/pubkeys/identifiers to reject # Comma-separated list supporting three formats (same as whitelist formats): # - Block all repos from this pubkey # / - Block specific repo # - Block repos with this identifier (any pubkey) # # Blacklist takes precedence over ALL whitelists: # - Blacklisted repos are rejected even if they match archive or repository whitelists # - Blacklisted repos are rejected even if they list our service # # Rejection reasons indicate the match type: # - "Repository owner is blacklisted" (npub format) # - "Repository / is blacklisted" (npub/identifier format) # - "Repository identifier is blacklisted" (identifier format) # # CLI: --repository-blacklist # Default: (empty - no repositories are blacklisted) # Examples: # NGIT_REPOSITORY_BLACKLIST=npub1spam... # NGIT_REPOSITORY_BLACKLIST=npub1alice.../bad-repo # NGIT_REPOSITORY_BLACKLIST=malware-repo,spam-repo # NGIT_REPOSITORY_BLACKLIST= # ============================================================================ # EVENT BLACKLIST # ============================================================================ # Blacklist events from specific authors (npubs) # Comma-separated list of npubs whose events are rejected # ALL events from these authors are blocked from both relay storage and purgatory # # Event blacklist takes precedence over ALL other validation: # - Blacklisted events are rejected before any other policy checks # - Applies to announcements, state events, PRs, and all other event types # - Events never reach purgatory (rejected immediately) # # Rejection reason: # - "Event author is blacklisted" # # CLI: --event-blacklist # Default: (empty - no events are blacklisted by author) # Examples: # NGIT_EVENT_BLACKLIST=npub1spam... # NGIT_EVENT_BLACKLIST=npub1spam...,npub1abuser... # NGIT_EVENT_BLACKLIST= # ============================================================================ # RATE LIMITING & DOS PROTECTION # ============================================================================ # Maximum total connections to the relay # Prevents connection exhaustion DoS attacks # CLI: --max-connections # Default: 4096 # NGIT_MAX_CONNECTIONS=4096