Skip to content
Klutch.sh Docs

Deploying Ech0

Introduction

Ech0 is a next-generation open-source, self-hosted, lightweight federated publishing platform designed for individuals. It provides a clean, distraction-free environment for sharing thoughts, writings, and links with ultra-low resource consumption and full data sovereignty.

Key Features

  • 🌐 Federated Social Network: ActivityPub protocol support for connecting with the Fediverse
  • ✍️ Distraction-Free Writing: Clean online Markdown editor with rich plugin support and live preview
  • ☁️ Ultra-Lightweight: Memory usage under 15MB, Docker image under 40MB
  • 📦 Data Sovereignty: All content stored locally in SQLite database with RSS feed support
  • 🔐 Secure Backup System: Web, TUI, and CLI modes for one-click export and automatic backups
  • ♻️ Zero-Downtime Recovery: Online snapshot restore without service interruption
  • 🚀 Instant Deployment: From installation to usage with just one command
  • 🎨 Modern UI: Built with Vue.js 3 and responsive design
  • 🔒 Privacy First: No ads, tracking, subscriptions, or external service dependencies

Tech Stack

  • Backend: Go 1.25.3+ with Gin web framework
  • Frontend: Vue.js 3 with TypeScript
  • Database: SQLite 3 for atomic single-file storage
  • Port: Default port 6277
  • Image: sn0wl1n/ech0:latest (~40MB)

Use Cases

  • Personal Microblogging: Share thoughts, notes, and links like a personal social network
  • Federated Content: Connect with others through ActivityPub protocol
  • Markdown Publishing: Write and publish formatted content with live preview
  • RSS Feed Generation: Automatic RSS feeds for your published content
  • Private Social Network: Self-hosted alternative to traditional social platforms
  • Knowledge Sharing: Lightweight platform for sharing ideas and insights

Why Deploy Ech0 on Klutch.sh?

  • Instant Deployment: Deploy from GitHub in minutes with automatic Docker detection
  • Persistent Storage: Built-in volume management for SQLite database and backups
  • Global Accessibility: Deploy globally with automatic HTTPS on custom domains
  • Zero Configuration: No complex setup—just push your Dockerfile and deploy
  • Cost-Effective: Pay only for what you use with transparent pricing
  • Automatic Backups: Volume snapshots ensure your data is always protected
  • Scalable Resources: Adjust compute resources as your platform grows
  • ActivityPub Ready: Public domain support for federation with the Fediverse

Prerequisites

Before deploying Ech0, ensure you have:

  • A Klutch.sh account
  • A GitHub account for repository hosting
  • Basic understanding of Docker and environment variables
  • (Optional) A custom domain for ActivityPub federation

Preparing Your Ech0 Repository

Option 1: Use Official Docker Image

Create a simple Dockerfile that uses the official Ech0 image:

FROM sn0wl1n/ech0:latest


# Expose Ech0 port
EXPOSE 6277


# Data and backup volumes will be mounted at runtime
VOLUME ["/app/data", "/app/backup"]


# The image already has the correct CMD

Option 2: Build from Source (Advanced)

If you want to customize Ech0, you can build from source:

# Build stage - Frontend
FROM node:24-alpine AS frontend-builder


WORKDIR /app/web
COPY web/package.json web/pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install


COPY web/ ./
RUN pnpm build


# Build stage - Backend
FROM golang:1.25-alpine AS backend-builder


# Install build dependencies
RUN apk add --no-cache gcc g++ musl-dev sqlite-dev


WORKDIR /app


# Copy Go modules first for better caching
COPY go.mod go.sum ./
RUN go mod download


# Copy source code
COPY . .


# Copy built frontend
COPY --from=frontend-builder /app/web/dist ./web/dist


# Build the application with CGO for SQLite
ENV CGO_ENABLED=1
RUN go build -ldflags="-s -w" -o ech0 main.go


# Runtime stage
FROM alpine:latest


# Install runtime dependencies
RUN apk add --no-cache ca-certificates tzdata sqlite-libs


WORKDIR /app


# Copy binary from builder
COPY --from=backend-builder /app/ech0 .


# Create directories for data and backups
RUN mkdir -p /app/data /app/backup


# Expose Ech0 port
EXPOSE 6277


# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:6277/api/health || exit 1


# Run Ech0
CMD ["./ech0"]

Creating a .dockerignore File

Optimize your build with a .dockerignore file:

# Dependencies
node_modules/
vendor/


# Build outputs
web/dist/
*.exe
*.test
*.out


# Development files
.git/
.github/
.vscode/
*.md
.env
.env.local


# Data directories
data/
backup/
tmp/


# OS files
.DS_Store
Thumbs.db

Environment Variables Configuration

Create a .env.example file for reference:

Terminal window
# Server Configuration
PORT=6277


# JWT Secret (REQUIRED - Change this!)
JWT_SECRET=your-super-secret-jwt-key-change-this


# Server Address (Required for ActivityPub federation)
SERVER_ADDRESS=https://yourdomain.com


# Optional: Meting API for music card feature
METING_API=https://api.example.com/meting


# Optional: Twikoo Comment API
TWIKOO_API=https://twikoo.yourdomain.com


# Optional: S3 Storage Configuration
S3_ENABLED=false
S3_ENDPOINT=s3.amazonaws.com
S3_BUCKET=ech0-media
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=us-east-1


# Optional: Database backup schedule
BACKUP_ENABLED=true
BACKUP_INTERVAL=24h

Deploying Ech0 on Klutch.sh

  1. Push your Ech0 repository to GitHub:
    Terminal window
    git init
    git add .
    git commit -m "Initial Ech0 deployment"
    git branch -M main
    git remote add origin https://github.com/yourusername/ech0.git
    git push -u origin main
  2. Log into your Klutch.sh dashboard.
  3. Navigate to the **Apps** section and click **"Create App"**.
  4. Configure your Ech0 deployment:
    • App Name: ech0 (or your preferred name)
    • Repository: Select your Ech0 GitHub repository
    • Branch: main (or your deployment branch)
    • Traffic Type: HTTP (for web application)
    • Internal Port: 6277 (Ech0’s default port)
    • Region: Choose your preferred deployment region
    • Compute: Start with Shared CPU (1 vCPU, 512MB RAM is sufficient)
    • Instances: 1 (increase for high-availability)
  5. Add environment variables in the **Environment Variables** section:

    Required:

    JWT_SECRET=your-super-secret-jwt-key-please-change-this

    Recommended (for ActivityPub):

    SERVER_ADDRESS=https://your-app-name.klutch.sh

    Optional:

    METING_API=https://meting-api.example.com
    TWIKOO_API=https://twikoo.yourdomain.com
    BACKUP_ENABLED=true
    BACKUP_INTERVAL=24h
  6. Configure **Persistent Volumes** for data persistence:

    Primary Volume (Database):

    • Mount Path: /app/data
    • Size: 1 GB (adjust based on expected content volume)

    Backup Volume (Optional but Recommended):

    • Mount Path: /app/backup
    • Size: 2 GB (should be larger than data volume)
  7. Click **"Create"** to deploy. Klutch.sh will: - Build your Docker image - Provision persistent volumes - Deploy your Ech0 instance - Generate a unique URL: `https://your-app-name.klutch.sh`
  8. Wait for the deployment to complete (typically 2-4 minutes).
  9. Access your Ech0 instance at the provided URL.
  10. **First-time setup**: Register an account. The first registered user automatically becomes the administrator with publishing permissions.

Configuration & Customization

JWT Security

The JWT_SECRET environment variable is critical for authentication security:

Terminal window
# Generate a secure random secret
JWT_SECRET=$(openssl rand -hex 32)

Important: Never use the default value "Hello Echos" in production. Update this in your Klutch.sh environment variables.

ActivityPub Federation Setup

To join the Fediverse and enable federation:

  1. **Bind a custom domain** to your Klutch.sh app (required for ActivityPub)
  2. **Set the SERVER_ADDRESS** environment variable to your domain:
    Terminal window
    SERVER_ADDRESS=https://yourdomain.com
  3. **Restart your app** to apply changes
  4. **Verify federation** by visiting `https://yourdomain.com/.well-known/webfinger` in your browser
  5. **Add Connect accounts** from other Fediverse instances in Ech0's settings panel

RSS Feed Access

Ech0 automatically generates RSS feeds for your content:

