cp .env.example .env
pnpm install --frozen-lockfile
bash scripts/copy-blog-images.sh
pnpm db:push && pnpm db:seed
pnpm dev
# http://localhost:3000  →  /dashboard  admin@yas.sh / Admin123!ChangeMe

Works identically on macOS and Oracle Linux 9. See #production.

Installation

Requirements: Node ≥20 <25, pnpm 9.12.3 (corepack), Sharp (libvips), Prisma (openssl), MariaDB 11 prod or SQLite dev.

node -v # v20.20.2
pnpm -v # 9.12.3
openssl version # OpenSSL 3.x

Oracle Linux 9: dnf install openssl vips + nodesource.

Configuration

All config via env + next.config.mjs + CSS vars.

Theme: app/globals.css :root --brand/--bg + components/theme-provider.tsx 7 palettes.

Images: next.config images.remotePatterns locked to yas.sh / unsplash / cdn. AVIF/WebP.

Environment Variables

DATABASE_URL"file:./dev.db" dev, "mysql://user:pass@host:3306/yas" prod

SESSION_SECRET"32+ random chars — openssl rand -hex 32"

BASE_URL"http://localhost:3000" dev, "https://yas.sh" prod

SEED_ADMIN_EMAIL/PASSWORDadmin@yas.sh / Strong123! (dev only)

REDIS_URL"redis://localhost:6379" optional Valkey for rate-limit/cache

NODE_ENVdevelopment | production

Never commit real secrets. .env.example is placeholder.

Deployment

Three options — local build, Docker, Coolify.

pnpm build && pnpm start
# or
docker compose up -d
# or Coolify on Oracle Linux 9 — see docs/10_DEPLOYMENT.md

Standalone when BUILD_STANDALONE=true — copies minimal deps for Docker.

API Guide

Base /api/v1 • OpenAPI 3.1 at /api/v1/openapi • Errors application/problem+json.

GET /v1/links?search=&limit=20&cursor=

POST /v1/links {originalUrl}

Full reference →

Authentication

Cookie: yas_session httpOnly Secure SameSite Lax — for dashboard.

Bearer: Authorization: Bearer yas_live_… — for servers, auto hashed (SHA-256), lastUsedAt tracked.

curl -H "Authorization: Bearer yas_live_abc123" https://yas.sh/api/v1/links

Scopes: links:read,links:write,analytics:read. Rotate via /api/v1/api-keys show-once, 10 max.

Search

Global ⌘K opens Fuse.js index of pages/tools/blogs. Endpoint /api/search/index serves blog slugs.

Link Intelligence

Shorten (random base62 7 chars + alias) → 302 edge redirect (p95 38ms, Valkey cache) → ClickEvent (geo/device/referrer, bot filtered) → analytics rollup.

Every share hits same redirect — single source of truth. Password (bcrypt), expiry (datetime/clicks), QR sync via short code.

Blog System

See Blog Guide. Co-located blog/content/<slug>/index.mdx + hero.webp, auto SSG, sanitized marked, JSON-LD, i18n EN/AR RTL, sticky TOC, progress bar.

Project Structure

app/            Next.js (marketing, dashboard, blog/[slug], docs, api/v1, [code], status, case-studies)
components/ui/  Card/Badge/Button/Input + blog-progress/theme-provider/search
lib/            api-helpers, api-sdk (UI→REST), auth, prisma, utils, validators, tools-def
blog/content/   MDX + hero/cover/thumb per post (EN + AR)
prisma/         schema.prisma + seed.ts
public/blog-img/ served images (copied via script)
scripts/        smoke.sh, security-smoke.sh, copy-blog-images.sh (POSIX)
docs/           markdown + BLOG_GUIDE.md

Development Workflow

Add feature = add folder (app/tools/[slug] + lib/tools-def) — no core edits.
UI never imports Prisma — only lib/api-sdk.ts → REST /v1.
Theme via CSS vars — change 2 vars to rebrand.
Blog via file system — no registry.
Test: pnpm build + bash scripts/smoke.sh + BASE= prod bash scripts/security-smoke.sh.

Production Deployment (Oracle Linux 9)

sudo dnf install -y openssl vips
# Node 20 via nodesource, pnpm 9.12.3 via corepack
cp .env.example .env # edit
pnpm install --frozen-lockfile
pnpm db:push && pnpm db:seed
bash scripts/copy-blog-images.sh
pnpm build
pnpm start # behind Nginx with CSP (next.config headers)

Nginx: proxy + HSTS, 4GB RAM recommended for build, 1GB runtime.

Troubleshooting

Build OOM: Use BUILD_STANDALONE=true pnpm build or 4GB instance.

Prisma engine: openssl version must be 3.x; prisma generate on postinstall.

Blog 404: Check slug /^[a-z0-9-]+$/, file index.mdx, run copy script.

/contact not sending: Check Web3Forms key, honeypot, network tab.

Theme flash: ThemeProvider sets vars post-hydration — default palette SSR matches to avoid FOUC.

Operations — Oracle Linux 9

The production runbook: server setup, reverse proxy, TLS, monitoring, backups, logging, and recovery procedures.

Read the runbook →Deployment guide →

User Guide

Getting started, the full feature tour, tutorials, FAQ, and troubleshooting for end users.

Read the user guide →

FAQ

Free limit?

50 links, 1k clicks/mo, 1 API key. Pro 5k/100k, Business 50k/1M.

RPO?

≤15m with daily encrypted dumps (MariaDB).

Support SLA?

Contact → <24h; Enterprise → 4h.

i18n?

EN + AR RTL supported, dir auto, locale frontmatter.