Fayette County Public Libraries — Website & Staff Portal

Self-hosted. Zero dependencies on the host. No frameworks. No API keys. No CMS subscriptions. A production-grade public library website + staff content management portal serving Fayette County, West Virginia.

Admin API integration tests:
- cd admin && npm test
Docker-based test execution (no host npm required):
- docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile test run --rm fcpl-admin-test
Faster admin frontend/backend iteration without rebuilding image each edit:
- docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev up -d --build
- This mounts admin/server.js and admin/public directly into the running admin container.

1. Project Overview

What It Is

The FCPL Website & Staff Portal is a fully self-hosted web platform for Fayette County Public Libraries — a multi-branch public library system serving rural Fayette County, West Virginia. It replaces a legacy website with a modern, accessible, maintainable system that library staff can manage without any technical knowledge.

What Problem It Solves

_Problem	_Solution
_{Legacy CMS required vendor maintenance contracts}	_{Fully self-hosted on any Docker-capable server}
_{Staff needed technical skills to update content}	_{Browser-based admin portal — no coding needed}
_{Website inaccessible to patrons with disabilities}	_{WCAG 2.1 AA compliant throughout}
_{No content backup or audit trail}	_{Auto-backup + 60-day recycle bin + activity log}
_{Expensive hosted platform subscriptions}	_{Runs on a single VPS or local server, zero SaaS fees}
_{Slow page loads from heavy JavaScript frameworks}	_{Zero-framework static HTML — loads in milliseconds}

Who It Is For

Library staff — manage events, hours, announcements, programs, and content through a browser
Library patrons — find branch hours, upcoming events, digital resources, and library services
System administrators — deploy and maintain the site via Docker Compose on any Linux server
Developers — extend the static site or admin API with minimal toolchain overhead

Why It Exists

Rural public libraries often lack IT budgets for commercial CMS platforms. This project delivers enterprise-grade security, accessibility, content management, and disaster recovery in a simple Docker stack that any library director can hand off to a successor without technical debt.

2. Key Features

