docs: refine README presentation and streamline setup guide
This commit is contained in:
@@ -1,29 +1,61 @@
|
||||
# RadioSync Hub
|
||||
|
||||
RadioSync Hub is a self-hosted podcast synchronization service for selected Polish radio stations. It collects podcast metadata, retrieves protected audio URLs where supported, stores the local catalogue, and exposes podcast feeds for compatible clients.
|
||||
|
||||
|
||||
The project is designed to run on a home server or Raspberry Pi using Docker.
|
||||
**Your radio catalogue, ready for your podcast player.** A self-hosted service that collects podcast metadata from selected Polish radio stations, retrieves protected audio URLs where supported, and exposes feeds for compatible clients.
|
||||
|
||||
[Features](#features) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Usage](#usage) · [Architecture](#architecture) · [Limitations](#limitations) · [Development](#development) · [Documentation](#documentation) · [Credits](#credits) · [License](#license)
|
||||
| Project | Deployment | Storage | Output |
|
||||
| --- | --- | --- | --- |
|
||||
| Self-hosted service | Docker Compose | SQLite | RSS + OPML |
|
||||
|
||||
<p align="center">
|
||||
<a href="#getting-started"><strong>Get started</strong></a> ·
|
||||
<a href="#supported-stations">Supported stations</a> ·
|
||||
<a href="#configuration">Configure</a> ·
|
||||
<a href="#usage">Use your feeds</a>
|
||||
</p>
|
||||
|
||||
Designed for a home server or Raspberry Pi. Station credentials and synchronization are managed from the web dashboard.
|
||||
|
||||
<details>
|
||||
<summary>Browse all sections</summary>
|
||||
|
||||
- [Features](#features)
|
||||
- [Requirements](#requirements)
|
||||
- [Getting started](#getting-started)
|
||||
- [Configuration](#configuration)
|
||||
- [Usage](#usage)
|
||||
- [Architecture](#architecture)
|
||||
- [Limitations](#limitations)
|
||||
- [Development](#development)
|
||||
- [Documentation](#documentation)
|
||||
- [Credits](#credits)
|
||||
- [License](#license)
|
||||
|
||||
</details>
|
||||
|
||||
## Features
|
||||
|
||||
- FastAPI web dashboard.
|
||||
- Automatic synchronization using APScheduler.
|
||||
- Manual full-station and single-programme synchronization.
|
||||
- SQLite storage through SQLAlchemy.
|
||||
- RSS feeds generated for locally synchronized episodes.
|
||||
- Master and station-specific OPML files.
|
||||
- Error and warning tracking with acknowledgement from the dashboard.
|
||||
- Grouping of repeated errors and warnings.
|
||||
- Diagnostic snapshots for unexpected API or HTML responses.
|
||||
- ntfy notifications for synchronization errors.
|
||||
- CSRF protection for dashboard actions.
|
||||
- Encrypted configuration values in SQLite, including passwords, tokens, and cookies.
|
||||
- Docker Compose deployment.
|
||||
| Capability | Included behavior |
|
||||
| --- | --- |
|
||||
| **Collect** | Scheduled synchronization with APScheduler; manual station or programme sync. |
|
||||
| **Subscribe** | RSS for synchronized episodes; master and station-specific OPML files. |
|
||||
| **Manage** | FastAPI dashboard, error acknowledgement, and grouped errors and warnings. |
|
||||
| **Diagnose** | Response snapshots for unexpected API or HTML responses; ntfy error notifications. |
|
||||
| **Store** | SQLite through SQLAlchemy; encrypted passwords, tokens, and cookies. |
|
||||
| **Deploy** | Docker Compose with persistent local data; CSRF protection for dashboard actions. |
|
||||
|
||||
### Supported stations
|
||||
|
||||
| Station | Catalogue and feeds | Access |
|
||||
| --- | --- | --- |
|
||||
| **Radio 357** | API metadata with an initial catalogue index and incremental sync. | Authentication for protected audio URLs. |
|
||||
| **Radio Nowy Świat** | Programme and episode pages; recent sync followed by older catalogue backfill. | Logged-in session for patron-only content. |
|
||||
| **Radio Jazz FM** | Discovery of public programme RSS feeds; links to the station's original feeds. | Public feeds. |
|
||||
|
||||
<details>
|
||||
<summary>Station-specific synchronization details</summary>
|
||||
|
||||
#### Radio 357
|
||||
|
||||
- Fetches podcast metadata from the Radio 357 content API.
|
||||
@@ -46,6 +78,8 @@ The project is designed to run on a home server or Raspberry Pi using Docker.
|
||||
|
||||
Radio Jazz FM is treated as a catalogue of public RSS feeds. The service discovers available programmes and links directly to the original feeds hosted by the station.
|
||||
|
||||
</details>
|
||||
|
||||
## Requirements
|
||||
|
||||
- Docker Engine
|
||||
@@ -54,41 +88,43 @@ Radio Jazz FM is treated as a catalogue of public RSS feeds. The service discove
|
||||
|
||||
## Getting started
|
||||
|
||||
First complete [Configuration](#configuration), then start the service:
|
||||
### Prepare the local files
|
||||
|
||||
The repository contains `docker-compose.example.yml` as a portable default configuration. Copy it to `docker-compose.yml` before starting the service:
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
cp docker-compose.example.yml docker-compose.yml
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
The copied `docker-compose.yml` is ignored by Git, so it can be customized locally without affecting the public repository. The example exposes port `8000` directly, which is convenient for a local installation.
|
||||
Both local configuration files are ignored by Git. The Compose example exposes port `8000` directly.
|
||||
|
||||
Build and start the service:
|
||||
### Set your keys
|
||||
|
||||
Follow [Configuration](#configuration) to generate and set both keys in `.env` before starting the service.
|
||||
|
||||
### Start the service
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Open the dashboard at:
|
||||
**Open the dashboard:** [http://localhost:8000](http://localhost:8000), or your server's address on port `8000`. Configure station credentials in the dashboard.
|
||||
|
||||
```text
|
||||
http://localhost:8000
|
||||
```
|
||||
The `data/` directory is mounted into the container, so the database survives container rebuilds.
|
||||
|
||||
View container logs:
|
||||
<details>
|
||||
<summary>View logs or stop the service</summary>
|
||||
|
||||
```bash
|
||||
# Follow application logs
|
||||
docker compose logs -f radiosync
|
||||
```
|
||||
|
||||
Stop the service:
|
||||
|
||||
```bash
|
||||
# Stop the service
|
||||
docker compose down
|
||||
```
|
||||
|
||||
The `data/` directory is mounted as a Docker volume, so the database survives container rebuilds.
|
||||
</details>
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -108,7 +144,7 @@ python3 -c "import base64, secrets; print(base64.urlsafe_b64encode(secrets.token
|
||||
|
||||
`RADIOSYNC_SECRET_KEY` signs browser sessions. `RADIOSYNC_CONFIG_KEY` encrypts sensitive values stored in SQLite.
|
||||
|
||||
Keep both keys safe and do not change them after the application has stored credentials. Losing or changing the encryption key makes existing encrypted configuration unreadable.
|
||||
> **Keep your keys** — Back up both keys and keep them stable after storing credentials. Losing or changing `RADIOSYNC_CONFIG_KEY` makes existing encrypted configuration unreadable.
|
||||
|
||||
The repository includes `.env.example` as a template. Never commit `.env`, the SQLite database, or the contents of `data/`.
|
||||
|
||||
@@ -136,6 +172,9 @@ Station names are `radio357`, `rns`, and `jazz`.
|
||||
|
||||
### Diagnostics
|
||||
|
||||
<details>
|
||||
<summary>Diagnostic codes and response snapshots</summary>
|
||||
|
||||
Unexpected responses are recorded with a diagnostic code such as:
|
||||
|
||||
- `HTTP_ERROR`
|
||||
@@ -148,8 +187,19 @@ Unexpected responses are recorded with a diagnostic code such as:
|
||||
|
||||
When possible, the response is saved under `data/diagnostics/` for investigation. Diagnostic snapshots can contain website HTML and should be treated as local operational data.
|
||||
|
||||
</details>
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
Station APIs / websites → Scrapers → Local SQLite catalogue → RSS / OPML
|
||||
↑
|
||||
Scheduler + web dashboard
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Repository layout</summary>
|
||||
|
||||
```text
|
||||
.
|
||||
├── core/
|
||||
@@ -171,6 +221,8 @@ When possible, the response is saved under `data/diagnostics/` for investigation
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Limitations
|
||||
|
||||
This project relies on unofficial endpoints and the current HTML structure of the station websites. The stations may change those interfaces without notice. The scrapers therefore validate responses, retry transient failures, preserve existing data, and report unexpected changes through the dashboard and ntfy.
|
||||
@@ -198,7 +250,11 @@ python -m py_compile main.py core/*.py core/scrapers/*.py
|
||||
|
||||
## Documentation
|
||||
|
||||
[README style guide](docs/README-STYLE.md).
|
||||
| Reference | What you will find |
|
||||
| --- | --- |
|
||||
| [Environment example](.env.example) | Required application keys. |
|
||||
| [Compose example](docker-compose.example.yml) | Portable container deployment. |
|
||||
| [README style guide](docs/README-STYLE.md) | Shared documentation structure and presentation rules. |
|
||||
|
||||
## Credits
|
||||
|
||||
|
||||
Reference in New Issue
Block a user