gitcitadel-online/README.md

GitCitadel Online

A server-generated static website that fetches content from Nostr relays, processes AsciiDoc articles, and serves professional HTML pages with intelligent caching. Built with Go and designed for decentralized content publishing.

Features

• Wiki System: Fetches and displays wiki articles (kind 30818) from Nostr relays
• Blog & Articles: Supports blog posts and longform articles (kind 30023) with full markdown/AsciiDoc processing
• E-Books Library: Displays e-books and publications (kind 30040) from Nostr
• Feed Integration: Real-time kind 1 feed integration in sidebar
• Contact Form: Nostr-based contact form with browser extension support and anonymous submission
• AsciiDoc Processing: Full AsciiDoc to HTML conversion with table of contents support
• Intelligent Caching: Multi-layer caching system with background rewarming
• Media Caching: Automatic caching of external images and media
• SEO Optimized: Structured data, sitemaps, and meta tags
• Responsive Design: Mobile-first responsive design with medium-dark theme
• Accessibility: WCAG AA/AAA compliant with proper ARIA labels and keyboard navigation
• Content Security Policy: Secure CSP headers for XSS protection

Requirements

• Go 1.22+ - For building and running the server
• Node.js - For AsciiDoc processing
• @asciidoctor/core - npm package for AsciiDoc conversion
• Network access - To connect to Nostr relays

Installation

1. Clone the repository:

   git clone <repository-url>
   cd gitcitadel-online
   

2. Install Go dependencies:

   go mod tidy
   

3. Install Node.js dependencies:

   npm install @asciidoctor/core
   

   Or install globally:

   npm install -g @asciidoctor/core
   

4. Download nostr-tools bundle (for contact form):

   mkdir -p static/js
   curl -L -o static/js/nostr.bundle.js https://unpkg.com/nostr-tools@latest/lib/nostr.bundle.js
   

   Note: The nostr-tools library is hosted locally to avoid dependency on external CDNs.

5. Copy and configure:

   cp config.yaml.example config.yaml
   

   Edit config.yaml with your Nostr indices, relay URLs, and settings.

Configuration

Edit config.yaml to configure:

Required Settings

• wiki_index: naddr for your wiki index (kind 30040)
• blog_index: naddr for your blog index (kind 30040)
• repo_announcement: naddr for repository announcement (for contact form)
• relays.feeds: Primary relay URL for fetching content
• relays.profiles: Comma-separated relay URLs for profile data
• relays.contactform: Comma-separated relay URLs for contact form submissions

Optional Settings

• link_base_url: Base URL for external links (default: Alexandria)
• cache.refresh_interval_minutes: How often to refresh cached pages (default: 30)
• feed.poll_interval_minutes: How often to poll for new feed items (default: 5)
• feed.max_events: Maximum number of feed items to display (default: 30)
• server.port: HTTP server port (default: 8080)
• server.enable_compression: Enable gzip compression (default: true)
• seo.site_name: Site name for SEO
• seo.site_url: Canonical site URL
• seo.default_image: Default OpenGraph image path

Example Configuration

wiki_index: "naddr1qvzqqqr4tqpzplfq3m5v3u5r0q9f255fdeyz8nyac6lagssx8zy4wugxjs8ajf7pqyd8wumn8ghj7..."
blog_index: "naddr1qvzqqqr4tqpzplfq3m5v3u5r0q9f255fdeyz8nyac6lagssx8zy4wugxjs8ajf7pqyvhwumn8ghj7..."
repo_announcement: "naddr1qvzqqqrhnypzplfq3m5v3u5r0q9f255fdeyz8nyac6lagssx8zy4wugxjs8ajf7pqq9xw6t5vd5hgctyv4kqde47kt"
relays:
  feeds: "wss://theforest.nostr1.com"
  profiles: "wss://theforest.nostr1.com,wss://nostr.land"
  contactform: "wss://thecitadel.nostr1.com,wss://relay.damus.io"
server:
  port: 8080
  enable_compression: true
seo:
  site_name: "GitCitadel"
  site_url: "https://gitcitadel.com"

Running

Development Mode

Run with verbose logging:

go run cmd/server/main.go --dev

Production Mode

Build and run:

go build -o gitcitadel-online cmd/server/main.go
./gitcitadel-online

Command Line Options

• --config <path>: Path to configuration file (default: config.yaml)
• --dev: Enable development mode with verbose logging
• --log-level <level>: Set log level (debug, info, warn, error) (default: info)

Routes & Endpoints

Public Pages

• / - Landing page with feed sidebar
• /wiki - Wiki index page
• /wiki/<d-tag> - Individual wiki article pages
• /blog - Blog index page with article navigation
• /articles - Longform articles index page
• /ebooks - E-books library with sortable table
• /feed - Feed page with relay information
• /contact - Contact form with Nostr integration

