Configuration Guide

This guide explains every configuration option in /config/project.config.yaml - the ONLY file you need to edit to customize your Nodes Map.

After editing config: Configuration is loaded at server startup. Restart the web container to apply changes:

docker restart atlasp2p-web

For developers adding new config fields: See the comprehensive developer guide in packages/config/README.md for:

Table of Contents

  1. Project Identity
  2. Chain Configuration
  3. Theme & Branding
  4. Content Configuration
  5. Map Configuration
  6. Feature Flags
  7. Asset Paths
  8. Environment Variables

Project Identity

projectName: YourCoin Nodes Map
chain: yourcoin

projectName (string)

chain (string, lowercase)

Chain Configuration

chainConfig:
  name: YourCoin
  ticker: YOUR
  p2pPort: 8333
  rpcPort: 8332
  protocolVersion: 70015
  currentVersion: "1.0.0"
  minimumVersion: "0.9.0"
  criticalVersion: "0.8.0"
  explorerUrl: https://explorer.yourcoin.org
  websiteUrl: https://yourcoin.org
  githubUrl: https://github.com/yourcoin/yourcoin

name (string)

ticker (string)

p2pPort (integer)

rpcPort (integer)

protocolVersion (integer)

currentVersion (string)

minimumVersion (string)

criticalVersion (string)

explorerUrl (string, URL)

websiteUrl (string, URL)

githubUrl (string, URL)

messagePrefix (string, optional)

addressPrefix (string, optional)

pubKeyHash (string, hex, optional)

Theme & Branding

themeConfig:
  name: YourCoin Nodes Map
  primaryColor: "#ff8c00"
  secondaryColor: "#ffa500"
  accentColor: "#ffb347"
  logo: /logos/logo.png
  favicon: /logos/favicon.ico

name (string)

primaryColor (string, hex color)

secondaryColor (string, hex color)

accentColor (string, hex color)

logo (string, path)

favicon (string, path)

Pro Tip: Use RealFaviconGenerator to create multi-platform favicons from your logo.

See Also: apps/web/public/logos/README.md for complete logo guidelines and template files.

Content Configuration

content:
  siteName: YourCoin Nodes Map
  siteDescription: Real-time map and analytics for YourCoin network nodes worldwide
  siteUrl: https://nodes.example.com

  navigation:
    - name: Map
      href: /
      icon: map
    - name: Statistics
      href: /stats
      icon: barchart
    - name: Leaderboard
      href: /leaderboard
      icon: trophy

  footerLinks:
    - label: API
      href: /api-docs
      external: false

  social:
    - name: GitHub
      href: https://github.com/yourcoin/yourcoin
      icon: github
    - name: Twitter
      href: https://twitter.com/yourcoin
      icon: twitter
    - name: Discord
      href: https://discord.gg/yourcoin
      icon: discord

  copyrightText: Open source project
  githubRepoUrl: https://github.com/RaxTzu/AtlasP2P

siteName (string)

siteDescription (string)

siteUrl (string, URL)

Navigation menu items in the header

Object structure:

- name: Map              # Display text
  href: /               # URL path or full URL
  icon: map             # Icon identifier
  external: false       # Optional: opens in new tab

Available icons:

Middle section links in footer

Object structure:

- label: API            # Link text
  href: /api-docs       # URL
  external: false       # Optional: true for external links

social (array of objects)

Social media icons in footer

Object structure:

- name: GitHub          # Display name (tooltip)
  href: https://...     # Social media URL
  icon: github          # Icon identifier

Available social icons:

copyrightText (string)

githubRepoUrl (string, URL)

Admin & Notification Configuration

adminConfig:
  # Admin emails for alerts and notifications (array)
  adminEmails:
    - admin@example.com
    - devops@example.com

  # Semantic Colors
  semanticColors:
    success: "#22c55e"
    warning: "#f59e0b"
    error: "#ef4444"
    info: "#3b82f6"

  # Email Configuration
  email:
    provider: resend
    fromEmail: noreply@example.com
    fromName: Node Map
    alertsFromEmail: alerts@example.com
    alertsFromName: Node Map Alerts
    autoConfirm: false
    verificationRequired: true
    otp:
      expiryMinutes: 10
      maxResendAttempts: 3
      resendCooldownSeconds: 60

  # Alert thresholds
  alerts:
    enabled: false
    nodeCountDropPercent: 20
    healthScoreThreshold: 70
    alertCooldownHours: 24

