Getting Started

Prerequisites

Docker and Docker Compose
Either Ollama (for a fully local, free setup) or an Anthropic API key (for cloud LLM processing) — see LLM Providers for the tradeoffs

1. Clone and configure

git clone https://github.com/ShoebillFeed/ShoebillFeed.git shoebill_feed
cd shoebill_feed
cp .env.example .env

Edit .env and set at minimum:

Variable	Description
`POSTGRES_PASSWORD`	Database password
`JWT_SECRET`	Random secret — generate with `openssl rand -hex 32`
`ADMIN_PASSWORD`	Initial admin account password
`LLM_PROVIDERS`	`ollama` or `anthropic` — see LLM Providers

The full variable reference can be found in Configuration.

2. Start the stack

docker compose up -d

This starts Postgres (with pgvector), Redis, the FastAPI backend, two Celery workers (fetch and LLM-processing queues), Celery Beat, and the frontend.

The app is served by the frontend container on port 80. Wire it up behind a reverse proxy (Traefik, Nginx — see Deployment), or for local testing without one, add a port mapping in docker-compose.yml:

frontend:
  ports:
    - "8080:80"

Then open http://localhost:8080.

3. Log in

Use the credentials from ADMIN_USERNAME/ADMIN_PASSWORD in your .env. To reset the admin password later, change ADMIN_PASSWORD and restart — the new password is applied automatically on startup.

4. Add your first categories

In Settings → Categories, define a few topics you care about — each needs a name, and optionally a color, keywords, and a prompt fragment giving the LLM extra context on what belongs in it. Don’t want to write them by hand? The “Default Categories” browser lets you pull ready-made ones from a built-in IPTC-based taxonomy instead. See User Guide for details.

5. Add your first source

In Settings → Sources, add an RSS feed, a subreddit, or any other source type (see Sources for the full list and each type’s exact configuration). Sources are fetched on a schedule (every 5 minutes by default) and new items are processed by the LLM shortly after.