docs: standardize README and add repository documentation guide
This commit is contained in:
@@ -4,29 +4,7 @@ RadioSync Hub is a self-hosted podcast synchronization service for selected Poli
|
||||
|
||||
The project is designed to run on a home server or Raspberry Pi using Docker.
|
||||
|
||||
## Supported stations
|
||||
|
||||
### Radio 357
|
||||
|
||||
- Fetches podcast metadata from the Radio 357 content API.
|
||||
- Performs an initial metadata index of the available catalogue.
|
||||
- On later synchronizations, stops when it reaches a page containing only known episodes.
|
||||
- Retrieves protected audio URLs separately using an authenticated gateway.
|
||||
- Stores and refreshes the Radio 357 access token.
|
||||
|
||||
### Radio Nowy Świat
|
||||
|
||||
- Fetches programme and episode pages from the station website.
|
||||
- Uses a logged-in web session for patron-only content.
|
||||
- Stores the authenticated cookies securely in the local database.
|
||||
- Synchronizes recent episodes before gradually backfilling older pages.
|
||||
- Uses an adaptive cooldown for programmes that publish infrequently.
|
||||
- Retries request timeouts up to three times with a 30-second delay.
|
||||
- Reports unavailable episode players as warnings instead of failing the entire synchronization.
|
||||
|
||||
### Radio Jazz FM
|
||||
|
||||
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.
|
||||
[Features](#features) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Usage](#usage) · [Architecture](#architecture) · [Limitations](#limitations) · [Development](#development) · [Documentation](#documentation) · [Credits](#credits) · [License](#license)
|
||||
|
||||
## Features
|
||||
|
||||
@@ -44,35 +22,39 @@ Radio Jazz FM is treated as a catalogue of public RSS feeds. The service discove
|
||||
- Encrypted configuration values in SQLite, including passwords, tokens, and cookies.
|
||||
- Docker Compose deployment.
|
||||
|
||||
### Supported stations
|
||||
|
||||
#### Radio 357
|
||||
|
||||
- Fetches podcast metadata from the Radio 357 content API.
|
||||
- Performs an initial metadata index of the available catalogue.
|
||||
- On later synchronizations, stops when it reaches a page containing only known episodes.
|
||||
- Retrieves protected audio URLs separately using an authenticated gateway.
|
||||
- Stores and refreshes the Radio 357 access token.
|
||||
|
||||
#### Radio Nowy Świat
|
||||
|
||||
- Fetches programme and episode pages from the station website.
|
||||
- Uses a logged-in web session for patron-only content.
|
||||
- Stores the authenticated cookies securely in the local database.
|
||||
- Synchronizes recent episodes before gradually backfilling older pages.
|
||||
- Uses an adaptive cooldown for programmes that publish infrequently.
|
||||
- Retries request timeouts up to three times with a 30-second delay.
|
||||
- Reports unavailable episode players as warnings instead of failing the entire synchronization.
|
||||
|
||||
#### Radio Jazz FM
|
||||
|
||||
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.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Docker Engine
|
||||
- Docker Compose
|
||||
- A Gitea or Git server is optional and only needed for source-code hosting
|
||||
|
||||
## Configuration
|
||||
## Getting started
|
||||
|
||||
Create a local `.env` file next to `docker-compose.yml`:
|
||||
|
||||
```env
|
||||
RADIOSYNC_SECRET_KEY=generate-a-long-random-value
|
||||
RADIOSYNC_CONFIG_KEY=generate-a-fernet-key
|
||||
```
|
||||
|
||||
Generate the values with:
|
||||
|
||||
```bash
|
||||
python -c "import secrets; print(secrets.token_urlsafe(48))"
|
||||
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
The repository includes `.env.example` as a template. Never commit `.env`, the SQLite database, or the contents of `data/`.
|
||||
|
||||
## Running with Docker
|
||||
First complete [Configuration](#configuration), then start the service:
|
||||
|
||||
The repository contains `docker-compose.example.yml` as a portable default configuration. Copy it to `docker-compose.yml` before starting the service:
|
||||
|
||||
@@ -108,7 +90,29 @@ docker compose down
|
||||
|
||||
The `data/` directory is mounted as a Docker volume, so the database survives container rebuilds.
|
||||
|
||||
## Dashboard and feeds
|
||||
## Configuration
|
||||
|
||||
Copy `.env.example` to `.env` in the repository root, then set both keys:
|
||||
|
||||
```dotenv
|
||||
RADIOSYNC_SECRET_KEY=generate-a-long-random-value
|
||||
RADIOSYNC_CONFIG_KEY=generate-a-fernet-key
|
||||
```
|
||||
|
||||
Generate the values with Python 3 (only needed for this setup step):
|
||||
|
||||
```bash
|
||||
python3 -c "import secrets; print(secrets.token_urlsafe(48))"
|
||||
python3 -c "import base64, secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
The repository includes `.env.example` as a template. Never commit `.env`, the SQLite database, or the contents of `data/`.
|
||||
|
||||
## Usage
|
||||
|
||||
The dashboard allows you to:
|
||||
|
||||
@@ -130,7 +134,7 @@ Available feed endpoints:
|
||||
|
||||
Station names are `radio357`, `rns`, and `jazz`.
|
||||
|
||||
## Diagnostics
|
||||
### Diagnostics
|
||||
|
||||
Unexpected responses are recorded with a diagnostic code such as:
|
||||
|
||||
@@ -144,7 +148,7 @@ 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.
|
||||
|
||||
## Project structure
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
.
|
||||
@@ -167,7 +171,7 @@ When possible, the response is saved under `data/diagnostics/` for investigation
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
## Important limitations
|
||||
## 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.
|
||||
|
||||
@@ -192,6 +196,14 @@ The application currently has no dedicated automated test suite. At minimum, val
|
||||
python -m py_compile main.py core/*.py core/scrapers/*.py
|
||||
```
|
||||
|
||||
## Collaboration with AI
|
||||
## Documentation
|
||||
|
||||
[README style guide](docs/README-STYLE.md).
|
||||
|
||||
## Credits
|
||||
|
||||
This project was developed with assistance from GitHub Copilot. Human decisions, configuration, deployment, and responsibility for running the service remain with the project owner.
|
||||
|
||||
## License
|
||||
|
||||
No project-level license file is currently included in this repository. Third-party components retain their own licenses.
|
||||
|
||||
Reference in New Issue
Block a user