ESP8266 Kore Server

A multi-protocol embedded server implementation for the ESP8266 supporting Gemini, Spartan, HTTP, and Gopher protocols.

Features

• Multi-Protocol Support:
  • Gemini (port 1965) with optional client certificate authentication
  • Spartan (port 300)
  • HTTP (port 80)
  • Gopher (port 70)
• Virtual Hosting: Serve multiple domains from a single device
• File Management: Built-in admin interface for file operations
• Content Generation:
  • Dynamic directory listings
  • Server status page
  • Fortune cookie system
  • Tinylog blog engine
  • CPIO archive generation
  • Feed generation for gemini sites
• Security Features:
  • TLS encryption for Gemini
  • Client certificate authentication
  • Path validation to prevent directory traversal
• System Integration:
  • mDNS support for local network discovery
  • DuckDNS integration for dynamic DNS
  • NTP time synchronization
  • UPnP port mapping (optional)

Requirements

• ESP8266 board (NodeMCU, Wemos D1 Mini, etc.)
• Arduino IDE set up for ESP8266 development
• ESP8266 LittleFS Data Upload plugin
• RSA certificate and private key for Gemini TLS support
• File system with content (LittleFS or SD card)

Setup

1. Configure WiFi and Host:

   • Edit /data/kore.cfg to set your WiFi credentials and hostname
   • Add your RSA certificate to /data/ssl/srv-cert.pem
   • Add your RSA private key to /data/ssl/srv-key.pem
   • (Optional) Add CA certificate to /data/ssl/ca-cert.pem for client authentication

2. Prepare Content:

   • Add your gemini content to /data/[hostname]/
   • For virtual hosting, create directories for each domain
   • Add fortune files to /data/fortunes/ (optional)

3. Upload to Device:

   • Open the sketch in Arduino IDE
   • Compile and upload the sketch to your ESP8266 board
   • Run Arduino IDE > Tools > ESP8266 LittleFS Data Upload to upload the data folder

4. Connect:

   • Check serial output for connection status
   • Connect using your preferred browser for each protocol:
     • Gemini: gemini://[hostname].local or gemini://[your-dns-name]
     • Spartan: spartan://[hostname].local
     • HTTP: http://[hostname].local
     • Gopher: gopher://[hostname].local

Special Paths

• /status - Server status information
• /fortunes - Random fortune cookies
• /admin/file-manager - Web-based file management (requires client certificate)
• /admin/create-directory - Create directories (requires client certificate)
• /tinylog/new - Add entries to tinylog (requires client certificate)
• /cpio - Generate CPIO archive of content (requires client certificate)
• /*/feed.gmi - Generate dynamic feed of directory contents

Titan Protocol

The server supports the Titan protocol for file uploads:

titan://[hostname].local/path?mime=text/gemini;token=[token];size=[bytes]

Configure the token in kore.cfg for security.

Configuration

The main configuration file /data/kore.cfg supports these options:

• hostname - Primary domain name
• titan - Token for Titan uploads
• ddns - DuckDNS token for dynamic DNS
• tz - Timezone string (e.g., "UTC-2")
• wifi - WiFi credentials (SSID,PASSWORD)
• mime - MIME type mappings (ext,gph,mime)
• mdns - Enable/disable mDNS (0/1)

Example configuration:

hostname=example.com
titan=mysecrettoken
ddns=your-duckdns-token
tz=UTC0
wifi=MyNetwork,MyPassword
mime=gmi,0,text/gemini
mime=txt,0,text/plain