Sparkle RSS

setup

Deploy your own Sparkle RSS

Sparkle RSS is infrastructure as code. Spin up the whole stack — database, sync API, ingestion pipeline, web reader, auth — on your own AWS account, then point any Google Reader–compatible client at it. Rough numbers: a few cloud resources, one pipeline, about an hour.

01

Prereqs on your machine

Node 22, pnpm 10 (corepack enable), Terraform >= 1.10, the AWS CLI v2, and Docker (for the local Postgres used in development). You also need an AWS account and the domain whose Route 53 hosted zone you'll publish under. 

node --version   # v22+
pnpm --version  # 10.x
terraform --version  # >= 1.10
02

Clone and install

Clone the repo and install dependencies with pnpm. The workspace includes the API, the web reader, the domain packages, and every tool. 

git clone https://github.com/rewdy/sparkle-rss.git
cd sparkle-rss
pnpm install
03

Configure for your account

Deployment is a single, fork-friendly config. Edit tf/terraform.tfvars (backed by tf/variables.tf): set your app_domain, whether to publish the marketing site, and sign-up policy. Terraform state lives in S3, configured inline in tf/main.tf — point it at your own bucket. No env vars or extra backend files. 

# tf/terraform.tfvars
app_domain   = "app.example.com"
deploy_site  = false   # most forks run app-only
allow_signups = true   # or keep invite-only
04

Deploy

Push to main and the GitHub Actions pipeline takes over: lint, typecheck, tests, a terraform apply that creates the whole stack, DB migrations, and publish of the web reader. No long-lived AWS keys — deploys use GitHub OIDC. 

# everything below happens automatically on push to main:
# terraform apply → migrations → s3 sync + CloudFront invalidation
05

Add a user and connect

Users are invite-only. Create one via the AWS CLI (Cognito admin-create-user), sign in at your reader, and mint a per-user API token from the settings page. Then add the server in any Google Reader–compatible app. 

Server URL:  https://your-reader.example/api/greader.php
Username:    you@example.com
Password:    your srk_… API token (from Settings)

This is the shape of a deploy, not a line-by-line walkthrough — the repo's docs/ directory is the full, living setup guide and is kept current with the code. Costs typically land around $5–12/month, near-zero when idle.

fork it on GitHub