126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# fast-website
|
|
|
|
Lightweight, SEO-first website for SanthoshJ that aggregates YouTube + Instagram + podcast content and tracks conversion events via Umami.
|
|
|
|
## Local Setup
|
|
|
|
```bash
|
|
cd site
|
|
cp .env.example .env
|
|
npm install
|
|
npm run fetch-content
|
|
npm run dev
|
|
```
|
|
|
|
Open `http://localhost:4321`.
|
|
|
|
## Configuration
|
|
|
|
All configuration is via environment variables (see `site/.env.example`).
|
|
|
|
### YouTube
|
|
|
|
- `YOUTUBE_CHANNEL_ID` is required for ingestion.
|
|
- Optional: `YOUTUBE_API_KEY` enables view-count ingestion for high-performing ranking.
|
|
|
|
Notes:
|
|
- The channel ID looks like `UC...` and can be found by viewing the channel page source or via YouTube Studio settings.
|
|
- If `YOUTUBE_API_KEY` is not set, ingestion falls back to the public channel RSS feed and metrics will be missing.
|
|
|
|
### Podcast
|
|
|
|
- `PODCAST_RSS_URL` is required to ingest episodes.
|
|
|
|
### Instagram (Embed-First)
|
|
|
|
Edit `site/content/instagram-posts.json`:
|
|
|
|
```json
|
|
{
|
|
"posts": [
|
|
{ "url": "https://www.instagram.com/p/<id>/", "publishedAt": "2026-02-01T00:00:00Z", "title": "Movie post" }
|
|
]
|
|
}
|
|
```
|
|
|
|
Phase 2 (API ingestion) path:
|
|
- Requires Meta developer app setup, correct account type, token issuance + refresh, and platform policy compliance.
|
|
- Recommended approach: keep embed-first for v1, then add an optional API ingest module when constraints are clear.
|
|
|
|
### Curation / Featured Videos
|
|
|
|
If YouTube metrics are not available, curate high-performing videos in `site/content/featured-videos.json`:
|
|
|
|
```json
|
|
{ "videoIds": ["abc123", "def456"] }
|
|
```
|
|
|
|
## Analytics (Umami)
|
|
|
|
Set:
|
|
- `PUBLIC_UMAMI_SCRIPT_URL`
|
|
- `PUBLIC_UMAMI_WEBSITE_ID`
|
|
|
|
If either is missing, analytics is disabled and the site still functions.
|
|
|
|
Event tracking is implemented using Umami's `data-umami-event` and `data-umami-event-*` attributes.
|
|
|
|
## Click Tracking Taxonomy (Umami-Compatible)
|
|
|
|
All tracked clickables MUST set:
|
|
- `data-umami-event`: the event name (max 50 chars), e.g. `click`, `cta_click`, `outbound_click`
|
|
- `data-umami-event-target_id`: stable unique identifier for the clickable element (namespaced like `nav.*`, `cta.*`, `card.*`)
|
|
- `data-umami-event-placement`: where the clickable appears (e.g. `nav`, `hero`, `section_header`, `home.newest`)
|
|
|
|
For links, also set:
|
|
- `data-umami-event-target_url`: destination URL (can be relative for internal navigation)
|
|
|
|
Common additional properties:
|
|
- `data-umami-event-domain`: destination domain (for outbound links)
|
|
- `data-umami-event-source`: `youtube` / `instagram` / `podcast` where applicable
|
|
- `data-umami-event-ui_placement`: a sub-placement for UI grouping (e.g. `content_card`)
|
|
|
|
Instrumentation checklist:
|
|
- Every clickable should have a unique `target_id` so it can be segmented in Umami.
|
|
- Use categorical ids and placements only (no PII).
|
|
|
|
## Deployment (Linode + Docker)
|
|
|
|
The production host is intentionally minimal and only needs Docker (no Node.js on the server).
|
|
|
|
### Local Docker
|
|
|
|
```bash
|
|
docker compose build
|
|
docker compose up -d
|
|
```
|
|
|
|
The container serves the static output on port `8080` (map or proxy as needed).
|
|
|
|
### Production (Docker-Only Host)
|
|
|
|
In production, CI builds and publishes a Docker image (nginx serving the static output). The server updates by pulling that image and restarting the service.
|
|
|
|
Runbook: `deploy/runbook.md`.
|
|
|
|
### Refreshing Content (Manual, Docker-Only)
|
|
|
|
Content is fetched at build time into `site/content/cache/content.json` (typically in CI), then packaged into the image.
|
|
|
|
On the server host:
|
|
|
|
```bash
|
|
./scripts/refresh.sh
|
|
```
|
|
|
|
This:
|
|
1. Pulls the latest published image
|
|
2. Restarts the service (no build on the host)
|
|
|
|
### Refreshing Content (Scheduled)
|
|
|
|
Install a daily cron using `deploy/cron.example` as a starting point.
|
|
|
|
Rollback:
|
|
- Re-deploy a known-good image tag/digest (see `deploy/runbook.md`).
|