# RSS Alchemy

## About

RSS Alchemy is a website-to-rss converter, like RSSHub, RSS-bridge or Rss.app. Here is the difference:

- Convert arbitrary website to RSS feed using CSS selectors
- Dynamic websites are supported using headless chrome (playwright)
- Cookies[^1] (supports scraping private feeds, eg youtube subscriptions)
- Proxy
- Results caching
- Screenshots (primarily for debugging)
- Stateless[^2] (all task parameters are encoded into url, no database needed)
- Distruibuted by design (deploy as many workers as you need)
- Self-hosted; easy to deploy; docker-compose provided
- Relatively small codebase, written in go + typescript

[^1]: Cookies require support from your RSS reader/aggregator. Miniflux works, others are not checked yet.
[^2]: Nats KV is used to store cookies permanently, it's required for sites that update cookies on every request, like
youtube

| feature/program      | RSS Alchemy               | RSS Hub                      | RSS-Bridge              | RSS.app       |
|----------------------|---------------------------|------------------------------|-------------------------|---------------|
| Custom websites      | ✅ (using CSS selectors)   | ❌ (only hardcoded site list) | ✅ (using CSS selectors) | ✅             |
| Render dynamic sites | ✅ (using headless chrome) | ❌                            | ❌                       | ✅             |
| Hosting              | Self-hosting              | Self-hosting                 | Self-hosting            | Only cloud    |
| Price                | Free and open-source      | Free and open-source         | Free and open-source    | Paid ($8/mon) |

## Project status

Program is still under development. The code architecture is not final, tests are missing, no CI, no demo page, no docs,
etc...

## Deployment

```bash
git clone https://github.com/egor3f/rssalchemy
cd rssalchemy/deploy
docker-compose up -d
```

Then open your browser targeting to port 8080.

For SSL, authentication, domains, etc. - use Caddy or Nginx (no specific configuration required). Personally I recommend Caddy, if you haven't used it before - give it a try :)

### Configuration

Configuration is done using [config.yml](config.yml) file or env vars 

Env vars always has precedence over config.yml

Docker-compose deployment uses [deploy/.env file](deploy/.env)

You can see all available options in [config.go file](internal/config/config.go) (struct Config)

### Scaling

Each worker can process 1 page at a time, so to scale you should run multiple worker instances. This is done using replicas parameter in worker section in [docker-compose.yml file](deploy/docker-compose.yml)

## Development

You need Go 1.23 (most of application), Node.js 20 (frontend) and Nats server.

Instaling dependencies example for MacOS:

```bash
brew install go@1.23
brew install node@20
brew install nats-server  # Don't use brew services to manage nats because it lacks config support
go mod download
cd frontend/wizard-vue && npm install
nats -js
```

Also this repository contains some useful git hooks. To enable them, use:
```bash
git config --local core.hooksPath .githooks/
```