adminEmails (array of strings)

semanticColors (object)

Standardized colors for UI states across the application.

Purpose: Ensures consistent color usage for status indicators, alerts, and feedback.

semanticColors.success (string, hex color)

semanticColors.warning (string, hex color)

semanticColors.error (string, hex color)

semanticColors.info (string, hex color)

Best Practices:

Email Configuration

IMPORTANT: Two Separate Email Systems

AtlasP2P uses two independent email systems for different purposes:

  1. GoTrue Auth Emails (.env configuration)
    • Purpose: Authentication-related emails (signup, password reset, email verification)
    • Configured in: .env file using SMTP settings
    • Email service: Uses SMTP relay (Resend, SendGrid, or custom SMTP)
    • ENV variables: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS
    • Example: Resend SMTP (smtp.resend.com:587)
    • Note: GoTrue is a pre-built Supabase service that only reads ENV vars
  2. Application Custom Emails (project.config.yaml configuration)
    • Purpose: Custom application emails (alerts, notifications, node updates)
    • Configured in: config/project.config.yaml (adminConfig.email.provider)
    • Email service: Can use HTTP API (Resend, SendGrid) or SMTP
    • ENV variables: RESEND_API_KEY, SENDGRID_API_KEY, or SMTP settings
    • Example: Resend API for faster, feature-rich emails
    • Note: These emails are sent by your application code

Both can use the SAME provider (e.g., both use Resend), but through different interfaces (SMTP relay vs HTTP API).

email.provider (string)

email.fromEmail (string, email)

email.fromName (string)

email.alertsFromEmail (string, email, optional)

email.alertsFromName (string, optional)

email.autoConfirm (boolean)

email.verificationRequired (boolean)

email.otp.expiryMinutes (integer)

email.otp.maxResendAttempts (integer)

email.otp.resendCooldownSeconds (integer)

Alert Configuration

alerts.enabled (boolean)

alerts.nodeCountDropPercent (integer)

alerts.healthScoreThreshold (integer)

alerts.alertCooldownHours (integer)

Map Configuration

mapConfig:
  defaultCenter: [20, 0]
  defaultZoom: 2
  minZoom: 2
  maxZoom: 18
  tileProvider: openstreetmap
  clusterRadius: 80
  clusterMaxZoom: 14

  tileStyles:
    - id: light
      name: Light (Themed)
      url: https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png
      attribution: "© OpenStreetMap contributors"
      maxZoom: 20
      subdomains: [a, b, c, d]

  defaultTileStyle: light

defaultCenter (array: [latitude, longitude])

defaultZoom (integer)

minZoom (integer)

maxZoom (integer)

tileProvider (string)

clusterRadius (integer)

clusterMaxZoom (integer)

tileStyles (array of objects)

Custom map tile layers for the style switcher

Object structure:

- id: unique-id         # Unique identifier (lowercase, no spaces)
  name: Display Name    # Name shown in switcher
  url: https://...      # Tile server URL pattern
  attribution: "..."    # Copyright/attribution HTML
  maxZoom: 20          # Max zoom for this tileset
  subdomains: [a,b,c]  # Optional: tile server subdomains

URL patterns:

Popular tile providers:

CARTO (Free, recommended):

# Light theme
url: https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png

# Dark theme
url: https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png

# Voyager (colorful)
url: https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png

OpenStreetMap (Free):

url: https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

Stadia Maps (Requires API key):

url: https://tiles.stadiamaps.com/tiles/alidade_smooth/{z}/{x}/{y}{r}.png

defaultTileStyle (string)

Feature Flags

Control which features are enabled/disabled in your deployment.

features:
  map:
    enabled: true
    clustering: true
    heatmap: false
    liveUpdates: true

  stats:
    enabled: true
    versionChart: true
    countryChart: true
    healthScore: true

  filters:
    byCountry: true
    byVersion: true
    byTier: true
    byStatus: true
    search: true

  nodes:
    categories: true
    rankings: true
    uptimeTracking: true
    historicalData: true

  verification:
    enabled: true
    messageSign: true
    userAgent: true
    portChallenge: false
    dnsTxt: false

  tipping:
    enabled: true
    tracking: false

  community:
    nodeSubmission: false
    leaderboard: true
    badges: true

  ui:
    darkMode: true
    themeSwitcher: true