# User feed
https://your-app-name.klutch.sh/rss/user/@username


# All public content
https://your-app-name.klutch.sh/rss/public

Subscribe to these URLs in your favorite RSS reader (Feedly, NewsBlur, etc.).

Comment System Integration

Ech0 supports Twikoo for comments:

  1. Deploy a Twikoo backend (see Twikoo documentation)
  2. Add the `TWIKOO_API` environment variable:
    Terminal window
    TWIKOO_API=https://twikoo.yourdomain.com
  3. Comments will automatically appear on posts

S3 Storage for Media

For external media storage, configure S3-compatible storage:

Terminal window
S3_ENABLED=true
S3_ENDPOINT=s3.amazonaws.com
S3_BUCKET=ech0-media
S3_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_REGION=us-east-1

Note: Ensure your S3 bucket has public read access for uploaded media.

Music Card Feature

To enable music card sharing, set up a Meting API:

Terminal window
METING_API=https://meting-api.example.com

If not set, Ech0 uses the default API hosted on Vercel.

Custom Domains

To use your own domain with Ech0:

  1. Navigate to your app in the Klutch.sh dashboard
  2. Go to **Settings** → **Domains**
  3. Click **"Add Domain"** and enter your domain (e.g., `ech0.yourdomain.com`)
  4. Add the provided CNAME record to your DNS provider: 
    Type: CNAME
    Name: ech0
    Value: your-app-name.klutch.sh
  5. Wait for DNS propagation (5-30 minutes)
  6. Update `SERVER_ADDRESS` environment variable to your custom domain
  7. Klutch.sh will automatically provision SSL/TLS certificates

Data Management & Backups

Manual Backup

Create a manual backup through Ech0’s web interface:

  1. Log in as administrator
  2. Navigate to **Settings** → **Data Management**
  3. Click **"Create Snapshot"** to generate a backup
  4. Download the snapshot file from the backup list

Automatic Backups

Enable automatic backups with environment variables:

Terminal window
BACKUP_ENABLED=true
BACKUP_INTERVAL=24h  # Daily backups

Backups are stored in /app/backup directory (your mounted volume).

Restore from Backup

To restore from a backup snapshot:

Web Interface (Zero-Downtime):

  1. Go to **Settings** → **Data Management**
  2. Click **"Restore Snapshot"**
  3. Select your backup file
  4. Confirm restoration
  5. If data doesn't appear immediately, restart the container

Manual Restoration:

  1. Stop your Ech0 app in Klutch.sh dashboard
  2. Access your volume through Klutch.sh file browser
  3. Replace files in `/app/data` with your backup
  4. Restart your app

Volume Snapshots

Leverage Klutch.sh’s volume snapshot feature:

  1. Navigate to **Volumes** in your Klutch.sh dashboard
  2. Select your Ech0 data volume
  3. Click **"Create Snapshot"** for point-in-time backups
  4. Restore from snapshots if needed

User Management & Permissions

Administrator Setup

The first registered user becomes the system administrator with full permissions:

  • Publish content (posts, images, links)
  • Manage system settings
  • Assign permissions to other users
  • Access data management features
  • Configure federation settings

Granting Publishing Permissions

By default, only administrators can publish content. To grant permissions:

  1. Log in as administrator
  2. Navigate to **Settings** → **User Management**
  3. Select a user
  4. Toggle **"Publishing Permissions"**
  5. Save changes

Note: Ech0 intentionally keeps permissions simple (Admin vs Non-Admin) to maintain a lightweight architecture. Be cautious when assigning administrator privileges.

Publishing Content

Writing Posts

  1. Click the **"New Post"** button
  2. Use the Markdown editor with live preview
  3. Add text, images, or extended content (music/video cards)
  4. Click **"Publish"** when ready

Content Guidelines

Ech0 works best with focused content:

Recommended:

  • Short-form text posts
  • Text + images
  • Text + extended content (music/video)
  • Single images with captions

Not Recommended:

  • Dense posts combining text + images + extended content
  • Long-form articles (use external platforms and link instead)
  • Multiple extended content items in one post

Markdown Features

Ech0 supports rich Markdown formatting:

