moreminimore-website/WEBSITE-CREATOR-IMPROVEMENTS.md

# 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