Skip to content
NutsNews chestnut logoNutsNews Wiki

Simple guide · Overview

Page status: Active

Operations

This document explains how NutsNews is operated and maintained.

Visual overview

Primary diagram

System map

This document explains how NutsNews is operated and maintained.

Render the repository-owned system map when you need it.

Diagram is not rendered yet.

View as text
Operations

This document explains how NutsNews is operated and maintained.

flowchart LR
  accTitle: Operations
  accDescr {
    This document explains how NutsNews is operated and maintained.
  }
  edit["Operator updates markdown docs"] --> commit["Push commit to main"]
  commit --> ci["GitHub Actions wiki pipeline"]
  ci --> checks["Inventory and secret safety checks"]
  checks --> build["Jekyll build + budgets"]
  build --> publish["Pages artifact deployment"]
  publish --> dns["DNS CNAME + HTTPS check"]
  dns --> ok["Wiki route serving"]
  ok --> users["Readers and operators"]

  subgraph "Ops runtime"
    direction TB
    web["web app and admin routes"]
    api["/admin dashboards"]
    workers["Cloudflare Worker shards"]
    infra["VPS + backend rails"]
    web --> api
    api --> workers
    workers --> infra
  end

Operations

Fullscreen diagram view.

Operations

Section titled “Operations”

This article is how the NutsNews team runs and maintains the project.

Start with:

docs/NUTSNEWS_INFRA_OPERATIONS_PLATFORM.md

for:

  • VPS GitOps operating model
  • CI stability
  • Ops Portal goals
  • Home server support-node rules
  • email reports
  • provider migration strategy

Admin portal

Section titled “Admin portal”

The admin portal is at:

/admin

It is protected by Google login and an approved admin email allowlist.

Current admin routes:

/admin
/admin/articles
/admin/ai-usage
/admin/local-ai
/admin/shards
/admin/feed-health
/admin/feeds
/admin/login

Admin dashboards

Section titled “Admin dashboards”

Article Review

Section titled “Article Review”

Route:

/admin/articles

Use this to:

  • review recent article decisions
  • sort by review time
  • filter accepted/rejected decisions, source, category, and score
  • see rejection reasons
  • jump to original source and published story
  • investigate AI failures manually
  • confirm whether OpenAI, local AI, or local rules made each decision
  • check the saved model name for each review

Detailed guide:

docs/ADMIN_ARTICLE_REVIEWS.md

AI Usage

Section titled “AI Usage”

Route:

/admin/ai-usage

Use this to track:

  • OpenAI calls
  • prompt, completion, and total token usage
  • estimated spend
  • accepted/rejected review outcomes
  • cost-protection events
  • token spike warnings

Local AI

Section titled “Local AI”

Route:

/admin/local-ai

Use this to track:

  • Oracle-hosted local AI calls
  • qwen/Ollama model usage
  • accepted/rejected local decisions
  • local review latency
  • OpenAI fallback activity while local mode runs
  • recent local AI decision history
  • model-level quality comparisons while testing

Detailed guide:

docs/ORACLE_LOCAL_AI.md

Worker Shard Health

Section titled “Worker Shard Health”

Route:

/admin/shards

Use this to monitor:

  • shard freshness
  • failed or stale shards
  • latest errors
  • failed worker runs
  • feed counts
  • accepted/rejected counts
  • image hydration

Feed Health

Section titled “Feed Health”

Route:

/admin/feed-health

Use this to monitor:

  • RSS reliability
  • repeated failures
  • thumbnail coverage
  • accepted output
  • weak feeds
  • source quality comparisons

Feed Management

Section titled “Feed Management”

Route:

/admin/feeds

Use this to:

  • list RSS feeds
  • view 0-100 source scores
  • view source grades
  • enable/disable feeds
  • inspect source active state
  • fix bad sources without code deploys

Deployment checklist

Section titled “Deployment checklist”

Use:

docs/DEPLOYMENT_CHECKLIST.md

for releases of:

  • Vercel web app and previews
  • GHCR image publishing and VPS digest promotion
  • Cloudflare Worker shards
  • Controller Worker
  • Supabase migrations
  • Cloudflare cache changes
  • post-deploy checks

Quick check:

Terminal window
./scripts/post_deploy_verify.sh

With a specific article:

Terminal window
./scripts/post_deploy_verify.sh https://www.nutsnews.com /articles/<article-id>

Deployment model

Section titled “Deployment model”

Web

Section titled “Web”

The web app source is ramideltoro/nutsnews/web.

Vercel stays the primary production target and uses a Git-based build. GitHub Actions also publishes production OCI images to GHCR. Only ramideltoro/nutsnews-infra can promote immutable VPS digests.

The issue #67 state is prepared, not deployed. The VPS app, staged route, and public route are still disabled, and nutsnews.com stays on Vercel. See Dual-Target Web Deployment.

Common commands:

Terminal window
cd web
npm ci
npm run build

Worker shards

Section titled “Worker shards”

Generate Worker shard configs:

Terminal window
cd worker
npm run generate:wrangler

Deploy one shard:

Terminal window
npx wrangler deploy --config generated-wrangler/wrangler.shard0.jsonc

Deploy controller:

Terminal window
cd controller
npx wrangler deploy

Useful runtime checks

Section titled “Useful runtime checks”

Public site

Section titled “Public site”
Terminal window
curl -I "https://www.nutsnews.com/"

Article API

Section titled “Article API”
Terminal window
curl -s "https://www.nutsnews.com/api/articles?page=0"