Self-Hosting Guide

Get FeedFerret running on your own server in minutes.

Quick Start with Docker

The fastest way to get FeedFerret running.

Make sure Docker and Docker Compose are installed.

Create a new directory and add a docker-compose.yml:

version: "3.8"

services:
  feedferret:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: feedferret
    restart: always
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=file:/app/data/dev.db
      - AUTH_SECRET=${AUTH_SECRET}
      - AUTH_TRUST_HOST=true
      - NEXTAUTH_URL=http://localhost:3000
    volumes:
      - feedferret_data:/app/data

volumes:
  feedferret_data:

Generate a secret and start the services:

export AUTH_SECRET=$(openssl rand -base64 32)
docker-compose up -d --build

Open http://localhost:3000 and create your first account.

Environment Variables

Configure FeedFerret to your needs.

Variable	Default	Description
DATABASE_URL	file:/app/data/dev.db	Path to SQLite database file
AUTH_SECRET	-	Secret for session encryption (required)
NEXTAUTH_URL	http://localhost:3000	Public URL of your instance
GOOGLE_CLIENT_ID	-	Google OAuth client ID (optional)
GOOGLE_CLIENT_SECRET	-	Google OAuth client secret (optional)
GITHUB_ID	-	GitHub OAuth app ID (optional)
GITHUB_SECRET	-	GitHub OAuth app secret (optional)

Background Sync

FeedFerret syncs feeds automatically — no external cron needed.

An in-process scheduler refreshes feeds on boot. It respects each feed's update frequency (per-feed → category → user → 60 min default).

Variable	Default	Description
BACKGROUND_SYNC_INTERVAL_MINUTES	5	How often the scheduler ticks
DISABLE_BACKGROUND_SYNC	unset	Set to true for external cron
SYNC_SECRET	unset	Bearer token for /api/sync endpoint

If you run multiple replicas, disable the built-in scheduler and use an external cron:

DISABLE_BACKGROUND_SYNC=true
SYNC_SECRET=$(openssl rand -hex 32)
# crontab:
# */5 * * * * curl -fsS -H "Authorization: Bearer $SYNC_SECRET" https://your.host/api/sync

Local Development

Run FeedFerret from source for development.

Node.js 20+, pnpm, SQLite (built-in)

Clone the repository and install dependencies:

git clone https://github.com/moby3012/feedferret.git
cd feedferret
pnpm install

Create a .env file:

DATABASE_URL="file:./prisma/dev.db"
NEXTAUTH_SECRET="your-super-secret-key"
NEXTAUTH_URL="http://localhost:3000"

Initialize the database:

pnpm exec prisma db push
pnpm exec prisma generate

Start the dev server:

pnpm run dev

Tech Stack

Framework

Next.js (App Router)

Auth

Auth.js (NextAuth v5)

Database

Prisma + SQLite

Styling

Tailwind CSS + shadcn/ui

State

TanStack Query

FeedFerret on GitHub

github.com/moby3012/feedferret