# Headers (H1-H6)
**Bold** and *Italic* text
[Links](https://example.com)
![Images](https://example.com/image.jpg)


- Bullet lists
1. Numbered lists


> Blockquotes


`Inline code` and


```code blocks```


Tables, task lists, and more...

Media Uploads

Upload images directly through the editor:

  • Drag and drop images
  • Click the image button to browse files
  • Paste images from clipboard
  • Automatic image processing and optimization

If S3 storage is configured, media is uploaded to S3. Otherwise, it’s stored locally in your SQLite database.

Production Best Practices

Security Hardening

  1. **Strong JWT Secret**: Never use default values
    Terminal window
    # Generate secure secret
    openssl rand -base64 32
  2. **HTTPS Enforcement**: Always use custom domains with SSL/TLS certificates (automatic with Klutch.sh)
  3. **Environment Variables**: Never commit secrets to Git
    Terminal window
    # Use .gitignore
    .env
    .env.local
    .env.production
  4. **User Permissions**: Be selective about administrator access
  5. **Public Access**: Consider whether your instance should be publicly accessible or behind authentication

Performance Optimization

  1. **Compute Resources**: Monitor memory usage (should stay under 50MB for typical usage)
    Terminal window
    # Recommended starting resources
    CPU: Shared (1 vCPU)
    Memory: 512MB RAM
  2. **Volume Size Planning**: 
    Data Volume: Start with 1GB, grow as needed
    Backup Volume: 2x data volume size
  3. **Image Optimization**: Enable S3 storage for better performance with many media files
  4. **Caching**: Ech0 includes built-in caching for optimal response times
  5. **Database Maintenance**: SQLite is self-maintaining, but consider periodic vacuum operations for large databases

Monitoring & Health Checks

Ech0 provides health check endpoints:

Terminal window
# Health check endpoint
curl https://your-app-name.klutch.sh/api/health


# Expected response
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "database": "connected",
  "uptime": "72h30m"
}

Monitor these metrics:

  • Response time (should be < 100ms for most requests)
  • Memory usage (< 50MB typical)
  • Volume usage (check data and backup volumes)
  • Federation connectivity (if using ActivityPub)

Backup Strategy

Implement a comprehensive backup strategy:

Daily Automated Backups:

Terminal window
BACKUP_ENABLED=true
BACKUP_INTERVAL=24h

Weekly Manual Backups:

  • Export full snapshots through web interface
  • Store off-site (download to local machine)

Volume Snapshots:

  • Create Klutch.sh volume snapshots before major changes
  • Keep at least 3 rolling snapshots

Disaster Recovery:

  • Test restore procedures quarterly
  • Document recovery steps
  • Keep SQLite database backup accessible

Scaling Considerations

Ech0 is designed for personal use with minimal scaling needs:

Vertical Scaling:

  • Increase compute resources if experiencing performance issues
  • Typical installations rarely need more than 512MB RAM

Volume Expansion:

  • Expand data volume as content grows (easy through Klutch.sh dashboard)
  • Monitor volume usage and expand before reaching 80% capacity

Multi-Instance (Advanced):

  • Ech0 uses SQLite, which doesn’t support multi-instance write operations
  • For high-availability, consider read-replicas with custom setup
  • Not recommended unless you have advanced database replication experience

Updates & Maintenance

Keep your Ech0 instance updated:

  1. **Check for updates** at the Ech0 releases page
  2. **Create a backup** before updating:
    Terminal window
    # Through web interface
    Settings → Data Management → Create Snapshot
  3. **Update your Dockerfile** if using official image: 
    FROM sn0wl1n/ech0:v3.0.4  # Pin specific version
  4. **Rebuild and redeploy** on Klutch.sh:
    Terminal window
    git add Dockerfile
    git commit -m "Update Ech0 to v3.0.4"
    git push origin main
  5. **Verify functionality** after update

Troubleshooting

App Won’t Start

Symptoms: Container fails to start or crashes immediately

Solutions:

  1. Check logs in Klutch.sh dashboard under **Logs** tab
  2. Verify environment variables are set correctly:
    Terminal window
    # Required variable
    JWT_SECRET=your-secret-key
  3. Ensure volumes are properly mounted: 
    /app/data → Data volume
    /app/backup → Backup volume
  4. Check port configuration (internal port must be 6277)

Cannot Access Ech0

Symptoms: URL returns 502 or 503 errors

Solutions:

  1. Verify app is running in Klutch.sh dashboard
  2. Check health endpoint:
    Terminal window
    curl https://your-app-name.klutch.sh/api/health
  3. Ensure traffic type is set to **HTTP** (not TCP)
  4. Wait 2-3 minutes after deployment for services to initialize
  5. Check for firewall or network restrictions

Database Corruption

Symptoms: Data not loading, SQLite errors in logs

Solutions:

  1. Stop the application
  2. Restore from latest backup:
    Terminal window
    # Through Klutch.sh volume browser
    Navigate to /app/backup
    Copy latest backup to /app/data
  3. If no backup available, try SQLite recovery:
    Terminal window
    # Access volume through Klutch.sh
    sqlite3 /app/data/ech0.db ".recover" > recovered.sql
  4. Restart application

Publishing Fails

Symptoms: “Contact Administrator” error when trying to publish

Solutions:

  1. Verify user has publishing permissions: 
    Settings → User Management → Check user permissions
  2. Ensure you're logged in as administrator (first registered user)
  3. Check disk space in data volume:
    Terminal window
    # In Klutch.sh dashboard
    Volumes → Check usage percentage
  4. Review logs for specific error messages

ActivityPub Federation Not Working

Symptoms: Cannot connect with other instances, federation errors

Solutions:

  1. Verify custom domain is properly configured:
    Terminal window
    # Must use custom domain (not .klutch.sh)
    SERVER_ADDRESS=https://yourdomain.com
  2. Check DNS propagation:
    Terminal window
    dig yourdomain.com CNAME
  3. Verify SSL certificate is active (automatic with Klutch.sh)
  4. Test WebFinger endpoint:
    Terminal window
    curl https://yourdomain.com/.well-known/webfinger
  5. Restart app after setting `SERVER_ADDRESS`

Connects Not Displaying

Symptoms: Some federated connections don’t show up

Solutions:

  1. This is normal behavior - Ech0 fetches instance info on-demand
  2. Unreachable or offline instances are automatically filtered out
  3. Check if remote instances are online:
    Terminal window
    curl https://remote-instance.com/api/health
  4. Try removing and re-adding the connection

High Memory Usage

Symptoms: Memory usage exceeds 100MB

Solutions:

  1. This is unusual for Ech0 - check for issues:
    Terminal window
    # Review logs for memory leaks
  2. Verify no large media files in local storage (use S3 instead)
  3. Restart the application to clear memory
  4. Increase compute resources if consistently high: 
    Upgrade to: 1 vCPU, 1GB RAM

Backup/Restore Issues

Symptoms: Cannot create or restore backups

Solutions:

  1. Verify backup volume is mounted and has space: 
    Mount Path: /app/backup
    Available Space: Check in Volumes dashboard
  2. Check write permissions on backup volume
  3. Manual backup as alternative:
    Terminal window
    # Download database directly
    Navigate to Volumes → Download /app/data/ech0.db
  4. If restore doesn't show new data, manually restart container

S3 Media Upload Failures

Symptoms: Images fail to upload with S3 enabled

Solutions:

  1. Verify S3 credentials are correct:
    Terminal window
    S3_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
    S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  2. Ensure bucket has public read access
  3. Check endpoint format (no http:// or https:// prefix):
    Terminal window
    S3_ENDPOINT=s3.amazonaws.com  # Correct
    S3_ENDPOINT=https://s3.amazonaws.com  # Wrong
  4. Verify bucket region matches configuration:
    Terminal window
    S3_REGION=us-east-1
  5. Test S3 connection with AWS CLI or SDK

RSS Feed Not Working

Symptoms: RSS URL returns 404 or empty feed

Solutions:

  1. Verify correct RSS URL format: 
    https://your-app-name.klutch.sh/rss/user/@username
    https://your-app-name.klutch.sh/rss/public
  2. Ensure posts are published (not drafts)
  3. Check if content visibility is set to public
  4. Test URL in browser before adding to RSS reader

Additional Resources

Congratulations! You’ve successfully deployed Ech0 on Klutch.sh. You now have a lightweight, self-hosted federated publishing platform ready to share your thoughts with the world. Remember to configure your JWT secret, set up backups, and enjoy distraction-free writing! 🚀