neiam /feedpug

feedpub

public · Issues · Pulls · Labels · Forks · Compare · Actions success · Badges · Packages

docs: write real README (overview, features, quickstart, container images)

d5046af · gmorell · 2026-06-27 15:53

1 files +67 -11

Files changed

modified README.md

+67 −11

@@ -1,18 +1,74 @@

1	1	# FeedPug
2	2
3		−To start your Phoenix server:
	3	+A self-hosted RSS/Atom feed reader. Subscribe to feeds, organize them into
	4	+groups, react to items, and read from the web UI or a JSON API. Feeds are
	5	+globally deduped and fetched once no matter how many people follow them.
	6	+Phoenix LiveView on top of PostgreSQL, with background fetching via Oban.
4	7
5		−* Run `mix setup` to install and setup dependencies
6		−* Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
	8	+## Features
7	9
8		−Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
	10	+- Newsfeed — a unified reading view at `/` (Phoenix LiveView) with
	11	+ read / unread tracking.
	12	+- Shared, deduped feeds — feeds are canonical and deduped by URL, items
	13	+ by `{feed_id, guid}`, so a feed followed by many people is fetched and
	14	+ stored exactly once.
	15	+- Groups — organize your subscriptions into groups (`/groups`).
	16	+- Discover & follow — find and follow new feeds at `/discover`.
	17	+- Reactions — react to individual items.
	18	+- OPML — import and export your subscriptions (`/opml/export`).
	19	+- JSON API — `/api/*` for timelines, items, sources, groups, follows,
	20	+ and reactions — handy for companion apps and devices (`/devices`).
	21	+- Background fetching — Oban workers keep feeds up to date.
	22	+- Accounts — magic-link login by default, password optional, with
	23	+ invite-gated registration (`/users/invites`).
	24	+- Themes — pick a daisyUI theme; the choice persists.
9	25
10		−Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
	26	+## Quick start
11	27
12		−## Learn more
	28	+```sh
	29	+# 1. Bring up Postgres (see compose.yml)
	30	+podman compose up -d # or: docker compose up -d
13	31
14		−* Official website: https://www.phoenixframework.org/
15		−* Guides: https://hexdocs.pm/phoenix/overview.html
16		−* Docs: https://hexdocs.pm/phoenix
17		−* Forum: https://elixirforum.com/c/phoenix-forum
18		−* Source: https://github.com/phoenixframework/phoenix
	32	+# 2. Install deps, create + migrate the dev DB, build assets
	33	+mix setup
	34	+
	35	+# 3. Start the dev server
	36	+mix phx.server
	37	+```
	38	+
	39	+Then open <http://localhost:4000>.
	40	+
	41	+## Container images
	42	+
	43	+CI publishes a multi-registry image on every push to `master`:
	44	+
	45	+- `ghcr.io/neiam/feedpug`
	46	+- `docker.io/neiam/feedpug`
	47	+- `quay.io/neiam/feedpug`
	48	+
	49	+Tags: `latest` (default branch), `vX.Y.Z` + `X.Y` (git tags), the branch name,
	50	+and the commit SHA.
	51	+
	52	+```sh
	53	+docker pull ghcr.io/neiam/feedpug:latest
	54	+
	55	+docker run --rm -p 4000:4000 \
	56	+ -e PHX_SERVER=true \
	57	+ -e SECRET_KEY_BASE="$(openssl rand -base64 48)" \
	58	+ -e PHX_HOST=localhost \
	59	+ -e POSTGRES_HOST=host.containers.internal \
	60	+ -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=feed_pug \
	61	+ ghcr.io/neiam/feedpug:latest
	62	+```
	63	+
	64	+Or set `DATABASE_URL=ecto://user:pass@host/db` instead of the discrete
	65	+`POSTGRES_*` variables.
	66	+
	67	+## Tests
	68	+
	69	+```sh
	70	+mix test
	71	+mix precommit # compile --warnings-as-errors, deps.unlock --unused, format, test
	72	+```
	73	+
	74	+`mix precommit` is what CI runs and what every change should pass.

Parents: 2e92cf0