From 7e69fb317d68d642af1e57dfc2fed2ddb17fc968 Mon Sep 17 00:00:00 2001 From: Kunthawat Greethong Date: Tue, 10 Mar 2026 08:21:16 +0700 Subject: [PATCH] docs: Add WEBSITE-CREATOR-IMPROVEMENTS.md with lessons learned from PDPA implementation --- WEBSITE-CREATOR-IMPROVEMENTS.md | 410 ++++++++++++++++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 WEBSITE-CREATOR-IMPROVEMENTS.md diff --git a/WEBSITE-CREATOR-IMPROVEMENTS.md b/WEBSITE-CREATOR-IMPROVEMENTS.md new file mode 100644 index 0000000..5a76bf1 --- /dev/null +++ b/WEBSITE-CREATOR-IMPROVEMENTS.md @@ -0,0 +1,410 @@ +# Website Creator Skill - Improvements from PDPA Implementation + +**Date:** March 9, 2026 +**Source:** Real-world implementation at moreminimore-redesign +**Status:** ✅ Lessons Learned & Action Items + +--- + +## 🚨 Critical Fixes Required + +### 1. Dockerfile Template - Production Server + +**PROBLEM:** Original template used `astro preview` (development server) + +```dockerfile +# ❌ WRONG - Development server only +CMD ["npx", "astro", "preview", "--host", "0.0.0.0", "--port", "80"] +``` + +**SOLUTION:** Use Node adapter production server + +```dockerfile +# ✅ CORRECT - Production server +CMD ["node", "dist/server/entry.mjs"] +``` + +**WHY:** +- `astro preview` is for development only +- Has host restrictions and security limitations +- Not optimized for production +- `node dist/server/entry.mjs` is the actual production server + +--- + +### 2. Dockerfile - Environment Variables for Docker Networking + +**PROBLEM:** Server listens on `localhost` by default, not accessible from outside container + +```dockerfile +# ❌ MISSING - Server only accessible inside container +ENV NODE_ENV=production +``` + +**SOLUTION:** Add HOST and PORT environment variables + +```dockerfile +# ✅ CORRECT - Server accessible from outside +ENV NODE_ENV=production +ENV HOST=0.0.0.0 +ENV PORT=80 +``` + +**WHY:** +- Node.js servers respect `HOST` and `PORT` env vars +- `0.0.0.0` means "listen on all network interfaces" +- Required for Docker container networking +- More reliable than adapter config + +--- + +### 3. Astro DB Build - Remote Flag Required + +**PROBLEM:** Build fails without `--remote` flag and `ASTRO_DB_REMOTE_URL` + +```dockerfile +# ❌ WRONG - Build fails +RUN npm run build +``` + +**SOLUTION:** Set env var and use `--remote` flag + +```dockerfile +# ✅ CORRECT - Astro DB initialized properly +RUN mkdir -p ./data && ASTRO_DB_REMOTE_URL=file:./data/consent.db npx astro build --remote +``` + +**WHY:** +- Astro DB requires explicit connection info at build time +- `--remote` flag tells Astro to connect to database +- `ASTRO_DB_REMOTE_URL` must be set during build +- Data directory must exist before build + +--- + +### 4. Package Installation - Production Dependencies + +**PROBLEM:** `npm ci --production` skips build-time dependencies + +```dockerfile +# ❌ WRONG - Missing @astrojs/node at build time +RUN npm ci --production +``` + +**SOLUTION:** Use `npm install --production` + +```dockerfile +# ✅ CORRECT - All dependencies available +RUN npm install --production +``` + +**WHY:** +- `npm ci --production` is too strict +- Some packages needed at both build and runtime +- `npm install --production` handles this correctly + +--- + +## 📝 Skill Template Updates Needed + +### Updated Dockerfile Template + +```dockerfile +FROM node:20-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci +COPY . . +# Create data directory BEFORE build (Astro DB requirement) +RUN mkdir -p ./data && ASTRO_DB_REMOTE_URL=file:./data/consent.db npx astro build --remote + +FROM node:20-alpine +WORKDIR /app +COPY package*.json ./ +# Use npm install, not npm ci --production +RUN npm install --production +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/db ./db +COPY --from=builder /app/data ./data + +# SQLite runtime for Astro DB +RUN apk add --no-cache sqlite-libs + +EXPOSE 80 + +# Critical environment variables for Docker networking +ENV NODE_ENV=production +ENV ASTRO_DB_REMOTE_URL=file:/app/data/consent.db +ENV HOST=0.0.0.0 +ENV PORT=80 +ENV ADMIN_PASSWORD=${ADMIN_PASSWORD} + +# Use production server, NOT astro preview +CMD ["node", "dist/server/entry.mjs"] +``` + +--- + +### Updated astro.config.mjs Template + +```javascript +// @ts-check +import { defineConfig } from 'astro/config'; +import db from '@astrojs/db'; +import node from '@astrojs/node'; + +import tailwindcss from '@tailwindcss/vite'; + +export default defineConfig({ + integrations: [db()], + adapter: node({ + mode: 'standalone' + // Don't set host/port here - use environment variables instead + }), + vite: { + plugins: [tailwindcss()], + server: { + host: true // Allow all hosts in development + } + } +}); +``` + +--- + +### Updated package.json Template + +```json +{ + "dependencies": { + "astro": "^5.x.x", + "@astrojs/db": "^0.19.0", + "@astrojs/node": "^9.x.x", + "@libsql/client": "^0.17.0", + "drizzle-orm": "^0.45.1", + "astro-consent": "^1.0.17", + "@tailwindcss/vite": "^4.x.x", + "tailwindcss": "^4.x.x" + }, + "scripts": { + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview", + "start": "node dist/server/entry.mjs" + } +} +``` + +--- + +## 🔧 Workflow Improvements + +### 1. Pre-Flight Checklist (MUST ask before starting) + +```markdown +## Critical Questions: + +1. **Deployment Platform:** + - Easypanel? (requires HOST=0.0.0.0) + - Vercel/Netlify? (different adapter needed) + - Docker only? (full Dockerfile) + +2. **Database Requirements:** + - Consent logging needed? (Astro DB) + - Just static site? (no DB needed) + - External DB? (Turso, PlanetScale, etc.) + +3. **Analytics:** + - Umami instance available? (get credentials) + - Use Umami Cloud? (API key needed) + - No analytics? (skip integration) + +4. **Admin Dashboard:** + - Need consent logs viewer? (create /admin routes) + - Default password? (MUST change in production) +``` + +--- + +### 2. Build Process (MUST test before deploy) + +```markdown +## Testing Steps (MANDATORY BEFORE DEPLOY): + +1. **Test Build Locally:** + ```bash + rm -rf dist data + mkdir -p data + ASTRO_DB_REMOTE_URL=file:./data/consent.db npx astro build --remote + ``` + +2. **Test Server Locally:** + ```bash + HOST=0.0.0.0 PORT=4321 node dist/server/entry.mjs & + curl http://localhost:4321 + pkill -f entry.mjs + ``` + +3. **Verify:** + - ✅ Build completes without errors + - ✅ Server starts successfully + - ✅ Homepage loads + - ✅ API routes respond + - ✅ Database initialized + ``` + +--- + +### 3. Umami Integration (Automatic) + +```markdown +## Automated Workflow: + +1. **Check for Umami credentials:** + ```bash + # Check global ~/.config/opencode/.env + cat ~/.config/opencode/.env | grep UMAMI + ``` + +2. **If credentials exist:** + ```bash + # Auto-create website + python3 skills/umami/scripts/umami_client.py \ + --action create-website \ + --website-name "{site-name}" \ + --website-domain "{domain}" + ``` + +3. **Update configuration automatically:** + - `.env` file with UMAMI_WEBSITE_ID + - `Layout.astro` with actual tracking script + - No placeholder values + ``` + +--- + +### 4. Error Handling & Troubleshooting + +```markdown +## Common Errors & Solutions: + +### "Cannot find module '@astrojs/node'" +- **Cause:** Missing from production dependencies +- **Fix:** Add to package.json dependencies (not devDependencies) + +### "Attempting to build without the --remote flag" +- **Cause:** Astro DB needs explicit connection +- **Fix:** Add `ASTRO_DB_REMOTE_URL=file:./data/consent.db` and `--remote` flag + +### "Unable to open connection to local database" +- **Cause:** Data directory doesn't exist +- **Fix:** Run `mkdir -p ./data` before build + +### "Blocked request. This host is not allowed" +- **Cause:** Server listening on localhost only +- **Fix:** Add `ENV HOST=0.0.0.0` to Dockerfile + +### "Server listening on http://localhost:80" (in container) +- **Cause:** Wrong HOST environment +- **Fix:** Use `ENV HOST=0.0.0.0` not adapter config +``` + +--- + +## 📚 New Documentation Templates + +### PDPA-COMPLIANCE.md (Auto-generated) + +```markdown +# PDPA Compliance Checklist + +## Privacy Policy Requirements (Section 36) +- [ ] Data Controller Information +- [ ] Types of Data Collected +- [ ] Purpose of Data Processing +- [ ] Legal Basis for Processing +- [ ] Data Retention Period +- [ ] Data Sharing & Disclosure +- [ ] Cross-border Transfers +- [ ] Automated Decision Making +- [ ] Cookies & Tracking Technologies +- [ ] Data Subject Rights (8 rights) +- [ ] Data Security Measures +- [ ] DPO Contact +- [ ] Right to Lodge Complaint +- [ ] Policy Version & Last Updated + +## Cookie Consent Requirements +- [ ] Opt-in model (not pre-ticked) +- [ ] Granular choices +- [ ] Equal prominence for Accept/Reject +- [ ] Withdrawal mechanism +- [ ] Script blocking until consent +- [ ] Consent logging (10+ years) + +## Admin Dashboard +- URL: `/admin/consent-logs` +- Default Password: `{password}` (⚠️ CHANGE THIS!) +- Features: View logs, delete records, export CSV +``` + +--- + +## 🎯 Skill Enhancement Priority + +### HIGH PRIORITY (Fix Immediately) + +1. ✅ **Update Dockerfile template** - Production server + env vars +2. ✅ **Add build testing step** - Test locally before deploy +3. ✅ **Umami auto-integration** - Use credentials from global .env +4. ✅ **Add Astro DB requirements** - --remote flag, mkdir data + +### MEDIUM PRIORITY (Next Sprint) + +1. ⏳ **Error detection** - Auto-detect common errors and suggest fixes +2. ⏳ **Deployment verification** - Automated post-deploy testing +3. ⏳ **Environment variable validation** - Check all required vars before build +4. ⏳ **Rollback procedure** - Document and automate rollback + +### LOW PRIORITY (Future Enhancement) + +1. 📋 **Multi-platform support** - Vercel, Netlify, Cloudflare adapters +2. 📋 **Database migration** - Auto-migrate Astro DB schema changes +3. 📋 **Performance monitoring** - Built-in uptime and error tracking +4. 📋 **SEO automation** - Auto-generate sitemap, robots.txt, meta tags + +--- + +## 📖 Learning Resources + +### Internal Documentation +- `/skills/website-creator/KNOWN-ISSUES.md` - Common problems & solutions +- `/skills/website-creator/DEPLOYMENT-GUIDE.md` - Platform-specific guides +- `/skills/website-creator/TESTING-CHECKLIST.md` - Pre-deploy testing + +### External References +- [Astro DB Production Guide](https://docs.astro.build/en/guides/astro-db/#production) +- [Node Adapter Docs](https://docs.astro.build/en/guides/integrations-guide/node/) +- [Docker Networking](https://docs.docker.com/network/) +- [PDPA Guidelines](https://www.pdpc.or.th/) + +--- + +## ✅ Implementation Status + +| Improvement | Status | Priority | +|-------------|--------|----------| +| Dockerfile production server | ✅ Ready | HIGH | +| HOST=0.0.0.0 environment variable | ✅ Ready | HIGH | +| Astro DB --remote flag | ✅ Ready | HIGH | +| npm install vs npm ci | ✅ Ready | HIGH | +| Local build testing | ✅ Ready | HIGH | +| Umami auto-integration | ✅ Ready | HIGH | +| Error detection | 📝 Planned | MEDIUM | +| Deployment verification | 📝 Planned | MEDIUM | + +--- + +**Last Updated:** March 9, 2026 +**Based On:** moreminimore-redesign PDPA implementation +**Next Review:** After next 3 deployments