_Feature	_Description	_Impact	_Status
_{Zero-framework static site}	_{Pure HTML/CSS/JS — no React, Vue, or build pipeline}	_{Sub-100ms page loads; no Node.js needed on host}	_{✅ Live}
_{Browser-based CMS}	_{Staff manage all content via a tabbed SPA admin portal}	_{No coding or terminal access required for content changes}	_{✅ Live}
_{WCAG 2.1 AA Accessibility}	_{Skip links, ARIA labels, keyboard navigation, accessibility toolbar}	_{Usable by patrons on screen readers, elderly, and children}	_{✅ Live}
_{Multi-layer security}	_{Nginx + Express dual rate-limiting, bcrypt(12), JWT, Helmet.js}	_{Resistant to brute-force, XSS, clickjacking, CSRF, injection}	_{✅ Live}
_{Soft-delete recycle bin}	_{Deleted items recoverable for 60 days}	_{Prevents accidental permanent loss of content}	_{✅ Live}
_{Auto-backup before writes}	_{Snapshot of data files created before every destructive change}	_{One-click rollback to any previous state}	_{✅ Live}
_{Full audit log}	_{Every staff action logged with timestamp, IP, and detail}	_{Accountability and forensics for every content change}	_{✅ Live}
_{Self-signed / Let's Encrypt TLS}	_{Local: auto-generated self-signed cert. Production: Certbot script}	_{HTTPS on port 8443 out of the box}	_{✅ Live}
_{Image upload pipeline}	_{MIME-type validation, 5 MB cap, random filename on disk}	_{Prevents file-type spoofing and enumerable URLs}	_{✅ Live}
_{Interactive event calendar}	_{Dynamic calendar widget fed by events.json via API}	_{Patrons see accurate upcoming events in real-time}	_{✅ Live}
_{Bookmobile & Homebound pages}	_{Dedicated service pages for outreach programs}	_{Serves patrons who cannot visit branches in person}	_{✅ Live}
_{5-branch location maps}	_{OpenStreetMap embed with per-branch hours and directions}	_{Works without Google Maps API; no cost, no rate limits}	_{✅ Live}
_{Digital resources directory}	_{Staff-managed list of eBook/database links via admin portal}	_{Patron-facing resource page always stays current}	_{✅ Live}
_{Holiday closure management}	_{Staff check holiday checkboxes; changes live immediately}	_{Patrons never show up to a closed library}	_{✅ Live}
_{Docker Compose deployment}	_{Two-container stack: fcpl-site (Nginx) + fcpl-admin (Node.js)}	_{Deploy anywhere Docker runs — VPS, bare metal, local}	_{✅ Live}
_{Simple / No-JS Site}	_{JavaScript-free HTML 4.01 site at /simple/ for IE6–8, Windows XP, and JS-disabled browsers}	_{Auto-detected via nginx UA map + <noscript> redirect; usable on any browser without JS}	_{✅ Live}

3. Architecture Overview

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Host Machine                                 │
│                                                                       │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    Docker Compose Stack                        │   │
│  │                                                                │   │
│  │  ┌─────────────────────────────────────────────────────┐    │   │
│  │  │              fcpl-site  (nginx:alpine)               │    │   │
│  │  │                                                       │    │   │
│  │  │  Port 8080 (HTTP)  ←──── Public Browser              │    │   │
│  │  │  Port 8443 (HTTPS) ←──── Public Browser (TLS)        │    │   │
│  │  │                                                       │    │   │
│  │  │  /               → Static HTML (site/)               │    │   │
│  │  │  /pages/*        → Static HTML pages                 │    │   │
│  │  │  /css, /js       → Static assets (30d cache)         │    │   │
│  │  │  /images/*       → Uploaded + static images          │    │   │
│  │  │  /data/*.json    → Content files (no-cache)          │    │   │
│  │  │  /simple/*       → Simple site (IE6–8 / no-JS)       │    │   │
│  │  │  /admin/*   ─────────────────────────────────────┐   │    │   │
│  │  │  /api/*     ─────────────────────────────────┐   │   │    │   │
│  │  └──────────────────────────────────────────────│───│───┘    │   │
│  │                                                  │   │        │   │
│  │  ┌───────────────────────────────────────────────▼───▼──┐   │   │
│  │  │           fcpl-admin  (node:20-alpine)                │   │   │
│  │  │                                                        │   │   │
│  │  │  Internal port 3000 (not exposed to host)             │   │   │
│  │  │                                                        │   │   │
│  │  │  GET  /admin/         → Staff Portal SPA              │   │   │
│  │  │  POST /admin/api/auth/login                           │   │   │
│  │  │  GET|POST|PUT|DELETE /admin/api/events                │   │   │
│  │  │  GET|POST|PUT|DELETE /admin/api/announcements         │   │   │
│  │  │  GET|PUT /admin/api/content/:section                  │   │   │
│  │  │  POST /admin/api/upload                               │   │   │
│  │  │  GET|DELETE /admin/api/recycle-bin                    │   │   │
│  │  │  GET /admin/api/audit-log                             │   │   │
│  │  │  GET /admin/api/backups                               │   │   │
│  │  └───────────────────────────────────────────────────────┘   │   │
│  │                                                                │   │
│  │  Shared Volumes (bind-mounted):                                │   │
│  │    ./site/data/   ←→ /data/        (events.json, content.json) │  │
│  │    ./site/images/ ←→ /images/      (uploaded photos)           │  │
│  │    ./docker/certs/ → /etc/nginx/certs/ (TLS cert, read-only)   │  │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Component Breakdown

_Component	_Technology	_Role
_fcpl-site	_nginx:alpine	_{Reverse proxy, static file serving, TLS termination, rate limiting}
_fcpl-admin	_{node:20-alpine + Express}	_{REST API for all content mutations; serves staff portal SPA}
_site/	_{Plain HTML/CSS/JS}	_{Public-facing website — 16 pages, no JS framework}
_{admin/public/index.html}	_{Vanilla JS SPA}	_{Staff content management portal — tabbed, responsive}
_{site/data/events.json}	_JSON	_{Live event data — read by both nginx (static) and admin API}
_{site/data/content.json}	_JSON	_{All other site content: branches, hours, programs, announcements}
_{docker/nginx.conf}	_{Nginx config}	_{Security headers, CSP, rate limit zones, proxy rules, caching, legacy UA detection → /simple/}
_admin/.env	_{Environment file}	_{Credentials and secrets — never committed to git}

Data Flow

Staff makes change in Admin Portal
          │
          ▼
POST/PUT/DELETE /admin/api/...
          │
    ┌─────▼─────┐
    │  Nginx    │──── Rate limit check (zone=admin_write: 30r/m)
    └─────┬─────┘
          │ proxy_pass
    ┌─────▼──────────────────────┐
    │  Express (fcpl-admin)       │
    │  1. requireAuth (JWT check) │
    │  2. writeLimiter (60/15min) │
    │  3. Input sanitisation      │
    │  4. autoBackup(file)        │
    │  5. writeJSON (atomic)      │
    │  6. addToBin / auditLog     │
    └─────────────────────────────┘
          │
          ▼
   ./site/data/*.json  (shared volume)
          │
          ▼
   Public site reads via fetch() → /data/events.json
   Calendar widget renders events in real-time

4. Technology Stack

Runtime Stack

_Technology	_Version	_{Why Chosen}	_{Alternatives Considered}	_Tradeoffs
_{Docker + Compose}	_{29.3 / 5.1}	_{Zero host dependencies; reproducible deployments; easy backup of bind-mounted volumes}	_{Bare-metal nginx, Podman}	_{Docker requires root or docker group; Compose v2 has no separate install}
_{Nginx (Alpine)}	_{latest-alpine}	_{Best-in-class static file serving; sub-ms latency; mature rate-limiting; tiny 8 MB image}	_{Caddy, Apache, Traefik}	_{Caddy has auto-HTTPS but adds complexity; Nginx config is well-understood by admins}
_{Node.js (Alpine)}	_{20 LTS}	_{LTS stability; native crypto module; excellent ecosystem for JWT/bcrypt; 50 MB image}	_{Deno, Python/Flask, Go}	_{Deno too new for rural IT handoff; Go requires compiled binary; Python slower startup}
_Express.js	_4.18	_{Minimal, battle-tested, widely documented}	_{Fastify, Koa, Hono}	_{Fastify is faster but Express has more documentation for non-JS-native maintainers}
_{Plain HTML/CSS/JS}	_ES2020	_{Zero build pipeline; no npm vulnerabilities in frontend; loads in <100ms}	_{React, Vue, Astro, HTMX}	_{Frameworks add maintenance burden and version rot — library may not have a dev on staff}

Security Dependencies (`admin/`)

_Package	_Version	_Purpose	_{Why This One}
_helmet	_^7.2	_{Sets 12 security response headers (CSP, HSTS, X-Frame-Options, etc.)}	_{Industry standard; maintained by the Express team}
_bcryptjs	_^2.4	_{Password hashing at cost factor 12}	_{Pure JS (no native bindings); portable across Alpine}
_jsonwebtoken	_^9.0	_{JWT session tokens (HS256, 8-hour expiry)}	_{Most widely audited JWT library for Node.js}
_{express-rate-limit}	_^7.4	_{Request rate limiting per IP (login + write + global)}	_{Works with trust proxy 1 behind Nginx; draft-7 headers}
_multer	_^2.0	_{Multipart file upload handling}	_{Integrates cleanly with Express; supports fileFilter + limits}

Frontend Libraries (CDN via HTML `<script>`)

_Library	_Purpose	_Notes
_{Leaflet.js (unpkg)}	_{Interactive branch location maps}	_{No Google Maps API key required; OpenStreetMap tiles are free}
_{LibraryThing (ltfl)}	_{Book cover images in catalog widget}	_{Optional external integration}
_{CDN Fonts}	_Typography	_{fonts.cdnfonts.com — scoped in CSP}

5. Quick Start

# 1. Navigate to the project
cd /home/kevin/Projects/fayette_lib

# 2. Copy example env file (change password before going live!)
cp admin/.env.example admin/.env

# 3. Generate a self-signed TLS cert for local HTTPS
mkdir -p docker/certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout docker/certs/key.pem \
  -out docker/certs/cert.pem \
  -subj "/CN=localhost"

# 4. Start both containers
sudo docker compose up -d

# 5. Verify both containers are healthy
sudo docker compose ps

# 6. Open the website
xdg-open http://localhost:8080

# 7. Open the staff portal
xdg-open http://localhost:8080/admin/

Stop the stack: sudo docker compose down Rebuild after code changes: sudo docker compose up -d --build View logs: sudo docker compose logs -f

Docker permission error? Add yourself to the docker group: sudo usermod -aG docker $USER — then log out and back in (or newgrp docker).

6. First-Time Setup

Prerequisites

_Requirement	_Check	_Install
_{Docker ≥ 24}	_{docker --version}	_{docs.docker.com}
_{Docker Compose v2}	_{docker compose version}	_{Included with Docker Desktop; pacman -S docker-compose on Arch}
_OpenSSL	_{openssl version}	_{Pre-installed on most Linux distros}
_{curl (optional)}	_{curl --version}	_{For endpoint verification}

No Node.js, Python, npm, or build tools are needed on the host machine.

Step 1 — Configure your admin password

# Generate a bcrypt hash (cost factor 12) of your chosen password
sudo docker run --rm node:20-alpine node -e \
  "require('bcryptjs').hash('YOUR_PASSWORD', 12).then(h => console.log(h))"

The output starts with $2a$12$.... Copy it.

# Generate a strong JWT secret
openssl rand -hex 48

Open admin/.env and set both values:

# Paste the bcrypt hash here (preferred — production-safe)
STAFF_PASSWORD_HASH=$2a$12$...your-hash-here...

# Or use plaintext during initial testing only (not for production)
# STAFF_PASSWORD=your-password-here

# JWT signing secret — must be at least 32 characters
JWT_SECRET=your-long-random-secret-here

⚠️ admin/.env is listed in .gitignore — it must never be committed to version control.

Step 2 — Generate TLS certificates

Local development (self-signed, browser will show a warning):

mkdir -p docker/certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout docker/certs/key.pem \
  -out docker/certs/cert.pem \
  -subj "/CN=localhost"

Production (trusted Let's Encrypt cert — after DNS is configured):

bash scripts/get-cert.sh your-library-domain.org admin@yourlibrary.org

Step 3 — Start and verify

sudo docker compose up -d
sudo docker compose ps

# Verify HTTP endpoint
curl -I http://localhost:8080/

# Verify admin portal
curl -I http://localhost:8080/admin/

Both should return HTTP/1.1 200 OK (or 302 redirect for HTTP→HTTPS).

Step 4 — Log in

Navigate to http://localhost:8080/admin/ and enter your password. Sessions last 8 hours, then require re-login.

Development vs Production

_Setting	_Development	_Production
_Password	_{STAFF_PASSWORD=... (plaintext OK)}	_{STAFF_PASSWORD_HASH=... (bcrypt required)}
_{JWT Secret}	_{Any string ≥ 32 chars}	_{openssl rand -hex 48 minimum}
_{TLS cert}	_{Self-signed (browser warning)}	_{Let's Encrypt via scripts/get-cert.sh}
_{HSTS preload}	_Off	_{Enable after HTTPS confirmed stable}
_Port	_{8080 / 8443}	_{80 / 443 (reverse proxy or firewall redirect)}

7. Usage Flow

Public Patron Flow

Browser visits http://library-domain.org
        │
        ▼
   [Nginx: fcpl-site]
        │
        ├── / ────────────────► index.html (homepage)
        │                           │
        │                    JS fetches /data/events.json
        │                    JS fetches /data/content.json
        │                           │
        │                    Renders: announcements sidebar
        │                            upcoming events preview
        │                            homepage image slider
        │
        ├── /pages/programs.html  ► Programs & Events page
        ├── /pages/locations.html ► Branch map + hours (Leaflet)
        ├── /pages/ebooks.html    ► Digital resources list
        ├── /pages/bookmobile.html► Bookmobile schedule
        ├── /pages/homebound.html ► Homebound delivery service
        ├── /pages/...            ► 16 total pages
        │
        └── Legacy / no-JS browsers
                │
                ├── IE6–8 or Windows XP: nginx UA map detects user-agent
                │       └── 302 redirect ──────────────────► /simple/
                │
                └── JavaScript disabled (any modern browser)
                        ├── index.html: <noscript> meta-refresh → /simple/
                        └── pages/*.html: <noscript> amber banner with manual link

Staff Content Management Flow

Staff opens http://localhost:8080/admin/
        │
        ▼
   Login screen → POST /admin/api/auth/login
        │                    │
        │              [rate limited: 5r/m Nginx + 10/15min Express]
        │                    │
        │            ✓ Returns JWT token (8-hour expiry)
        │            ✗ Returns 401 (generic message)
        │
        ▼
   Admin Portal SPA (tabbed)
        │
        ├── 📅 Events tab
        │       ├── GET /admin/api/events              ← list all
        │       ├── POST /admin/api/events             ← add event
        │       ├── PUT /admin/api/events/:id          ← edit event
        │       └── DELETE /admin/api/events/:id       ← soft-delete
        │
        ├── 📢 Announcements tab
        │       └── CRUD /admin/api/announcements
        │
        ├── 🕒 Branch Hours tab
        │       └── PUT /admin/api/content/branches
        │
        ├── 📚 Programs / 🌐 Resources / ⚙️ Settings
        │       └── GET|PUT /admin/api/content/:section
        │
        ├── 🖼️ Images tab
        │       └── POST /admin/api/upload  (MIME check + 5MB cap)
        │
        ├── 🗑️ Recycle Bin  → restore/purge soft-deleted items
        ├── 🔍 Activity Log → audit trail (last 500 actions)
        └── 💾 Backups      → browse/restore auto-snapshots

8. Admin Portal Guide

Tab Reference

_Tab	_Icon	_{What You Can Do}
_Events	_📅	_{Add / edit / delete calendar events; upload event photos}
_{Announcements}	_📢	_{Manage homepage sidebar announcements}
_{Branch Hours}	_🕒	_{Edit hours for all 5 branches; holiday closures}
_Programs	_📚	_{Storytime schedules, adult book club, Library Chef}
_{Digital Resources}	_🌐	_{Manage eBook/database/website links}
_Analytics	_📊	_{Page-view stats}
_System	_⚡	_{Server health check; restart signal}
_Settings	_⚙️	_{Site name, phone number, social media links}
_Calendars	_📆	_{Manage shareable calendar feeds}
_{Hosting Info}	_🏠	_{DNS, SSL cert status, server IP records}
_Staff	_👥	_{Director, assistant, bookmobile staff names}
_Images	_🖼️	_{Homepage slider photos and featured event cards}
_{Recycle Bin}	_🗑️	_{Restore items deleted in the last 60 days}
_{Activity Log}	_🔍	_{Full audit trail — every change with IP + timestamp}
_Backups	_💾	_{Browse and restore automatic pre-change snapshots}

Adding an Event

Click 📅 Events → + Add Event
Fill in: title, start date/time, end date/time, location, category, description
Optionally upload a photo (JPEG/PNG/GIF/WebP, max 5 MB)
Click Save — appears on the public calendar immediately

Recurrence options: None · Daily · Weekly · Monthly (by weekday)

Managing Branch Hours

Click 🕒 Branch Hours → Edit Hours next to the branch
Update rows — +Row to add time ranges, trash icon to remove
Holiday Closures section at the bottom: check holidays + optional notes
Click Save Hours — live instantly

Recycle Bin

Events, Announcements, Programs, Digital Resources, and Images are soft-deleted
Items are kept for 60 days, then permanently purged
Click Restore to put an item back into its original tab
Click Delete Forever to remove immediately

Activity Log

Records every save/delete with: timestamp · IP address · action type · detail
Last 500 entries retained
Delete actions highlighted in red for quick scanning

Backups

Auto-snapshot of events.json or content.json taken before every destructive write
Up to 20 backups kept per file (oldest auto-pruned)
Click Restore to roll back — this also creates a backup of the current state first (undo the undo)

9. API Reference

All API endpoints are under /admin/api/. All mutating endpoints require a Bearer JWT token in the Authorization header.

Authentication

_Endpoint	_Method	_Auth	_Description
_{/admin/api/auth/login}	_POST	_None	_{Exchange password for JWT}

Request:

{ "password": "your-staff-password" }

Response:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

Events

_Endpoint	_Method	_Auth	_Description
_{/admin/api/events}	_GET	_✅	_{List all events}
_{/admin/api/events}	_POST	_✅	_{Create new event}
_{/admin/api/events/:id}	_PUT	_✅	_{Update event by ID}
_{/admin/api/events/:id}	_DELETE	_✅	_{Soft-delete event (moves to recycle bin)}

Event object fields:

{
  "id": 42,
  "title": "Summer Reading Kickoff",
  "start": "2026-06-01T10:00:00",
  "end": "2026-06-01T12:00:00",
  "location": "Oak Hill Branch",
  "category": "children",
  "description": "Join us for the start of summer reading...",
  "recurrence": "none",
  "image": "/images/events/1717200000-a1b2c3d4e5f6.jpg"
}

Announcements

_Endpoint	_Method	_Auth	_Description
_{/admin/api/announcements}	_GET	_✅	_{List all announcements}
_{/admin/api/announcements}	_POST	_✅	_{Create announcement}
_{/admin/api/announcements/:idx}	_PUT	_✅	_{Update by array index}
_{/admin/api/announcements/:idx}	_DELETE	_✅	_{Soft-delete announcement}

Content Sections

_Endpoint	_Method	_Auth	_Description
_{/admin/api/content/:section}	_GET	_✅	_{Read a content section}
_{/admin/api/content/:section}	_PUT	_✅	_{Update a content section}

Allowed sections: site · staff · branches · programs · digital_resources · services · memorial_program · hosting · holiday_closures · homepage_features · jobs

Images

_Endpoint	_Method	_Auth	_Description
_{/admin/api/upload}	_POST	_✅	_{Upload image (multipart/form-data)}

Accepted: JPEG · PNG · GIF · WebP · Max 5 MB Returns: { "url": "/images/events/timestamp-randomhex.ext" }

System & Audit

_Endpoint	_Method	_Auth	_Description
_{/admin/api/recycle-bin}	_GET	_✅	_{List deleted items}
_{/admin/api/recycle-bin/:bin_id/restore}	_POST	_✅	_{Restore an item}
_{/admin/api/recycle-bin/:bin_id}	_DELETE	_✅	_{Permanently delete}
_{/admin/api/audit-log}	_GET	_✅	_{Last 500 audit entries}
_{/admin/api/backups}	_GET	_✅	_{List available backups}
_{/admin/api/backups/restore}	_POST	_✅	_{Restore a backup}

Response Conventions

_Status	_Meaning
_{200 OK}	_{Read success}
_{201 Created}	_{Write success}
_{400 Bad Request}	_{Invalid input}
_{401 Unauthorized}	_{Missing or expired JWT}
_{404 Not Found}	_{Resource doesn't exist}
_{413 Payload Too Large}	_{Image over 5 MB}
_{429 Too Many Requests}	_{Rate limit exceeded}
_{500 Internal Server Error}	_{Server-side failure}

10. Security

Defense-in-Depth Model

Internet Request
      │
      ▼
[Nginx — Layer 1]
  • Rate limit zones (general: 120r/m, admin_write: 30r/m, login: 5r/m)
  • Returns 429 on breach (not 503)
  • Security headers on every response
  • TLS 1.2/1.3 with strong cipher suite
      │
      ▼
[Express — Layer 2]
  • apiLimiter: 200 req/15min per IP
  • writeLimiter: 60 writes/15min per IP
  • loginLimiter: 10 attempts/15min per IP
  • JWT verification (HS256, 8-hour expiry)
  • Helmet.js (12 security headers)
      │
      ▼
[Application — Layer 3]
  • Password: bcrypt(12) + constant-time compare
  • Input: all fields sanitized and length-capped
  • Uploads: MIME-type checked, random filename
  • Files: path traversal prevention on all reads/writes
  • Writes: atomic (temp-file rename; no corruption on crash)

Security Headers (Nginx — all responses)

_Header	_Value
_{X-Frame-Options}	_SAMEORIGIN
_{X-Content-Type-Options}	_nosniff
_{Referrer-Policy}	_{strict-origin-when-cross-origin}
_{Permissions-Policy}	_{Camera/mic/payment blocked; geolocation self-only}
_{X-DNS-Prefetch-Control}	_off
_{Cross-Origin-Opener-Policy}	_same-origin
_{Content-Security-Policy}	_{Restricts scripts/styles/images/frames to trusted origins}

Additional Admin Headers (Helmet.js)

_Header	_Value
_{Strict-Transport-Security}	_{max-age=31536000; includeSubDomains}
_{X-Frame-Options}	_{DENY (stricter for admin)}
_{Content-Security-Policy}	_{Admin-specific; blocks all external CDNs}

Rate Limits

_Endpoint	_Nginx	_Express
_{Login (/admin/api/auth/login)}	_{5 req/min, burst 3}	_{10 req/15 min}
_{Admin API writes}	_{30 req/min, burst 10}	_{60 req/15 min}
_{All admin API}	_—	_{200 req/15 min}
_{Public site}	_{120 req/min, burst 30}	_—

OWASP Top 10 Mitigations

_{OWASP Risk}	_Mitigation
_{A02 Cryptographic Failures}	_{bcrypt(12) for passwords; HS256 JWT with strong secret}
_{A03 Injection}	_{All inputs sanitized and truncated; no eval/exec; no SQL}
_{A05 Misconfiguration}	_{Helmet defaults; server_tokens off; no X-Powered-By header}
_{A06 Vulnerable Components}	_{Pinned npm dependencies; minimal image size}
_{A07 Auth Failures}	_{Rate limiting on login; JWT expiry; constant-time password comparison}
_{A08 Software Integrity}	_{Atomic writes (write→temp→rename); no partial JSON on crash}

Changing the Password (Staff Departure)

# Step 1: Generate a new bcrypt hash
sudo docker run --rm node:20-alpine node -e \
  "require('bcryptjs').hash('NEW_PASSWORD_HERE', 12).then(h => console.log(h))"

# Step 2: Edit admin/.env — replace STAFF_PASSWORD_HASH
nano /home/kevin/Projects/fayette_lib/admin/.env

# Step 3: Restart admin container (< 5 seconds)
sudo docker compose restart fcpl-admin

To immediately invalidate all active sessions, also rotate JWT_SECRET in .env and restart.

Known Limitations

Single shared password — all staff use one credential. Departing staff access is revoked by changing the password. The Activity Log provides per-IP accountability.
No TOTP/2FA — suitable for internal deployment; consider adding for internet-facing portals.
Self-signed cert — local only; use scripts/get-cert.sh for production.

11. Site Structure

fayette_lib/
├── README.md                         ← This file
├── docker-compose.yml                ← Starts both containers
├── .gitignore
│
├── admin/                            ← Staff portal backend
│   ├── .env.example                  ← Template — copy to .env and edit
│   ├── .env                          ← ⚠️ SECRETS — never commit
│   ├── server.js                     ← Express REST API (~700 lines)
│   ├── package.json                  ← 5 production dependencies
│   ├── Dockerfile                    ← node:20-alpine, 9 steps
│   └── public/
│       └── index.html                ← Staff portal SPA (vanilla JS)
│
├── docker/
│   ├── Dockerfile                    ← nginx:alpine, 8 steps
│   ├── nginx.conf                    ← Nginx config + security headers
│   ├── docker-entrypoint.sh
│   └── certs/
│       ├── cert.pem                  ← TLS certificate (self-signed or LE)
│       └── key.pem                   ← TLS private key
│
├── site/                             ← Public website (static files)
│   ├── index.html                    ← Homepage
│   ├── 404.html
│   ├── robots.txt
│   ├── favicon.ico
│   ├── css/
│   │   └── style.css                 ← All styles; edit :root vars to retheme
│   ├── js/
│   │   ├── main.js                   ← Content loading, nav, tabs
│   │   ├── calendar.js               ← Public calendar widget
│   │   └── a11y.js                   ← Accessibility toolbar
│   ├── pages/                        ← All secondary pages
│   │   ├── about.html
│   │   ├── programs.html
│   │   ├── programs-adults.html
│   │   ├── programs-children.html
│   │   ├── programs-teens.html
│   │   ├── programs-community.html
│   │   ├── locations.html            ← Branch map (OpenStreetMap + Leaflet)
│   │   ├── research.html
│   │   ├── ebooks.html
│   │   ├── bookmobile.html
│   │   ├── homebound.html
│   │   ├── archives.html
│   │   ├── news.html
│   │   ├── jobs.html
│   │   ├── catalog.html
│   │   └── myaccount.html
│   ├── simple/                       ← No-JS / legacy browser version (IE6+)
│   │   ├── index.html                ← Simple homepage — HTML 4.01, no JS required
│   │   ├── about.html
│   │   ├── locations.html
│   │   ├── programs.html
│   │   ├── ebooks.html
│   │   ├── bookmobile.html
│   │   ├── homebound.html
│   │   ├── research.html
│   │   ├── news.html
│   │   ├── jobs.html
│   │   ├── catalog.html
│   │   ├── archives.html
│   │   └── css/
│   │       └── simple.css            ← IE6+ compatible stylesheet (float layout, no CSS custom properties)
│   ├── images/                       ← Static images + uploaded event photos
│   └── data/
│       ├── events.json               ← All calendar events (live data)
│       ├── content.json              ← Branches, hours, programs, announcements
│       ├── audit_log.json            ← Staff action log (0o640 — not public)
│       ├── recycle_bin.json          ← Soft-deleted items (0o640)
│       └── backups/                  ← Auto-snapshots (up to 20 per file)
│
├── scripts/
│   └── get-cert.sh                   ← Let's Encrypt cert for production
└── docs/
    └── site-audit.md                 ← Original site content audit

The two key data files:

_File	_Contents	_{Who edits it}
_{site/data/events.json}	_{All calendar events with dates, times, locations}	_{Admin portal → Events tab}
_{site/data/content.json}	_{Branch hours, announcements, programs, staff, settings}	_{Admin portal → all other tabs}

12. Daily Staff Usage

All content management happens at http://localhost:8080/admin/ — no terminal access needed.

Adding an Event

📅 Events → + Add Event
Fill in title, date/time, location, category, description
Optionally upload a photo
Save — event appears on the public calendar immediately

Adding an Announcement

📢 Announcements → + Add Announcement
Fill in title, body text, optional link
Save — appears in the homepage sidebar immediately

Editing Branch Hours

🕒 Branch Hours → Edit Hours next to the branch
Update time rows; +Row adds a new row; trash icon removes
Save — live immediately

Setting Holiday Closures

🕒 Branch Hours → scroll to Holiday Closures
Check the holiday checkboxes when the library is closed
Add any patron-facing notice in the text field
Save Holiday Closures

Managing Digital Resources

🌐 Digital Resources → Add / Edit / Delete eBook and database links

Homepage Images

🖼️ Images → Upload slider photos and featured event cards
Keep original images under 1 MB for fast page loads

13. Backups & Recovery

Automatic Backups

A snapshot of events.json or content.json is saved to site/data/backups/ before every destructive write through the admin portal. Up to 20 backups are kept per file (oldest auto-pruned).

Manual Backup

# Full data export to a timestamped folder
cp -r /home/kevin/Projects/fayette_lib/site/data/ ~/fcpl-backup-$(date +%Y%m%d)/

Restoring via Admin Portal

Log into the admin portal
Click 💾 Backups
Find the backup and click Restore

Restoring via Terminal

# List available backups
ls /home/kevin/Projects/fayette_lib/site/data/backups/

# Restore events
cp site/data/backups/events_2026-03-31T14-22-00.json site/data/events.json

# Restore content
cp site/data/backups/content_2026-03-31T09-15-00.json site/data/content.json

No container restart needed — changes are live immediately since files are bind-mounted.

14. Updating the Site

After Editing HTML, CSS, or JS

sudo docker compose up -d --build

After Editing `site/data/events.json` or `site/data/content.json` Directly

No rebuild needed — volume-mounted files are live immediately.

After Editing `admin/server.js` or `admin/public/index.html`

sudo docker compose up -d --build

Changing the Color Theme

Open site/css/style.css and edit the CSS variables in :root { ... } at the top of the file. Then rebuild.

Updating Branch Map Coordinates

Look up the address at nominatim.openstreetmap.org
Find the BRANCHES object in site/pages/locations.html
Update lat and lng for the branch
Rebuild

15. Production Deployment

Server Requirements

_Resource	_Minimum	_Recommended
_CPU	_{1 vCPU}	_{2 vCPU}
_RAM	_{512 MB}	_{1 GB}
_Disk	_{5 GB}	_{20 GB}
_OS	_{Any Linux with Docker}	_{Ubuntu 24 LTS / Arch}
_{Inbound ports}	_{80, 443}	_{80, 443}

DNS Setup

Point your domain's A record to the server's public IP, then:

# After DNS propagates, obtain a real TLS certificate
bash scripts/get-cert.sh your-library-domain.org admin@yourlibrary.org

Going Live Checklist

[ ] Set STAFF_PASSWORD_HASH (bcrypt, not plaintext) in admin/.env
[ ] Set JWT_SECRET to output of: openssl rand -hex 48
[ ] Replace self-signed cert with Let's Encrypt cert
[ ] Confirm HTTPS works at https://your-domain.org
[ ] Set HSTS preload: true in admin/server.js (after HTTPS is stable)
[ ] Add the user to the docker group: sudo usermod -aG docker $USER
[ ] Set up daily data backup cron: cp -r site/data/ ~/backups/fcpl-$(date +%Y%m%d)/
[ ] Configure server firewall to allow only ports 80 and 443
[ ] Point domain DNS A record to server IP

16. Debugging Common Problems

Site Won't Start

# Check container status
sudo docker compose ps

# View logs
sudo docker compose logs fcpl-site
sudo docker compose logs fcpl-admin

# Rebuild from scratch
sudo docker compose down
sudo docker compose up -d --build

Admin Portal Login Loop / "Authentication Required"

Verify admin/.env exists and contains STAFF_PASSWORD_HASH or STAFF_PASSWORD
Hash must start with $2a$12$...
JWT_SECRET must be at least 32 characters
Restart: sudo docker compose restart fcpl-admin

Calendar Not Showing Events

# Validate JSON syntax
python3 -m json.tool site/data/events.json

Events need: "id", "title", and "start" (ISO 8601: "2026-06-01T10:00:00").

Images Not Uploading

Max size: 5 MB
Accepted types: JPEG, PNG, GIF, WebP
Check disk space: df -h
Check logs: sudo docker compose logs fcpl-admin

"Too Many Requests" in Admin Portal

You've hit the write rate limit (60 ops/15 minutes per IP)
Wait 15 minutes — this is intentional security behaviour

Self-Signed Cert Warning in Browser

Expected for local development. For production, run scripts/get-cert.sh to get a trusted Let's Encrypt cert.

nginx Won't Start ("cannot load certificate")

The docker/certs/ directory is missing cert.pem / key.pem. Generate them:

mkdir -p docker/certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout docker/certs/key.pem -out docker/certs/cert.pem -subj "/CN=localhost"

How to View the Audit Log from Terminal

cat site/data/audit_log.json | python3 -m json.tool | head -100

17. Project Roadmap

_Phase	_Timeline	_Goals	_Status
_{Phase 1 — Core Site}	_{Q1 2026}	_{Static website with all 16 pages; Docker stack; WCAG 2.1 AA}	_{✅ Complete}
_{Phase 2 — Admin Portal}	_{Q1 2026}	_{Staff CMS: events, hours, announcements, programs, images}	_{✅ Complete}
_{Phase 3 — Security Hardening}	_{Q1 2026}	_{OWASP Top 10 mitigations; dual-layer rate limiting; bcrypt + JWT}	_{✅ Complete}
_{Phase 4 — Resilience}	_{Q1 2026}	_{Auto-backup, recycle bin, activity log, atomic writes}	_{✅ Complete}
_{Phase 5 — Production TLS}	_{Q2 2026}	_{Let's Encrypt cert automation; HSTS preload}	_{✅ Complete}
_{Phase 5b — Legacy Browser Support}	_{Q2 2026}	_{No-JS simple site at /simple/; nginx IE6–8 + Windows XP UA detection; <noscript> redirects and banners on all pages}	_{✅ Complete}
_{Phase 6 — Production Deploy}	_{Q2 2026}	_{Go live at fayette.lib.wv.us; DNS cutover; smoke tests}	_{🟡 In Progress}
_{Phase 7 — Analytics}	_{Q3 2026}	_{Self-hosted page-view analytics (no Google Analytics)}	_{⭕ Planned}
_{Phase 8 — Mobile App}	_{Q4 2026}	_{Progressive web app (PWA) manifest + offline support}	_{⭕ Planned}
_{Phase 9 — Multi-Staff}	₂₀₂₇	_{Optional: per-staff accounts with role-based permissions}	_{⭕ Backlog}

18. FAQ

Q: How do I add a new branch? Go to admin → 🕒 Branch Hours → scroll to the bottom → + Add Branch.

Q: Can I restore something I deleted by mistake? Yes — 🗑️ Recycle Bin tab. Items are kept for 60 days.

Q: How do I close the library for a holiday? Check the holiday in 🕒 Branch Hours → Holiday Closures, or add a calendar event with category closure.

Q: What is the simple site and who uses it? The simple site at /simple/ is a JavaScript-free HTML 4.01 version of the site. It is served automatically to browsers that don't support modern JS — specifically IE6, IE7, IE8, and any browser running on Windows XP. It is also shown to any browser with JavaScript manually disabled, via a <noscript> meta-refresh on the homepage and amber warning banners on all subpages.

Q: How do I update the content in the simple site? Edit the HTML files directly in site/simple/. The content is hardcoded (no JSON fetching). After editing, rebuild with sudo docker compose up -d --build.

Q: A staff member left — how do I prevent access? Change the admin password. See Section 10 — Security. Takes effect immediately on restart.

Q: How do I see what someone changed? 🔍 Activity Log tab — every action is recorded with IP and timestamp.

Q: The site looks wrong after I edited something — how do I undo? 💾 Backups tab → restore the snapshot before your change. Or from terminal: copy from site/data/backups/.

Q: How do I move this to a real web server?

Copy the project directory to the server
Install Docker
sudo docker compose up -d
Point your domain DNS to the server IP
Run scripts/get-cert.sh your-domain.org your@email.com
Done — no other dependencies needed

Q: How do I back up everything?

cp -r site/data/ ~/fcpl-backup-$(date +%Y%m%d)/

Q: Can staff access the portal from another computer? Yes — navigate to http://SERVER_IP:8080/admin/ from any machine on the same network.

Q: Why aren't we using WordPress / Drupal / Squarespace? Those platforms require ongoing maintenance, license fees, plugin management, and vulnerability patching. This codebase has 5 npm dependencies, no database, and runs on any $6/month VPS. The staff can manage all content without ever touching code.

Built for Fayette County Public Libraries, Fayette County, West Virginia. All site content and data belong to FCPL.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.vscode		.vscode
admin		admin
docker		docker
docs		docs
scripts		scripts
site		site
.gitignore		.gitignore
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Fayette County Public Libraries — Website & Staff Portal

Table of Contents

Maintainer Documentation Bundle

Developer Ergonomics (New)

1. Project Overview

What It Is

What Problem It Solves

Who It Is For

Why It Exists

2. Key Features

3. Architecture Overview

High-Level Architecture

Component Breakdown

Data Flow

4. Technology Stack

Runtime Stack

Security Dependencies (admin/)

Frontend Libraries (CDN via HTML <script>)

5. Quick Start

6. First-Time Setup

Prerequisites

Step 1 — Configure your admin password

Step 2 — Generate TLS certificates

Step 3 — Start and verify

Step 4 — Log in

Development vs Production

7. Usage Flow

Public Patron Flow

Staff Content Management Flow

8. Admin Portal Guide

Tab Reference

Adding an Event

Managing Branch Hours

Recycle Bin

Activity Log

Backups

9. API Reference

Authentication

Events

Announcements

Content Sections

Images

System & Audit

Response Conventions

10. Security

Defense-in-Depth Model

Security Headers (Nginx — all responses)

Additional Admin Headers (Helmet.js)

Rate Limits

OWASP Top 10 Mitigations

Changing the Password (Staff Departure)

Known Limitations

11. Site Structure

12. Daily Staff Usage

Adding an Event

Adding an Announcement

Editing Branch Hours

Setting Holiday Closures

Managing Digital Resources

Homepage Images

13. Backups & Recovery

Automatic Backups

Manual Backup

Restoring via Admin Portal

Restoring via Terminal

14. Updating the Site

After Editing HTML, CSS, or JS

After Editing site/data/events.json or site/data/content.json Directly

After Editing admin/server.js or admin/public/index.html

Changing the Color Theme

Updating Branch Map Coordinates

15. Production Deployment

Server Requirements

DNS Setup

Going Live Checklist

16. Debugging Common Problems

Security Dependencies (`admin/`)

Frontend Libraries (CDN via HTML `<script>`)

After Editing `site/data/events.json` or `site/data/content.json` Directly

After Editing `admin/server.js` or `admin/public/index.html`

Packages