docs: Add WEBSITE-CREATOR-IMPROVEMENTS.md with lessons learned from PDPA implementation
This commit is contained in:
Kunthawat Greethong
410
WEBSITE-CREATOR-IMPROVEMENTS.md
Normal file
410
WEBSITE-CREATOR-IMPROVEMENTS.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user