Map Features

Stats Features

Filter Features

Node Features

Verification Features

verification:
  enabled: true
  methods:
    messageSign: true      # ✅ IMPLEMENTED
    userAgent: false       # ⚠️ Partial (no crawler verification yet)
    portChallenge: false   # ⚠️ Partial (no crawler verification yet)
    dnsTxt: true           # ✅ IMPLEMENTED
  requirePayment: false    # 🚫 NOT IMPLEMENTED - Do not enable
  paymentAmount: 100
  paymentCurrency: DINGO
  challengeExpiryHours: 24
  autoApprove: false

Tipping Features

Community Features

UI Features

Turnstile (Bot Protection)

turnstile:
  enabled: true  # Enable Cloudflare Turnstile CAPTCHA
  siteKey: "0x4AAAAAACHmrULrWXGjnBlP"  # Public site key (safe to commit)
  mode: invisible  # Widget appearance mode
  protectedActions:
    - verification  # Protect node verification endpoint

What is Turnstile? Cloudflare Turnstile is a privacy-friendly CAPTCHA alternative that protects your API endpoints from bots and automated abuse without degrading user experience.

Configuration:

Environment Variables Required:

Add to your .env file (NEVER commit):

# Production keys (domain restricted)
NEXT_PUBLIC_TURNSTILE_SITE_KEY=0x4AAAAAACHmrULrWXGjnBlP
TURNSTILE_SECRET_KEY=0x4AAAAAACHmrfqdjuWH8nhgwEVTDHAqZTE

# OR for local development (test keys that always pass)
NEXT_PUBLIC_TURNSTILE_SITE_KEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

Development vs Production Keys:

How it Works:

  1. User triggers protected action (e.g., verification request)
  2. Frontend shows Turnstile widget (if mode=visible) or runs silently
  3. Turnstile validates user is human, returns token
  4. Frontend sends token with API request
  5. Backend verifies token with Cloudflare API
  6. If valid, request proceeds; if invalid, returns 403 error

Best Practices:

Free Tier Limits:

Asset Paths

assets:
  logoPath: /logos/logo.png
  faviconPath: /logos/favicon.ico
  ogImagePath: /logos/og-image.png

logoPath (string, path)

faviconPath (string, path)

ogImagePath (string, path)

What is OG Image? When someone shares your nodes map on social media, this image appears in the preview card. Make it eye-catching!

Environment Variables

While most configuration is in YAML, some sensitive values must remain in environment variables.

Required .env.local Variables

# Docker Compose Configuration
COMPOSE_PROJECT_NAME=atlasp2p  # Controls container/image naming

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# MaxMind GeoIP (for crawler)
MAXMIND_ACCOUNT_ID=your-account-id
MAXMIND_LICENSE_KEY=your-license-key

# Cloudflare Turnstile (Bot Protection) - REQUIRED if features.turnstile.enabled=true
TURNSTILE_SECRET_KEY=0x4AAAAAACHmrfqdjuWH8nhgwEVTDHAqZTE  # NEVER commit this!

# Optional: Crawler Configuration
CRAWLER_INTERVAL_MINUTES=5
MAX_CONCURRENT_CONNECTIONS=100
CONNECTION_TIMEOUT_SECONDS=10

Turnstile Setup:

  1. Create account at Cloudflare Turnstile
  2. Add your domain/localhost
  3. Copy Site Key → paste in project.config.yaml under features.turnstile.siteKey
  4. Copy Secret Key → paste in .env as TURNSTILE_SECRET_KEY (NEVER commit!)
  5. Set features.turnstile.enabled: true in project.config.yaml

Why These Aren’t in YAML

Quick Reference: What Goes Where

Type File Purpose
Public config project.config.yaml Branding, features, public settings
Secrets .env.local API keys, database credentials
Assets /apps/web/public/logos/ Logos, favicons, images
Business logic Code files Tier thresholds, PIX formula

Examples

See /config/examples/ for complete configuration examples:

Validation

Your configuration is validated at build time. Common errors:

❌ Invalid color format: Use hex colors like #ff8c00 ❌ Missing required fields: All fields shown above are required ❌ Invalid icon names: Must use icons from the available list ❌ Invalid URLs: Must start with http:// or https:// ❌ Mismatched defaultTileStyle: Must match a tileStyle id

✅ Tip: Run pnpm build to validate your configuration before deploying

Need Help?