Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Listsome

A platform for sharing DIY projects and recipes with the maker community.

Table of Contents

Introduction

Listsome is a content sharing and documentation platform designed for indie web makers and creators. Instead of being “listless” (without energy or purpose), you’re “listsome” - actively documenting and sharing the things you create. Whether it’s a woodworking project, a new recipe, or an electronics build, Listsome helps you share what you’ve done so others can learn from your experience.

Think of it as:

  • A recipe box for all your DIY projects, not just food
  • A portfolio for makers who build things
  • A how-to wiki written by people who actually did the thing
  • Your project’s documentation that others can follow

Project Goals & Values

Core Values

Indie Web First

  • Content creators maintain ownership and control of their work
  • No platform lock-in - content lives on creator’s own sites
  • Support for indie web standards (microformats, WebMention, etc.)
  • Respect for creator autonomy and data sovereignty

Anti-Big Tech

  • Avoid dependency on FAANG services (AWS, GCP, etc.)
  • Use open source alternatives wherever possible
  • Support self-hosting and homelab deployment
  • Build with privacy-first principles

Accessibility & Inclusion

  • Deployable on modest hardware (Raspberry Pi, old laptops)
  • Low resource requirements for participation
  • Support for creators with limited technical resources
  • Progressive enhancement for all users

Community-Driven

  • Open source development model
  • Community curation and moderation
  • Transparent algorithms and processes
  • Collaborative improvement of discovery mechanisms

Primary Goals

  1. Enhance Discoverability: Help indie web creators reach new audiences without leaving their platforms
  2. Preserve Creator Control: Aggregate and enhance without appropriating or displacing original content
  3. Build Community: Foster connections between makers, learners, and creators across the indie web
  4. Democratize Access: Make sophisticated content discovery accessible to anyone with basic hardware
  5. Support Federation: Enable multiple hub instances to work together while maintaining independence

Architectural Overview

High-Level Architecture

The Listsome platform operates as a content sharing and documentation service with three primary layers:

  1. Discovery Layer: Finds and ingests content from distributed sources
  2. Processing Layer: Parses, enriches, and curates discovered content
  3. Distribution Layer: Provides enhanced discovery interfaces and federation capabilities

Technology Stack

Core Runtime

  • Language: Rust (performance, safety, single-binary deployment)
  • Web Framework: Axum (async, composable, well-maintained)
  • Database: SQLite (currently), PostgreSQL (planned)
  • Search: Full-text search (planned, Tantivy)

Frontend

  • Framework: Leptos (Rust-based, SSR)
  • Styling: Plain CSS
  • Markdown: Integrated editor with live preview (planned)

Content Processing (Planned)

  • Microformats: h-recipe, h-entry parsing
  • JSON-LD: Schema.org HowTo/Recipe structured data

Federation & Standards

  • ActivityPub: ActivityPub endpoints (partial)
  • WebFinger: Instance discovery (partial)
  • RSS/Atom: Feed generation and consumption

Deployment

  • Containerization: Docker with multi-arch builds (x86_64, ARM64) (planned)
  • Single Binary: Embedded assets, SQLite database, zero dependencies
  • CI/CD: Codeberg Actions (planned)

System Components

Content Discovery

  • WebMention endpoint for indie web integration
  • RSS/Atom feed crawler with intelligent scheduling
  • ActivityPub listener for fediverse content
  • Manual submission interface for community curation
  • Microformats parser for structured content detection

Content Processing Pipeline

  • Multi-stage parsing (structured → semi-structured → unstructured)
  • Confidence scoring for parsing quality assessment
  • Content enrichment (difficulty, time estimates, tags)
  • Duplicate detection and content deduplication
  • Image extraction and optimization

Data Storage

  • Metadata database (PostgreSQL/SQLite)
  • Full-text search index (Tantivy)
  • Content cache (summaries, images, metadata)
  • Analytics database (privacy-friendly, aggregated only)

User Interfaces

  • Web discovery interface (browse, search, filter)
  • RSS/JSON feeds (filtered streams, custom collections)
  • Embed widgets (for integration with other sites)
  • Mobile PWA (offline reading, responsive design)

Federation Network

  • ActivityPub server (share discoveries, follow creators)
  • WebHook system (real-time notifications)
  • Bridge integrations (Discord, Slack, etc.)
  • Hub-to-hub federation (distributed network)

Content Discovery Pipeline

Discovery Methods

WebMention Integration

  • Creators send webmentions when publishing new content
  • Automatic validation and processing of mentioned content
  • Support for indie web reply/like/repost interactions
  • Backfeed social interactions to original content

RSS/Atom Crawling

  • Intelligent scheduling based on publication frequency
  • Support for full-content and summary feeds
  • Automatic discovery of new feeds through OPML and link following
  • Respect for robots.txt and rate limiting

