The Sys.

A Spotify-style documentation browser running on EC2. Built to stay focused.

What This Is

A Node.js/Express server that renders markdown files with a card-based UI featuring:

Horizontal scrolling sections (Recently Added, Categories)
Gradient card backgrounds (hash-based, deterministic colors)
Dark mode aesthetic (#121212 background)
PWA support (installable, offline-capable)

All your personal docs (system reference, letters, blog posts) accessible via browser at port 3040.

Setup

Components:

Express server (server.js) - Serves markdown files as HTML with Spotify-style UI
Request logging - Every visit logged to access.log
systemd service - Runs as system service, auto-starts on boot, auto-restarts on crashes
PWA support - Manifest, service worker, installable app

Files:

server.js - Main server code (~900 lines, inline HTML/CSS templates)
package.json - Node dependencies (express, marked, gray-matter)
*.md - Markdown files with YAML frontmatter
access.log - Request logs
yap.service - systemd service configuration
manifest.json - PWA manifest
sw.js - Service worker for offline support

Running the Server

Via systemd (recommended):

# Start
sudo systemctl start yap

# Check status
sudo systemctl status yap

# View logs
sudo journalctl -u yap -f

Manual (development):

cd /home/ubuntu/workplace/repos/yap
node server.js

Accessing the Blog

URL:

http://[EC2-PUBLIC-IP]:3040

Get your EC2 public IP:

curl -s ifconfig.me

Useful Commands

Service Management:

# Check if running
sudo systemctl status yap

# Start/stop/restart
sudo systemctl start yap
sudo systemctl stop yap
sudo systemctl restart yap

# Disable/enable auto-start on boot
sudo systemctl disable yap
sudo systemctl enable yap

Viewing Logs:

# Access logs (who's visiting)
tail -f /home/ubuntu/workplace/repos/yap/access.log

# systemd logs (server output)
sudo journalctl -u yap -f

# Last 50 lines of systemd logs
sudo journalctl -u yap -n 50

After Making Changes:

# If you edit server.js or markdown files
sudo systemctl restart yap

# If you edit the service file
sudo systemctl daemon-reload
sudo systemctl restart yap

Markdown Frontmatter

Documents use YAML frontmatter for metadata:

---
title: "Document Title"
category: "Personal"
repo: "yap"
dateAdded: "2025-11-25"
tags: ["tag1", "tag2"]
---

# Your content here...

Categories: Personal, System, Stories, Design, Meta, Setup

Adding New Docs

Just add a .md file with frontmatter. It'll show up automatically.

No restart needed - the server scans for markdown files on each load.

systemd Service Configuration

Located at /home/ubuntu/workplace/repos/yap/yap.service (symlinked to /etc/systemd/system/yap.service):

[Unit]
Description=The Sys. Documentation Browser
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/workplace/repos/yap
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3040

[Install]
WantedBy=multi-user.target

UI Design

Background: #121212 (Spotify dark)
Cards: Gradient backgrounds with 30-35% saturation, 40-45% lightness
Layout: Horizontal scrolling sections with snap scrolling
Typography: System fonts, 1.6 line height
Mobile: Touch-optimized, 180x240px cards

Troubleshooting

Server not responding:

sudo systemctl status yap
sudo journalctl -u yap -n 50

Port 3040 not accessible:

Check EC2 security group allows inbound TCP on port 3040
Verify server is listening: sudo netstat -tlnp | grep 3040

After EC2 restart: Service should auto-start. If not:

sudo systemctl start yap

Built With

Node.js + Express
marked.js (markdown to HTML)
gray-matter (YAML frontmatter parsing)
systemd (process management)
Pure CSS (no frameworks, inline styles)

Philosophy: Simple. No frameworks. No build step. Just markdown files and a vanilla server.

Last updated: December 2025