aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# Grab Worker - Deployment Guide
2
3Complete deployment guide for the Aesthetic Computer screenshot generation service.
4
5## 🎯 Current Status
6
7**Production URL**: https://grab.aesthetic.computer
8**Workers.dev URL**: https://aesthetic-grab.aesthetic-computer.workers.dev
9**Latest Version**: e77346d0-3732-4bd2-b03b-e932dc50fac9
10
11### Quick Test
12```bash
13# Health check
14curl "https://grab.aesthetic.computer/health"
15
16# Icon (128x128)
17curl "https://grab.aesthetic.computer/icon/128x128/prompt.png" --output test.png
18
19# Preview (1200x630)
20curl "https://grab.aesthetic.computer/preview/1200x630/prompt.png" --output test.png
21```
22
23---
24
25## 🚀 Deployment
26
27### Method 1: Simple Deploy (Current Domain)
28
29If `grab.aesthetic.computer` is already configured:
30
31```bash
32cd /workspaces/aesthetic-computer/grab
33npm run deploy
34```
35
36This updates the worker code while keeping existing DNS/domain configuration.
37
38### Method 2: Deploy with Custom Domain
39
40The `wrangler.toml` includes the custom domain configuration:
41
42```toml
43routes = [
44 { pattern = "grab.aesthetic.computer", custom_domain = true }
45]
46```
47
48When you run `npm run deploy`, Wrangler automatically:
491. Deploys the worker code
502. Configures the custom domain route
513. Sets up DNS (if using Cloudflare-managed domain)
52
53**Note**: Custom domains require your domain to be on Cloudflare. Since `aesthetic.computer` is already managed by Cloudflare, this works automatically.
54
55---
56
57## 📋 Pre-Deployment Checklist
58
59- [ ] Cloudflare account access (`CLOUDFLARE_API_TOKEN` in environment)
60- [ ] `aesthetic.computer` domain on Cloudflare
61- [ ] Browser Rendering enabled on account
62- [ ] Dependencies installed: `npm install`
63- [ ] Types checked: `npm run type-check`
64
65---
66
67## 🔧 Configuration
68
69### Environment Variables (wrangler.toml)
70
71```toml
72[vars]
73ENVIRONMENT = "production"
74DOMAIN = "grab.aesthetic.computer"
75
76# Cache Configuration
77CACHE_TTL_SECONDS = "3600" # 1 hour
78CDN_CACHE_TTL_SECONDS = "86400" # 24 hours
79
80# Screenshot Configuration
81MAX_SCREENSHOT_AGE_MS = "604800000" # 7 days
82BROWSER_TIMEOUT_MS = "30000" # 30 seconds
83MAX_VIEWPORT_WIDTH = "1920"
84MAX_VIEWPORT_HEIGHT = "1080"
85
86# Rate Limiting
87MAX_REQUESTS_PER_MINUTE = "60"
88MAX_BROWSER_SESSIONS = "10"
89```
90
91### Cloudflare Requirements
92
93**Browser Rendering API**:
94- Automatically included with Workers Paid plan ($5/month)
95- Provides headless Chrome browser instances
96- Used for screenshot generation
97
98**Durable Objects**:
99- Included with Workers Paid plan
100- Used for browser session management
101- Reduces cold start times
102
103---
104
105## 🧪 Testing After Deployment
106
107### 1. Health Check
108```bash
109curl "https://grab.aesthetic.computer/health"
110# Expected: {"status":"ok","timestamp":"...","environment":"production"}
111```
112
113### 2. Icon Generation
114```bash
115curl "https://grab.aesthetic.computer/icon/128x128/prompt.png" --output icon.png
116file icon.png
117# Expected: PNG image data, 128 x 128
118```
119
120### 3. Preview Generation
121```bash
122curl "https://grab.aesthetic.computer/preview/1200x630/prompt.png" --output preview.png
123file preview.png
124# Expected: PNG image data, 1200 x 630
125```
126
127### 4. Cache Headers
128```bash
129curl -I "https://grab.aesthetic.computer/icon/128x128/prompt.png"
130# Expected:
131# Cache-Control: public, max-age=3600
132# CF-Cache-Status: HIT (on second request)
133```
134
135### 5. Error Handling
136```bash
137# Invalid format
138curl "https://grab.aesthetic.computer/invalid"
139# Expected: {"error":"Invalid request format..."}
140
141# Oversized dimensions
142curl "https://grab.aesthetic.computer/icon/5000x5000/prompt.png"
143# Expected: {"error":"Invalid dimensions..."}
144```
145
146---
147
148## 📊 Monitoring
149
150### View Logs
151```bash
152cd /workspaces/aesthetic-computer/grab
153npm run logs
154```
155
156### Check Recent Deployments
157```bash
158npx wrangler deployments list
159```
160
161### Monitor Usage
162- Dashboard: https://dash.cloudflare.com
163- Navigate to: Workers & Pages → aesthetic-grab
164- View: Requests, Errors, CPU Time, Duration
165
166### Key Metrics
167- **Success Rate**: Should be >99%
168- **Response Time**: 7-15 seconds for first request, <1s for cached
169- **Cache Hit Rate**: Should increase over time
170- **Error Rate**: Monitor 4xx/5xx responses
171
172---
173
174## 🔄 Rollback
175
176If issues occur after deployment:
177
178```bash
179cd /workspaces/aesthetic-computer/grab
180
181# List recent deployments
182npx wrangler deployments list
183
184# Rollback to previous version
185npx wrangler rollback [version-id]
186```
187
188---
189
190## 🏗️ Architecture
191
192```
193User Request
194 ↓
195grab.aesthetic.computer (Custom Domain)
196 ↓
197Cloudflare Workers (aesthetic-grab)
198 ↓
199Durable Object (Browser session management)
200 ↓
201Browser Rendering API (@cloudflare/puppeteer)
202 ↓
203Screenshot Generation (PNG)
204 ↓
205Response (with Cache-Control headers)
206 ↓
207Cloudflare CDN (24hr cache)
208```
209
210### Components
211- **Workers**: Serverless compute, handles HTTP requests
212- **Durable Objects**: Manages browser session lifecycle
213- **Browser Rendering**: Provides Chrome instances for screenshots
214- **CDN**: Caches generated screenshots globally
215
216---
217
218## 📁 Integration Points
219
220### parse.mjs
221```javascript
222// Lines 487-494
223const iconURL = `https://grab.aesthetic.computer/icon/128x128/${pieceParam}${query}`;
224const previewURL = `https://grab.aesthetic.computer/preview/1200x630/${pieceParam}${query}`;
225```
226
227### netlify.toml
228```toml
229# Lines 285-290: Icon redirect
230[[redirects]]
231 from = "/aesthetic.computer/api/icon/:piece"
232 to = "https://grab.aesthetic.computer/icon/128x128/:piece.png"
233 status = 200
234
235# Lines 306-310: Preview redirect
236[[redirects]]
237 from = "/aesthetic.computer/api/preview/:piece"
238 to = "https://grab.aesthetic.computer/preview/1200x630/:piece.png"
239 status = 200
240```
241
242---
243
244## 🐛 Troubleshooting
245
246### "Could not resolve host: grab.aesthetic.computer"
247- DNS not propagated yet (wait 5-10 minutes)
248- Check DNS: `dig grab.aesthetic.computer`
249- Verify custom domain in wrangler.toml
250
251### "Browser rendering is not available"
252- Ensure Workers Paid plan is active
253- Check account settings in Cloudflare dashboard
254- Browser Rendering API should be enabled
255
256### Screenshots are empty/white
257- Check Browser Rendering API status
258- Verify viewport dimensions in env vars
259- Review logs: `npm run logs`
260- Ensure piece exists on aesthetic.computer
261
262### Slow response times
263- First request is always slower (browser startup)
264- Check if Durable Object is working (session reuse)
265- Monitor Browser Rendering API latency
266- Consider adjusting `BROWSER_TIMEOUT_MS`
267
268### High error rates
269- Check rate limiting (`MAX_REQUESTS_PER_MINUTE`)
270- Review browser timeout settings
271- Monitor Durable Object errors
272- Check for upstream issues (aesthetic.computer availability)
273
274---
275
276## 📝 Related Documentation
277
278- **README.md**: Usage guide and API reference
279- **VIDEO-FUTURE.md**: Future video capture infrastructure
280- **docs/**: Detailed technical documentation
281 - `ANIMATED-GIF-STATUS.md`: Video recording research
282 - `INTEGRATION-SUMMARY.md`: System integration details
283 - `DEV-SETUP.md`: Local development guide
284
285---
286
287## 🎯 Next Steps
288
2891. **Monitor Production**: Watch logs and metrics for first few days
2902. **Test Integration**: Verify parse.mjs and netlify.toml redirects
2913. **Cache Tuning**: Adjust TTLs based on usage patterns
2924. **Video Capture**: When needed, see VIDEO-FUTURE.md for VPS approach
293
294---
295
296**Last Updated**: October 14, 2025
297**Deployed Version**: e77346d0-3732-4bd2-b03b-e932dc50fac9