ActivityPub Listening

  • Monitor fediverse hashtags (#diy, #maker, #tutorial)
  • Process shared links and content from Mastodon, Lemmy, etc.
  • Federate discoveries back to the network
  • Support for ActivityPub collections and featured content

Manual Submission

  • Community-driven content submission
  • Verification and quality control processes
  • Batch processing for content creators
  • API for programmatic submission

Content Parsing Strategy

Tier 1: Structured Data (90-95% confidence)

#![allow(unused)]
fn main() {
// Microformats (h-recipe, h-entry)
<article class="h-entry">
  <h1 class="p-name">Project Title</h1>
  <div class="e-content">...</div>
</article>

// JSON-LD Schema.org
{
  "@type": "HowTo",
  "name": "Project Title",
  "instruction": [...]
}
}

Tier 2: Semi-Structured HTML (60-80% confidence)

  • Common blog patterns and CSS selectors
  • Numbered lists and heading hierarchies
  • Content area detection algorithms
  • Heuristic-based extraction

Tier 3: Unstructured Content (30-50% confidence)

  • Regex pattern matching for steps, materials, tools
  • Natural language processing for content classification
  • Machine learning for difficulty and time estimation
  • Requires human review for quality assurance

Content Enhancement

Automatic Enrichment

  • Difficulty level assessment based on tools and complexity
  • Time estimation from step analysis and historical data
  • Tag generation using content analysis and ML
  • Image extraction, optimization, and caching
  • Tool and material standardization

Community Enhancement

  • Quality voting and community feedback
  • Collaborative tagging and categorization
  • Content correction and improvement suggestions
  • Moderation and spam detection

Federation Model

Hub-to-Hub Federation

Distributed Network

  • Multiple independent hub instances
  • Shared content discovery and curation
  • Distributed moderation decisions
  • Resilient to single points of failure

ActivityPub Integration

  • Standard federation protocol
  • Interoperability with Mastodon, Lemmy, etc.
  • Custom activity types for instructional content
  • Rich metadata sharing between instances

Content Syndication

  • RSS/JSON feed sharing between hubs
  • Webhook notifications for new discoveries
  • Collaborative filtering and recommendation
  • Respect for creator preferences and licensing

Creator Benefits

Increased Discoverability

  • Content appears in federated timeline
  • Cross-instance search and discovery
  • Community-driven promotion and sharing
  • Analytics on content performance

Maintained Control

  • Content remains on creator’s platform
  • Full attribution and backlinks
  • Creator can request removal at any time
  • No platform lock-in or content migration

Community Engagement

  • Cross-platform comments and discussions
  • Collaborative improvement suggestions
  • Skill-based networking and connections
  • Project remixes and derivatives tracking

Technical Implementation

Core Architecture Decisions

Single Binary Deployment

#![allow(unused)]
fn main() {
// Embedded assets and database
// Zero external dependencies
// Configurable via environment variables
// Graceful degradation for limited resources
}

Resource Efficiency

  • Target <512MB RAM for basic functionality
  • Efficient content parsing and caching
  • Intelligent background processing
  • Rate limiting and resource management

Privacy-First Design

  • No user tracking or cross-site analytics
  • Aggregate statistics only
  • GDPR compliance built-in
  • User control over data retention

Extensible Plugin System

  • Custom content parsers
  • Additional federation protocols
  • Community-contributed enhancements
  • Modular deployment options

Development Practices

Open Source Methodology

  • Codeberg for primary development
  • Transparent development process
  • Community contributions welcome
  • Comprehensive documentation and examples

Quality Assurance

  • Comprehensive test suite (unit, integration, end-to-end)
  • Automated security scanning
  • Performance benchmarking
  • Community code review

Deployment Options

  • Single binary for simple deployment
  • Docker containers for containerized environments
  • Kubernetes manifests for production scale
  • Ansible playbooks for automated setup

Development Roadmap

Phase 1: Foundation (Months 1-3)

  • Basic content parsing pipeline
  • SQLite-based single-user deployment
  • Web interface for content discovery
  • RSS feed generation
  • Basic WebMention support

Phase 2: Enhancement (Months 4-6)

  • PostgreSQL support for multi-user instances
  • Advanced content enrichment (AI/ML)
  • Community features (voting, collections)
  • Mobile PWA development
  • Comprehensive test suite

Phase 3: Federation (Months 7-9)

  • ActivityPub server implementation
  • Hub-to-hub federation
  • Advanced search and filtering
  • Performance optimization
  • Security hardening

Phase 4: Ecosystem (Months 10-12)

  • Plugin system for extensibility
  • Advanced analytics and insights
  • Community moderation tools
  • Integration bridges (Discord, Slack)
  • Comprehensive documentation

Long-Term Vision

Sustainable Ecosystem

  • Self-sustaining community development
  • Multiple independent hub instances
  • Rich ecosystem of tools and integrations
  • Standard protocols adopted by other projects

Creator Empowerment

  • Indie web creators have powerful discovery tools
  • Reduced dependency on centralized platforms
  • Strong community connections and collaboration
  • Sustainable creator economy support

Technical Innovation

  • Advanced content understanding and classification
  • Intelligent recommendation systems
  • Seamless cross-platform integration
  • Privacy-preserving analytics and insights

This documentation is living and will evolve with the project. Contributions and suggestions are welcome through our Codeberg repository.

Getting Started

Welcome to Listsome! This guide will help you set up your instance and discover DIY content from the indie web.

What is Listsome?

Listsome is a federated platform for discovering and sharing DIY content. Each instance is self-hosted and operated independently, connected to other instances through a simple subscription model.

Quick Start

Step 1: Set Up Your Instance

  1. Visit your listsome instance
  2. Complete the setup wizard to create your admin account
  3. Configure your instance details (name, domain, description)

Step 2: Add Content

  1. Go to Admin → New Project
  2. Add your tutorials, recipes, or DIY projects
  3. Use markdown for content formatting
  4. Tag content for organization

Your content is now available via RSS feed and visible to anyone who follows your instance.

Step 3: Discover Content

  1. Go to Admin → Federation
  2. Add instances to your blogroll
  3. Your instance will fetch their RSS feeds
  4. New content appears in your aggregated feed
  1. Visit the Timeline to see content from followed instances
  2. Use Search to find specific content across all feeds
  3. Filter by tags or content type

Your Instance Features

Content Publishing

  • Create and manage projects with markdown
  • Organize with tags
  • Generate RSS feeds for your content
  • Share your instance URL with others

Discovery

  • Add instances to your blogroll
  • Aggregate content from followed instances
  • Search across all aggregated content
  • Follow your interests

Federation

  • Your instance is discoverable via WebFinger
  • Others can find and subscribe to your content
  • No complex ActivityPub required - just RSS

Best Practices

Content

  • Quality over quantity - Better to have great tutorials than many mediocre ones
  • Use tags - Help others discover your content
  • Regular updates - Keep your content current

Discovery

  • Follow curated instances - Find instances that share content you care about
  • Stay organized - Review your blogroll periodically
  • Trust your sources - Only follow instances you find trustworthy

Key Concepts

Blogroll

A list of instances you follow. When you add an instance, your instance subscribes to their RSS feed.

Aggregation

Content from followed instances is fetched and stored locally, making it searchable and browsable.

Federation

Listsome instances are decentralized. Each operates independently but can discover and share content with others.

Next Steps

  1. Add Your First Project - Share your DIY content
  2. Manage Your Blogroll - Discover content from others
  3. Browse the Timeline - See aggregated content
  4. Search Content - Find specific tutorials or projects

Need Help?

Ready to start? Set up your account, add some content, and start discovering DIY projects from the indie web!

Discovery

Listsome instances discover content from other instances through a simple blogroll model. No scraping, no complex federation - just subscribe to feeds you trust.

How Discovery Works

The Blogroll Model

A blogroll is a curated list of instances you follow. When you add an instance to your blogroll:

  1. Your instance subscribes to their RSS feed
  2. New content appears in your aggregated feed
  3. You can search across all aggregated content

Think of it like RSS reader subscriptions, but managed by your instance instead of a third party.

Key Principles

  • Explicit consent - You choose who you follow
  • No inbox complexity - Just RSS feed fetching
  • Decentralized - Each instance operates independently
  • Your data stays yours - Aggregated content is cached locally

Managing Your Blogroll

Adding an Instance

  1. Go to the Federation page
  2. Enter the domain of the instance you want to follow
  3. Click “Follow” to add to your blogroll
  4. Your instance will start fetching their RSS feed

Removing an Instance

  1. Go to the Federation page
  2. Find the instance in your blogroll
  3. Click “Unfollow” to remove
  4. Their content will be removed from your aggregated feed

Discovery vs. Federation

Discovery (Current Implementation)

  • Model: Blogroll + RSS aggregation
  • Protocol: RSS feeds only
  • Complexity: Low
  • Privacy: Your instance fetches their public feed
  • Example: Adding diy.example.com to follow their tutorials

Federation (Future)

  • Model: ActivityPub social features
  • Protocol: ActivityPub inbox/outbox
  • Complexity: High (HTTP signatures, verification)
  • Privacy: Direct instance-to-instance communication
  • Example: Mastodon-style following with social interactions

For now, discovery through RSS feeds is the focus. Federation features may be added later.

Finding Instances

Ways to Discover Listsome Instances

  • Direct sharing - Someone shares their instance URL with you
  • Community lists - Future: a registry of public instances
  • Word of mouth - Indie web communities, maker forums
  • RSS discovery - Find blogs/tutorials you like and check if they use listsome

What to Look For

  • Content topics that interest you
  • Active instances with regular updates
  • Community engagement and moderation
  • Quality of existing aggregated content

Content Aggregation

How It Works

  1. You add an instance to your blogroll
  2. Your instance fetches their RSS feed
  3. New items are stored in your database
  4. Content appears in your timeline and search results
  5. Original source is preserved for attribution

Updating Content

  • Your instance checks for new content periodically
  • Existing content is updated if changed
  • Deleted content is handled gracefully

Privacy Considerations

What Others Can See

  • Your instance domain (when you follow them)
  • Public RSS feed content (what you already get from RSS)

What Others Cannot See

  • Your admin credentials
  • Other instances in your blogroll
  • Your local-only content
  • Server logs (if you configure logging carefully)

Discovery Best Practices

Building Your Blogroll

  • Quality over quantity - Follow instances with content you actually want
  • Trust the source - Only follow instances you find trustworthy
  • Stay organized - Regularly review and clean up your blogroll
  • Check activity - Follow active instances with regular updates

Discovering New Content

  • Start with interests - Find topics you care about
  • Follow curators - Find instances that curate good content
  • Branch out - When you find good content, explore their sources

Next Steps

  • Your Blogroll - Add or remove followed instances
  • Timeline - View aggregated content from followed instances
  • Search - Find content across your aggregated feed

💡 Pro Tip: Think of your blogroll as a curated reading list for DIY content. Add instances that consistently publish content you find valuable.

Architecture

Listsome is a federated, self-hostable platform for discovering and sharing DIY content (tutorials, recipes, projects).

Principles

  • Own your data - Content lives on your instance, you control it
  • Federation - Instances discover and follow each other via ActivityPub
  • No scraping - Explicit subscription model, not stealth extraction
  • RSS-first - Structured feeds as the interoperability layer

How It Works

┌─────────────────┐       Follow        ┌─────────────────┐
│   your.listsome │  ──────────────────►  │  my.listsome    │
│                 │  ◄──────────────────  │                 │
│  Your tutorials │     Content feed      │  Your feed +    │
│  Your recipes   │                       │  My feed        │
│  Your projects │                       │                 │
└─────────────────┘                       └─────────────────┘
        ▲                                        ▲
        │                                        │
     WebFinger                               WebFinger
        │                                        │
        └─────────── Fediverse ──────────────────┘

Instance Discovery

  1. WebFinger - Query https://instance/.well-known/webfinger?resource=acct:user@instance
  2. Actor endpoint - Returns ActivityPub actor with inbox/outbox URLs
  3. Follow - Send Follow activity to their inbox
  4. Accept - They approve, relationship established
  5. Aggregate - Your instance pulls their RSS feed

Content Flow

Publishing (Local)

  1. Create content via admin UI or API
  2. Content stored in local SQLite database
  3. Available via RSS feed at /feed.xml
  4. Optionally broadcast via ActivityPub outbox

Discovery (Remote)

  1. Discover instance via WebFinger
  2. Send Follow request
  3. On Accept, subscribe to their RSS feed
  4. Content aggregated into your local feed
  5. Search across your aggregated content

Data Model

Local Content

  • Projects with title, description, markdown content
  • Tags for organization
  • Author attribution
  • Published status

Remote Content (Aggregated)

  • Fetched from followed instances’ RSS feeds
  • Stored locally for search
  • Original source preserved for attribution

Relationships

  • Followed instances (who you follow)
  • Followers (who follows you)
  • Pending follows (approval queue)

Comparison to Faircamp/Fairplayer

ComponentFaircampFairplayerListsome
PublisherArtists publish musicAggregates faircampsUsers publish DIY content
FormatAudio catalogAudio playerTutorials, recipes, projects
DiscoveryManual URLsWebFingerWebFinger + RSS
Subscription-Follow faircampFollow listsome instance
Federation-Fairplayer networkListsome federation

Listsome takes the Faircamp/Fairplayer model and applies it to DIY/maker content with full federation support.

Password Reset System

This document describes the password reset and recovery system for Listsome. Since this is a single-user instance, the approach prioritizes simplicity while maintaining security.

Overview

The system provides two methods for password recovery:

  1. Direct CLI Reset - Immediate password change (requires SSH access)
  2. Token-Based Reset - Generate a one-time token for web-based reset

Architecture

Database Schema

CREATE TABLE password_reset_tokens (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    token_hash TEXT UNIQUE NOT NULL,     -- Argon2 hash (never store plaintext)
    account_id INTEGER NOT NULL,
    created_at TIMESTAMP,
    expires_at TIMESTAMP,                 -- 1 hour expiry
    used_at TIMESTAMP,                    -- When consumed
    ip_address TEXT,                      -- Optional audit
    used BOOLEAN DEFAULT FALSE            -- Single-use flag
);

Security Features:

  • Tokens are hashed with Argon2id before storage
  • 1-hour expiration window
  • Single-use only (marked as used after consumption)
  • Automatic cleanup of expired tokens (after 24 hours)
  • Optional IP address logging for audit trail

Token Lifecycle

  1. Generation → Store hash, display plaintext once
  2. Validation → Compare hash, check expiry/usage
  3. Consumption → Mark as used, update timestamp
  4. Cleanup → Remove old tokens via trigger

CLI Tool Usage

Direct Password Reset

Use when you have SSH access to the server:

# Reset password immediately
$ listsome-cli reset-password
WARNING: This will reset the admin password immediately.
Type 'I am sure' to continue:
I am sure
Enter new password: ********
Confirm new password: ********
Password has been reset successfully.

Security: Requires exact confirmation phrase “I am sure”

Generate Reset Token

Use when you’ve forgotten the password but can access server logs:

# Generate a one-time token
$ listsome-cli generate-reset-token
This will generate a one-time password reset token.
Type 'generate' to create a token:
generate

========================================
RESET TOKEN (save this securely):
a1b2c3d4e5f6... (64 hex characters)
========================================

Use this token via:
1. Web interface: POST /reset-password with token
2. Or check server logs for the token

Token expires: 1 hour
Token is single-use

Token Format: 32 random bytes encoded as 64 hex characters

Cleanup Tokens

Remove expired and used tokens:

$ listsome-cli cleanup-tokens
Cleanup complete: removed 5 tokens

Setup (Initial Account Creation)

Create the first admin account if none exists:

$ listsome-cli setup
No admin account found. Let's create one.
Email: admin@example.com
Password: ********
Display Name: Admin User
Instance Domain (e.g., diy.example.com): diy.example.com
Setup complete! You can now log in.

Recovery Scenarios

Scenario 1: Forgot Password, Have SSH

Solution: Direct CLI reset

ssh user@server
listsome-cli reset-password
# Enter new password

Risk Level: Low - requires server access

Scenario 2: Forgot Password, No SSH

Solution: Generate token via logs

# On server (or in systemd logs)
journalctl -u listsome | grep "RESET TOKEN"
# Or check application logs
tail -f /var/log/listsome/app.log

Then use the token via web interface or cURL:

curl -X POST http://localhost:3000/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token": "a1b2c3d4...", "new_password": "newpass123"}'

Risk Level: Medium - token exposure in logs

Scenario 3: Complete Lockout

Solution: Physical server access required

If you have:

  • No SSH access
  • No web access
  • Forgot password

You must have physical access to the server to:

  1. Access console directly
  2. Mount the SQLite database
  3. Delete the account row to trigger re-setup
  4. Or use SQL to manually update password_hash
# Emergency: Delete account to re-trigger setup
sqlite3 data.db "DELETE FROM account WHERE id = 1;"
# Then run setup again
listsome-cli setup

Risk Level: High - requires physical security breach

Security Considerations

Threat Model

Assumed attackers:

  • Someone with web access (can try tokens)
  • Someone with file system read access (can see tokens in logs)
  • Someone with database access (can see token hashes)

Mitigations:

  • Tokens expire in 1 hour (reduces window of attack)
  • Tokens are single-use (prevents replay)
  • Tokens are hashed (attacker with DB access can’t use tokens)
  • Direct reset requires confirmation phrase (prevents accidental execution)

Audit Trail

All CLI operations log to stderr:

[CLI] Starting password reset process
[CLI] Connecting to database: sqlite://data.db
[CLI] Password updated successfully for account_id=1

Recommendation: Redirect stderr to syslog:

listsome-cli reset-password 2> >(logger -t listsome-cli)

File Permissions

The CLI should be protected by file permissions:

# Make CLI only executable by owner
chmod 750 listsome-cli
chown root:admin listsome-cli

# Database should be readable only by application user
chmod 640 data.db
chown listsome:listsome data.db

Implementation Details

Token Generation

Uses cryptographically secure random bytes:

#![allow(unused)]
fn main() {
let token_bytes: Vec<u8> = (0..32).map(|_| rand::random::<u8>()).collect();
let token = hex::encode(&token_bytes);  // 64 hex chars
}

Entropy: 256 bits (comparable to JWT signing keys)

Hash Algorithm

Uses Argon2id (same as password hashing):

  • Memory-hard (resists GPU cracking)
  • Salted (each token produces different hash)
  • Tunable parameters

Database Cleanup

Automatic trigger runs on INSERT:

DELETE FROM password_reset_tokens 
WHERE expires_at < datetime('now', '-24 hours')
   OR (used = TRUE AND used_at < datetime('now', '-7 days'));

Future Enhancements

Possible improvements (not currently needed for single-user):

  1. Email Integration - Send tokens via email using lettre
  2. Rate Limiting - Limit token generation per IP
  3. Hardware Token - Require Yubikey for CLI operations
  4. Recovery Keys - Generate offline backup codes during setup
  5. Web UI - Add /forgot-password page for self-service

Testing

Run tests for the password reset system:

# Run all auth tests
cargo test auth

# Run specific token tests
cargo test test_create_reset_token
cargo test test_validate_and_consume_token

Troubleshooting

Token Not Working

Checklist:

  • Token hasn’t expired (1 hour limit)
  • Token hasn’t been used already
  • Token is complete (64 characters)
  • Database is accessible

CLI Can’t Connect to Database

# Check DATABASE_URL environment variable
echo $DATABASE_URL

# Default is sqlite://data.db
# Override: export DATABASE_URL="sqlite:///path/to/data.db"

Database Locked

If SQLite is locked by the running web server:

# Stop the web server temporarily
systemctl stop listsome
listsome-cli reset-password
systemctl start listsome

References

RSS Feeds

Stay updated with new content by subscribing to RSS feeds. Learn how to use feeds for content discovery and sharing.

Available RSS Feeds

Content Type Feeds

All Content

Everything in the database

RSS Feed
Recipes

Cooking and crafting recipes

RSS Feed
Tutorials

Step-by-step guides

RSS Feed
Projects

DIY projects and builds

RSS Feed

Feed Parameters

  • content_type: Filter by content type (Recipe, Tutorial, Project, Article)
  • limit: Control number of items (default: 50, max: 100)
  • format: Choose RSS or Atom format (default: rss)

Examples:

  • /feed?content_type=Recipe&limit=20 - 20 latest recipes
  • /feed?format=atom - All content in Atom format
  • /feed?content_type=Tutorial&limit=10 - 10 latest tutorials

Using RSS Feeds

RSS Readers

Add any of the feed URLs above to your favorite RSS reader:

  • Feedly - Web and mobile RSS reader
  • Inoreader - Advanced RSS reader with filters
  • NetNewsWire - macOS RSS reader
  • Reeder - iOS RSS reader
  • Any RSS reader - Most support custom feed URLs

Browser Integration

  • Firefox: Built-in RSS reader
  • Chrome: Extensions like “RSS Feed Reader”
  • Safari: Built-in feed reading

Following Instances

Blogroll-Based Following

Content from other instances is added through your blogroll:

  1. Go to the Federation page
  2. Enter the domain of an instance to follow
  3. Your instance will automatically fetch their RSS feed
  4. Content appears in your aggregated timeline

How It Works

  • Adding an instance subscribes to their RSS feed
  • New content is fetched and stored locally
  • You can unfollow at any time to stop aggregation
  • See the Discovery guide for more details

Feed Sources

  • Listsome instances - Full compatibility with RSS feeds
  • Other platforms - Any site with a valid RSS/Atom feed
  • Faircamp sites - Audio-focused content (future integration)

Feed Management

Organizing Feeds

  • Create folders in your RSS reader for different topics
  • Use descriptive names for each feed
  • Set update frequencies based on content volume
  • Enable notifications for important feeds

Content Quality

  • Review feed content before adding
  • Check update frequency to avoid spam
  • Monitor content quality over time
  • Remove inactive feeds periodically

Advanced Feed Usage

Feed Filtering

  • Use content type parameters to focus on specific content
  • Combine multiple feeds for comprehensive coverage
  • Create filtered feeds for specific interests

Integration

  • Email subscriptions for important feeds
  • IFTTT/Zapier automation with feed updates
  • Social media sharing of interesting content
  • Content aggregation for newsletters

Automation

  • Scheduled consumption of external feeds
  • Automated filtering based on keywords
  • Content alerts for specific topics
  • Feed exports for backup and sharing

Troubleshooting Feeds

Feed Not Loading

  • Check the URL is correct and accessible
  • Ensure the feed format is valid (RSS/Atom)
  • Try different feed parameters
  • Check if the site blocks feed access

Missing Content

  • Some feeds may have access restrictions
  • Content may be behind paywalls
  • Feed format may not be standard
  • Site may have changed feed structure

Performance Issues

  • Large feeds may take time to process
  • Frequent updates can be resource-intensive
  • Some feeds may have rate limits

Feed Best Practices

Content Sources

  • Choose reputable sources with consistent quality
  • Look for active feeds with regular updates
  • Check content relevance to your interests
  • Verify feed stability before relying on it

Organization

  • Use descriptive feed names in your reader
  • Create topic-based folders for organization
  • Set appropriate update intervals (hourly, daily, weekly)
  • Regular cleanup of inactive feeds

Integration

  • Combine with search for comprehensive discovery
  • Use feeds for staying current on topics
  • Share interesting feeds with communities
  • Export feed lists for backup

Next Steps

💡 Pro Tip: RSS feeds are perfect for staying updated with your favorite creators and topics. Combine them with search for the best content discovery experience.

Searching Content

Master the search features to find tutorials, recipes, and projects in your collection.

  1. Navigate to the search page
  2. Enter keywords in the search field
  3. Click “Search” to see results

Advanced Search Options

  • Content Type Filter: Limit results to Recipes, Tutorials, Projects, or Articles
  • Results Limit: Choose how many results to show (10, 20, 50, or 100)

Search Tips

Effective Keywords

  • Be specific: “sourdough bread recipe” works better than just “bread”
  • Use multiple words: “arduino temperature sensor” finds more relevant results
  • Try variations: Different terms for the same concept
  • Include context: “raspberry pi camera project” is more specific than “camera”

Content Type Filtering

  • Recipes: Cooking instructions, ingredient lists, preparation methods
  • Tutorials: Step-by-step guides, how-to instructions, educational content
  • Projects: DIY builds, construction guides, maker projects
  • Articles: Blog posts, general information, opinion pieces

Understanding Search Results

Result Information

Each search result shows:

  • Title: Click to visit the original content
  • Content Type Badge: Color-coded by type (Recipe, Tutorial, Project, Article)
  • Confidence Score: How well the content was parsed (higher is better)
  • Description: Preview of the content
  • Metadata: Materials count, tools count, steps count

Interpreting Results

  • High confidence scores (80%+) indicate well-parsed content
  • Complete metadata (materials, tools, steps) means better structured content
  • Original source links take you to the creator’s website
  • Content types help you find the right type of information

Search Strategies

Finding Recipes

  • Search for ingredients: “chicken rice tomato”
  • Search for meal types: “pasta dinner” or “breakfast smoothie”
  • Search for techniques: “fermentation” or “sous vide”

Finding Tutorials

  • Search for skills: “woodworking” or “electronics”
  • Search for tools: “3d printer” or “laser cutter”
  • Search for projects: “smart home” or “robotics”

Finding Projects

  • Search for outcomes: “greenhouse” or “furniture”
  • Search for materials: “wood” or “arduino”
  • Search for complexity: “beginner” or “advanced”

Building Search Collections

Curated Searches

  • Save effective search terms
  • Build collections around topics
  • Create personal knowledge bases

Regular Discovery

  • Search weekly for new content
  • Follow up on related topics
  • Build comprehensive resource libraries

No Results Found

  • Try different keywords
  • Use broader search terms
  • Remove content type filters
  • Check spelling

Too Many Results

  • Add more specific keywords
  • Use content type filters
  • Include context or qualifiers

Irrelevant Results

  • Use more specific search terms
  • Add context to your keywords
  • Try synonyms or related terms

Advanced Search Techniques

Boolean-Like Searching

While the current search doesn’t support complex boolean operators, you can:

  • Use multiple specific terms: “raspberry pi camera night vision”
  • Combine concepts: “arduino temperature humidity sensor”
  • Add qualifiers: “beginner woodworking project”

Iterative Refinement

  1. Start with broad search terms
  2. Note relevant results
  3. Refine with more specific terms
  4. Use content type filters to narrow results

Search Status

Currently Implemented

  • Basic text search across local content
  • Filter by content type

In Development

  • Full-text search backend
  • Relevance ranking
  • Filter by tags and source instance

Future Improvements

  • Fuzzy matching for typos
  • Advanced filters (difficulty, time, materials)
  • Cross-instance search (search followed instances)
  • Saved searches and alerts

Next Steps

💡 Pro Tip: The more content you add through parsing, the better your search results will be. Start building your collection to improve search relevance.

Current Limitations

While Listsome is functional, it has some limitations to be aware of. This page explains what’s not implemented yet and how it affects your experience.

Search Capabilities

Current State

  • Simple text matching only - No advanced search features
  • No fuzzy matching - Exact spelling required
  • Limited filtering - Only by content type
  • No relevance ranking - Results ordered by confidence score only

Impact

  • Search results may include irrelevant matches
  • Typos in search queries won’t find results
  • Can’t filter by difficulty, time, or materials
  • Results may not be in the most useful order

Workaround

  • Use specific, correctly spelled keywords
  • Add more context to search terms
  • Use content type filters to narrow results
  • Parse more content to improve result relevance

Content Discovery

Current State

  • Manual URL entry only - No automatic crawling
  • No content suggestions - No “related content” features
  • Limited parsing strategies - May not work with all websites
  • No batch processing - One URL at a time

Impact

  • Can’t discover content automatically
  • No recommendations for similar content
  • Some websites may not parse well
  • Time-consuming to add many URLs

Workaround

  • Manually find and add content you’re interested in
  • Use RSS feeds to stay updated with known sources
  • Focus on well-structured websites
  • Build your collection gradually

Data Storage

Current State

  • SQLite only - No multi-user support
  • No PostgreSQL backend - Limited scalability
  • Single-user focused - Not designed for teams
  • No data export/import - Difficult to migrate

Impact

  • Can’t share collections with others
  • Limited to personal use
  • No collaboration features
  • Data stays on your local machine

Workaround

  • Use the platform for personal content management
  • Share RSS feed URLs for others to subscribe
  • Export content through RSS feeds
  • Run your own instance for personal use

User Interface

Current State

  • Basic HTML interface - No advanced features
  • No user accounts - No personalization
  • No saved searches - Can’t save favorite queries
  • No content management - Limited organization tools

Impact

  • Can’t save preferences or settings
  • No personalized recommendations
  • Can’t organize content into collections
  • Limited content management features

Workaround

  • Use browser bookmarks for important searches
  • Manually organize content through RSS feeds
  • Use external tools for content organization
  • Focus on core discovery and search features

Content Processing

Current State

  • Rule-based parsing only - No AI/ML enhancement
  • No duplicate detection - May have duplicate content
  • Limited content types - Basic classification
  • No quality scoring - All content treated equally

Impact

  • Parsing may miss complex content structures
  • Duplicate content may appear in results
  • Content classification may be inaccurate
  • No automatic quality assessment

Workaround

  • Focus on well-structured, simple content
  • Manually review and remove duplicates
  • Use confidence scores to gauge parsing quality
  • Parse content from reputable sources

RSS Feeds

Current State

  • Basic feed generation - Limited customization
  • No feed management - Can’t edit or delete feeds
  • No social features - Can’t share or follow feeds
  • Limited feed formats - Basic RSS/Atom only

Impact

  • Can’t customize feed content or appearance
  • No way to manage multiple feeds
  • Can’t collaborate on feed curation
  • Limited integration options

Workaround

  • Use feeds as-is for basic subscription
  • Share feed URLs manually
  • Use external feed management tools
  • Focus on content discovery rather than feed management

Federation & Social Features

Current State

  • Basic ActivityPub endpoints - WebFinger, Actor, Inbox exist
  • Blogroll discovery - Follow other instances via RSS aggregation
  • No full ActivityPub flow - Follow/Accept not fully implemented
  • No fediverse connectivity - Can’t connect to Mastodon/Lemmy

Impact

  • Can discover content from followed instances
  • Can’t accept/manage followers yet
  • Limited social interaction features
  • No connection to broader fediverse

Workaround

  • Add instances to your blogroll manually
  • Share your RSS feed URL for others to subscribe
  • Use RSS readers to follow content
  • Focus on blogroll-based discovery

Performance & Scalability

Current State

  • Single-threaded processing - Limited performance
  • No caching - Every request processes from scratch
  • SQLite limitations - Not designed for high traffic
  • No background processing - Everything happens synchronously

Impact

  • Slow response times with large content databases
  • No caching for frequently accessed content
  • Limited concurrent users
  • Resource-intensive operations

Workaround

  • Keep content database manageable in size
  • Use for personal or small team use
  • Avoid very large search result sets
  • Run on capable hardware

Why These Limitations Exist

Design Philosophy

These limitations are intentional and by design:

  • Start simple - Focus on core functionality first
  • Personal use focus - Designed for individual users initially
  • Progressive enhancement - Build advanced features over time
  • Resource efficiency - Keep requirements minimal

Development Approach

  • Phase-based development - Core features first, advanced features later
  • User feedback driven - Build what users actually need
  • Open source model - Community can contribute improvements
  • Sustainability - Focus on maintainable, reliable features

Future Improvements

These limitations will be addressed in future updates:

  • Enhanced search with full-text indexing and relevance ranking
  • Full ActivityPub flow with Follow/Accept management
  • Federated blogrolls for cross-instance discovery
  • Fediverse connectivity to connect with Mastodon/Lemmy
  • Multi-user support with PostgreSQL backend

Getting Help

If You Encounter Issues

  • Check this page to see if it’s a known limitation
  • Try the workarounds suggested above
  • Review the future features to see if it’s planned
  • Check the getting started guide for basic usage

Contributing

  • Report issues on the project repository
  • Suggest improvements or new features
  • Help with documentation or testing
  • Contribute code for new features

Next Steps

💡 Remember: These limitations represent the current state, not the final vision. The platform is designed to grow and improve over time.

Future Features

These features are planned but not yet implemented. They represent the next phases of development for Listsome.

Phase 2: Enhanced Search & Discovery

Full-Text Search Engine

  • Tantivy integration for advanced search capabilities
  • Relevance ranking based on content quality and user engagement
  • Fuzzy matching for typos and variations
  • Stemming and lemmatization for better word matching

Automatic Content Discovery

  • Web crawling of known tutorial sites
  • RSS feed monitoring for automatic content ingestion
  • Content recommendations based on user interests
  • Duplicate detection to avoid redundant content

Advanced Filtering

  • Difficulty level filtering (beginner, intermediate, advanced)
  • Time estimation filtering (quick projects, long-term builds)
  • Material requirements filtering (specific tools or materials)
  • Content quality scoring and filtering

Phase 3: Federation & Social Features

ActivityPub Integration

  • Fediverse connectivity - Connect with Mastodon, Lemmy, and other platforms
  • Cross-instance sharing - Share projects with other Listsome instances
  • Social interactions - Like, share, and comment on content
  • Creator following - Follow your favorite makers and creators

Federated Blogrolls

  • Instance blogrolls - Curate lists of listsome instances you follow
  • Discovery by endorsement - See what trusted instances recommend
  • Trust propagation - Follow chains of endorsed instances
  • Cross-instance search - Search content across followed instances

WebMention Support

  • Cross-site interactions - Mention and reference content on other sites
  • Backfeed integration - Receive notifications when content is referenced
  • Citation tracking - See how your content is being used
  • Social web integration - Connect with the broader indie web

Hub-to-Hub Federation

  • Distributed network - Multiple instances working together
  • Content synchronization - Share discoveries across instances
  • Collaborative curation - Community-driven content quality assessment
  • Resilient architecture - No single points of failure

Phase 4: AI/ML Enhancement

Intelligent Content Processing

  • Content classification using machine learning
  • Automatic tagging based on content analysis
  • Difficulty assessment from content complexity
  • Time estimation from step analysis

Quality Scoring

  • Content quality metrics based on structure and completeness
  • User engagement tracking (views, saves, shares)
  • Automated spam detection and content filtering
  • Content freshness scoring and updates

Personalized Recommendations

  • User preference learning from search and save patterns
  • Content similarity matching for related content discovery
  • Trending content identification and promotion
  • Personalized feeds based on interests

Phase 5: Advanced User Experience

Progressive Web App

  • Offline functionality for reading saved content
  • Mobile optimization with responsive design
  • Push notifications for new content and updates
  • App-like experience on mobile devices

User Accounts & Personalization

  • User registration and profile management
  • Personal collections and content organization
  • Saved searches and search history
  • Content ratings and reviews

Content Management

  • Bulk operations for content management
  • Content editing and improvement suggestions
  • Collection sharing and collaboration
  • Content export in multiple formats

Phase 6: Infrastructure Improvements

Multi-User Support

  • PostgreSQL backend for scalability
  • User authentication and authorization
  • Team collaboration features
  • Content sharing and permissions

Performance Optimization

  • Redis caching for frequently accessed content
  • Background processing for content ingestion
  • Database optimization for large content collections
  • CDN integration for static assets

API Enhancements

  • GraphQL API for flexible data access
  • REST API improvements with better pagination
  • Webhook support for integrations
  • Rate limiting and abuse prevention

Local-Prod Sync Architecture

  • Plain text source of truth - Markdown files stored locally as canonical data
  • Local SQLite index - Index derived from MD files for fast queries
  • Migration-based sync - Push local changes to prod via versioned migrations
  • Conflict resolution - Timestamp-based conflict detection with manual resolution
  • Bidirectional sync - Pull prod changes, reconcile with local files
  • Offline-first workflow - Full functionality without connectivity, sync when online

Phase 7: Ecosystem Integration

Third-Party Integrations

  • Discord bots for content sharing
  • Slack integrations for team notifications
  • IFTTT/Zapier support for automation
  • Browser extensions for easy content saving

Content Platform Integration

  • WordPress plugins for content publishing
  • Static site generators integration
  • GitHub integration for documentation sites
  • YouTube/PeerTube integration for video content

Developer Tools

  • API documentation and developer portal
  • SDKs for different programming languages
  • CLI tools for content management
  • Docker integration for easy deployment

Long-Term Vision

Decentralized Content Network

  • Global federation of content discovery hubs
  • Interoperable content across different platforms
  • Creator-owned content with distributed hosting
  • Community governance and decision-making

AI-Powered Discovery

  • Semantic search understanding content meaning
  • Personalized learning paths and recommendations
  • Automated content curation and quality assessment
  • Intelligent content synthesis and summarization

Sustainable Ecosystem

  • Self-funding model through optional premium features
  • Community contributions and open development
  • Educational partnerships with maker communities
  • Research collaborations for content understanding

Development Roadmap

Current Phase

  • ✅ Content publishing with markdown
  • ✅ RSS feed generation
  • ✅ Blogroll-based discovery (RSS aggregation)
  • ✅ ActivityPub endpoints (WebFinger, Actor, Inbox)
  • 🔄 Full-text search backend
  • 🔄 Session management (auth)
  • 🔄 Project editor UI

Next Phase

  • 🔄 Enhanced search (filtering, relevance ranking)
  • 🔄 Federated blogrolls (cross-instance discovery)
  • 🔄 Follow/Accept flow for ActivityPub
  • 🔄 Improved user interface

Future Phases

  • 📋 Fediverse connectivity (Mastodon, Lemmy)
  • 📋 Trust propagation and endorsement chains
  • 📋 Cross-instance search
  • 📋 Multi-user support and collaboration

Future Phases (2025-2026)

  • 📋 Federation and social features
  • 📋 AI/ML content enhancement
  • 📋 Multi-user support and collaboration
  • 📋 Progressive web app development

Contributing to Development

Ways to Help

  • Bug reports and feature requests
  • Code contributions for new features
  • Documentation improvements
  • Testing and feedback
  • Community support and advocacy

Development Priorities

  • User feedback drives feature development
  • Core functionality stability before new features
  • Backward compatibility maintained across updates
  • Open standards and interoperability prioritized

Getting Involved

  • Check the project repository for open issues
  • Join community discussions about features
  • Contribute documentation or code
  • Help test new features and provide feedback

Feature Request Process

How to Suggest Features

  1. Check existing issues to see if it’s already planned
  2. Create a feature request with detailed description
  3. Include use cases and benefits
  4. Consider implementation complexity and impact

What Gets Prioritized

  • User impact - How many users will benefit
  • Feasibility - Can it be implemented with available resources
  • Alignment - Does it fit the project vision
  • Dependencies - Does it enable other features

Next Steps

🚀 The future of Listsome is shaped by the community. Your feedback and contributions help determine what gets built next!

Releases

Listsome uses release-plz for automated releases. This ensures version consistency between Cargo.toml, git tags, CHANGELOG.md, and GitHub/Gitea releases.

Release Workflow

  1. Push to main → Release PR workflow creates a PR with version bump and changelog update
  2. Review and merge PR → release-plz release creates git tag and Codeberg release
  3. Tag pushed → CI builds and uploads binaries to the release

Files Involved

  • .woodpecker/release.yml - Woodpecker CI pipeline for releases
  • .woodpecker/release-plz.toml - release-plz configuration
  • CHANGELOG.md - Maintains full release history

Configuration

The release workflow is configured for git-only mode (no crates.io publishing):

[workspace]
git_only = true           # Don't publish to crates.io
publish = false           # Disable cargo publish
git_release_enable = true # Create Codeberg releases
semver_check = false     # Not a library
changelog_update = true  # Keep CHANGELOG.md updated

Tokens Required

The release_api_token secret must be configured in Woodpecker CI with appropriate permissions.

Creating a Token on Codeberg

  1. Go to Settings → Applications on Codeberg
  2. Click Create Token
  3. Set a descriptive name (e.g., Woodpecker CI - listsome)
  4. Select these scopes:
    • read:repository - Read repository data
    • write:repository - Push tags and create releases
  5. Click Create Token
  6. Copy the token immediately - it won’t be shown again

Configuring the Secret in Woodpecker CI

  1. Go to your repository in Woodpecker CI
  2. Navigate to Settings → Secrets
  3. Create a new secret:
    • Name: release_api_token
    • Name: ssh_key (for Pages deployment in docs.yml)
    • Value: Paste the token from Codeberg (no quotes, no trailing newline)
  4. Ensure the secret is available for:
    • tag event (for release and upload-assets steps)
    • push event (for release-pr step)
    • Image: rustlang/rust:* (or leave empty for all images)

Token Format Requirements

  • Token must be a raw string with no extra whitespace
  • When pasting into Woodpecker, ensure no trailing newline is added
  • If you see “invalid header field value” errors, regenerate the token

CHANGELOG Management

The existing CHANGELOG.md is preserved and updated with each release:

  • New commits are added to the [Unreleased] section
  • When a release is created, unreleased changes are moved to the version section
  • Full changelog history is maintained in the root CHANGELOG.md

Binaries

Each release includes pre-built binaries for multiple platforms:

  • x86_64-unknown-linux-gnu - Standard Linux (glibc)
  • x86_64-unknown-linux-musl - Static binary (works anywhere)
  • aarch64-unknown-linux-gnu - ARM64 (Raspberry Pi, ARM servers)

Version Bumping

Versions are bumped automatically based on conventional commits:

  • feat: commits → Minor version bump
  • fix: commits → Patch version bump
  • feat!: or fix!: commits → Major version bump
  • Other commits → Patch version bump

See Conventional Commits for details.

Manual Release (Emergency)

If automated release fails, you can create a release manually:

# Install release-plz
cargo install release-plz

# Bump version and update changelog locally
release-plz update

# Create the release
release-plz release --forge gitea

See Also

Production Deployment

Listsome is designed to be deployed simply to any hardware you control. The goal is to bring ease of use to technology you control.

Prerequisites

  • A server running Linux (Raspberry Pi, VPS, or dedicated hardware)
  • just task runner installed locally (cargo install just or via package manager)
  • ARM64 cross-compilation support: rustup target add aarch64-unknown-linux-gnu
  • SSH access to your server

Configuration

Create a .justlocal file in the project root:

export LISTSOME_HOST="your-server.local"
export LISTSOME_USER="your-username"
export LISTSOME_PORT="3003"
export LISTSOME_PORT_TEST="3005"

Then source it before running just commands:

source .justlocal

Note: .justlocal is gitignored - never commit it.

Quick Start

First Time Setup

just deploy-init

This creates:

  • /opt/listsome/ with binary, static files, and database
  • /opt/listsome/.env with runtime configuration
  • Systemd service at /etc/systemd/system/listsome.service
  • Database file at /opt/listsome/db/listsome.db

Deploy Updates

just deploy

Builds ARM64 binary, copies to server, restarts service.

Cloudflare Tunnel Setup

Point your tunnel to localhost:3003 (or your configured port):

# ~/.cloudflared/config.yml
ingress:
  - hostname: yourdomain.com
    service: http://localhost:3003

Restart the tunnel: sudo systemctl restart cloudflared

First-Time Admin Setup

After deploying, visit https://yourdomain.com/setup to create your admin account.

Maintenance Commands

Production Management

just logs-prod          # View real-time logs
just status-prod        # Check service status
just restart-prod       # Restart service
just shell              # SSH to server

Binary Management

just binary-list        # List all versions with timestamps
just rollback-prod      # Interactive rollback to previous version
just binary-prune --keep 3  # Delete old versions, keep last 3

Database

just db-backup          # Backup to ~/.listsome/backups/

Test Deployment (Optional)

Deploy to a test instance before promoting to production:

just deploy-test-init   # First time test setup (port 3004)
just deploy-test      # Deploy to test

File Structure on Server

/opt/listsome/                    # Production
├── listsome                      # Current binary
├── listsome.v0.1.0             # Versioned backup
├── static/                       # Static assets
├── content/assets/              # User uploads
├── db/
│   └── listsome.db              # SQLite database
└── .env                         # Runtime config

/opt/listsome-test/              # Test (optional)
├── listsome
├── static/
├── content/assets/
├── db/
│   └── listsome.db
└── .env

Troubleshooting

Permission denied on database:

ssh your-user@your-server "sudo chown your-user:your-user /opt/listsome/db/listsome.db"

Service won’t start:

just logs-prod 100
just status-prod

Build fails:

rustup target add aarch64-unknown-linux-gnu

Security Notes

  • App runs as your user (not root)
  • Service is bound to specific port only
  • Database is in app directory, isolated per instance
  • Systemd hardening enabled (NoNewPrivileges, PrivateTmp, etc.)

See Also

  • just --list for all available commands
  • just help for quick reference