Static Assets

• /static/ - Static files (CSS, JavaScript, images, icons)
• /cache/media/ - Cached external media files
• /favicon.ico - Site favicon

API Endpoints

• /api/contact - POST endpoint for submitting contact form events (JSON)

System Endpoints

• /health - Health check endpoint
• /metrics - Metrics endpoint (Prometheus format)
• /sitemap.xml - XML sitemap for search engines
• /robots.txt - Robots.txt file

Project Structure

gitcitadel-online/
├── cmd/
│   └── server/              # Main server application entry point
├── internal/
│   ├── asciidoc/           # AsciiDoc processing with Node.js
│   ├── cache/              # Multi-layer caching system
│   │   ├── cache.go        # Page cache
│   │   ├── feed_cache.go  # Feed item cache
│   │   └── media_cache.go # Media file cache
│   ├── config/             # Configuration management
│   ├── generator/          # HTML generation and SEO
│   ├── logger/             # Structured logging
│   ├── nostr/              # Nostr client and event parsing
│   │   ├── client.go       # Relay connection management
│   │   ├── wiki.go         # Wiki event parsing
│   │   ├── profile.go      # Profile metadata
│   │   ├── feed.go         # Feed event parsing
│   │   ├── ebooks.go       # E-book parsing
│   │   └── issues.go       # Issue/contact form handling
│   └── server/             # HTTP server and handlers
├── static/                  # Static assets
│   ├── css/                # Stylesheets
│   ├── icons/              # SVG icons
│   └── js/                  # JavaScript libraries
├── templates/              # HTML templates
│   ├── base.html           # Base template
│   ├── landing.html        # Landing page
│   ├── wiki.html           # Wiki pages
│   ├── blog.html           # Blog pages
│   ├── articles.html       # Article pages
│   ├── ebooks.html         # E-books page
│   ├── feed.html           # Feed page
│   ├── contact.html        # Contact form
│   └── components.html     # Reusable components
├── cache/                   # Runtime cache directory
│   └── media/              # Cached media files
├── config.yaml             # Configuration file (not in repo)
├── config.yaml.example      # Example configuration
├── go.mod                   # Go module dependencies
├── package.json             # Node.js dependencies
└── README.md               # This file

Development

Building

go build -o gitcitadel-online cmd/server/main.go

Testing

The server uses a caching system that pre-generates all pages. On first run, pages will be generated and cached. Subsequent requests serve from cache until the refresh interval.

Cache Management

• Pages are cached in memory for fast serving
• Cache rewarming runs in the background at configured intervals
• Media files are cached to disk in cache/media/
• Cache can be cleared by restarting the server

Logging

Logs are structured and can be configured via:

• --log-level flag (debug, info, warn, error)
• --dev flag enables debug logging and verbose output

Content Types Supported

Wiki Articles (Kind 30818)

• AsciiDoc content processing
• Table of contents generation
• Cross-referencing support
• Syntax highlighting

Blog Posts (Kind 30023)

• Markdown/AsciiDoc content
• Image support with caching
• Author profiles
• Timestamps and metadata

E-Books (Kind 30040)

• Publication listings
• Author information
• Sortable table interface
• Links to Alexandria library

Feed Items (Kind 1)

• Real-time note display
• Author badges with profiles
• Timestamp formatting
• Content rendering

Contact Form

The contact form supports two submission methods:

1. Browser Extension: Users can sign with their Nostr browser extension (nos2x, Alby, etc.)
2. Anonymous: Server generates a temporary key pair for anonymous submissions

Both methods publish kind 1 events to configured relays with proper tags for issue tracking.

Security

• Content Security Policy (CSP) headers prevent XSS attacks
• All external scripts are hosted locally
• Input validation on contact form
• Event signature verification for API submissions
• Secure relay connections (WSS)

Performance

• Multi-layer caching (memory + disk)
• Background cache rewarming
• Gzip compression support
• Optimized static asset serving
• Efficient Nostr event parsing

Docker Deployment

GitCitadel Online can be run using Docker for easy deployment on localhost or remote servers.

Quick Start with Docker Compose

# 1. Create config file
cp config.yaml.example config.yaml
# Edit config.yaml with your settings

# 2. Build and run
docker-compose up -d

# 3. View logs
docker-compose logs -f

The application will be available at http://localhost:8080.

For detailed Docker instructions, see DOCKER.md.

License

MIT License - see LICENSE.md for details

Contributing

Contributions are welcome! Please ensure:

• Code follows Go conventions
• Templates are accessible (WCAG AA/AAA)
• All routes are documented
• Configuration changes are backward compatible