-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathtutorial-deploy.html
More file actions
437 lines (369 loc) · 22.7 KB
/
tutorial-deploy.html
File metadata and controls
437 lines (369 loc) · 22.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>WREN — Deploy Tutorial</title>
<meta name="description" content="Deploy a static site to WREN in 5 minutes. Preview before going live. Promote when ready." />
<link rel="stylesheet" href="/styles.css" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="alternate icon" href="/favicon.ico" />
<link rel="manifest" href="/site.webmanifest" />
<meta name="theme-color" content="#4338ca" />
<style>
.tutorial-layout {
display: grid; grid-template-columns: 220px 1fr; gap: 0;
max-width: var(--container-max); margin: 0 auto;
padding: var(--nav-height) 24px 0; min-height: calc(100vh - var(--nav-height));
}
.tutorial-sidebar {
position: sticky; top: calc(var(--nav-height) + 24px); align-self: start;
padding: 32px 20px 32px 0; font-size: 14px;
max-height: calc(100vh - var(--nav-height) - 48px); overflow-y: auto;
}
.tutorial-sidebar__title { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.08em; color: var(--color-muted); margin-bottom: 12px; }
.tutorial-sidebar__list { list-style: none; display: flex; flex-direction: column; gap: 2px; padding: 0; }
.tutorial-sidebar__list a { display: block; padding: 5px 8px; border-radius: 4px; color: var(--color-muted); font-size: 13px; }
.tutorial-sidebar__list a:hover { background: #f5f3ff; color: var(--color-text); }
.tutorial-sidebar__also { margin-top: 24px; font-size: 13px; }
.tutorial-sidebar__also h5 { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.08em; color: var(--color-muted); margin: 0 0 8px; }
.tutorial-sidebar__also a { display: block; padding: 4px 0; color: var(--color-primary); }
.tutorial-main { padding: 48px 0 80px 32px; border-left: 1px solid var(--color-border); min-width: 0; }
.tutorial-section { margin-bottom: 48px; }
.tutorial-section h2 { font-size: 24px; font-weight: 700; margin-bottom: 8px; display: flex; align-items: center; gap: 10px; }
.tutorial-section h3 { font-size: 16px; font-weight: 600; margin: 24px 0 8px; }
.tutorial-section p { color: var(--color-muted); margin-bottom: 16px; max-width: 680px; line-height: 1.7; }
.tutorial-section p code, .tutorial-section li code { font-family: var(--font-mono); font-size: 0.85em; background: #f5f3ff; border: 1px solid var(--color-border); border-radius: 3px; padding: 1px 5px; color: var(--color-primary-dark); }
.tutorial-divider { border: none; border-top: 1px solid var(--color-border); margin: 40px 0; }
.step-badge { display: inline-flex; align-items: center; justify-content: center; width: 28px; height: 28px; border-radius: 50%; background: var(--color-primary); color: #fff; font-size: 13px; font-weight: 700; }
.code-block { background: var(--color-code-bg); border-radius: 8px; overflow: hidden; font-size: 13px; margin: 12px 0 20px; max-width: 680px; }
.code-block__header { display: flex; align-items: center; gap: 8px; padding: 8px 14px; border-bottom: 1px solid rgba(255,255,255,0.07); }
.code-block__lang { font-family: var(--font-mono); font-size: 11px; color: rgba(255,255,255,0.4); text-transform: uppercase; letter-spacing: 0.06em; }
.code-block pre { padding: 14px 16px; overflow-x: auto; line-height: 1.65; color: #e2e8f0; margin: 0; }
.callout { border-radius: 8px; padding: 14px 16px; margin: 20px 0; font-size: 14px; max-width: 680px; line-height: 1.6; }
.callout--info { background: #f0fdf4; border-left: 3px solid #10b981; color: #065f46; }
.callout strong { font-weight: 700; }
.callout code { font-family: var(--font-mono); font-size: 0.85em; background: rgba(0,0,0,0.08); border-radius: 3px; padding: 1px 4px; }
.steps-inline { list-style: none; margin: 0 0 20px; padding: 0; display: flex; flex-direction: column; gap: 6px; }
.steps-inline li { display: flex; align-items: baseline; gap: 10px; font-size: 14px; color: var(--color-muted); line-height: 1.6; }
.steps-inline li .n { display: inline-flex; align-items: center; justify-content: center; width: 20px; height: 20px; border-radius: 50%; background: var(--color-border); color: var(--color-text); font-size: 11px; font-weight: 700; flex-shrink: 0; }
@media (max-width: 768px) {
.tutorial-layout { grid-template-columns: 1fr; overflow-x: hidden; padding-left: 16px; padding-right: 16px; }
.tutorial-sidebar { display: none; }
.tutorial-main { border-left: none; padding-left: 0; }
pre { font-size: 12px; }
}
</style>
</head>
<body>
<nav class="nav">
<div class="nav__inner">
<a href="/" class="nav__logo"><img src="/wren-logo.svg" alt="WREN" class="nav__logo-img" />WREN</a>
<ul class="nav__links">
<li><a href="/tutorial/deploy" style="color:var(--color-primary);font-weight:600">Tutorial</a></li>
<li><a href="/docs">Docs</a></li>
<li><a href="/#clients">Libraries</a></li>
<li><a href="/#pricing">Pricing</a></li>
<li><a href="/projects">Projects</a></li>
<li><a href="/admin">Admin</a></li>
</ul><button class="nav__hamburger" onclick="document.querySelector('.nav__links').classList.toggle('open')" aria-label="Menu"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 12h18M3 6h18M3 18h18"/></svg></button>
</div>
</nav>
<div class="tutorial-layout">
<aside class="tutorial-sidebar">
<div class="tutorial-sidebar__inner">
<h4 class="tutorial-sidebar__title">Deploy Tutorial</h4>
<nav>
<ul class="tutorial-sidebar__list">
<li><a href="#prereqs">Prerequisites</a></li>
<li><a href="#create-site">1. Create a site</a></li>
<li><a href="#first-deploy">2. First deploy</a></li>
<li><a href="#see-it-live">3. See it live</a></li>
<li><a href="#make-changes">4. Make changes</a></li>
<li><a href="#deploy-preview">5. Deploy as preview</a></li>
<li><a href="#promote">6. Promote to published</a></li>
<li><a href="#add-data">7. Add JSON data</a></li>
<li><a href="#rollback">8. Rollback</a></li>
<li><a href="#cleanup">9. Cleanup & --clean</a></li>
<li><a href="#whats-next">What's next</a></li>
</ul>
</nav>
<div class="tutorial-sidebar__also">
<h5>Other tutorials</h5>
<a href="/tutorial">Full WREN tutorial</a>
<a href="/tutorial/trees">Trees tutorial</a>
</div>
</div>
</aside>
<main class="tutorial-main">
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="prereqs">
<h2>Deploy Tutorial</h2>
<p>Deploy a static site to WREN, preview changes before going live, and promote when ready. Takes about 10 minutes.</p>
<h3 id="prereqs">Prerequisites</h3>
<ol class="steps-inline">
<li><span class="n">1</span> A running WREN instance (local Docker or <a href="https://wren.aemwip.com">wren.aemwip.com</a>)</li>
<li><span class="n">2</span> The WREN CLI installed: <code>bun install -g @usewren/cli</code> (or run from the repo with <code>bun run cli/index.ts</code>)</li>
<li><span class="n">3</span> An account — sign up via the <a href="/admin">Admin UI</a></li>
</ol>
<div class="callout callout--info">
<strong>Configure the CLI.</strong> Point it at your server and sign in:
</div>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>wren config --url https://wren.aemwip.com
wren auth login -e you@example.com -p yourpassword
wren me # confirm: shows your principal, org, and role</pre>
</div>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="create-site">
<h2><span class="step-badge">1</span> Create a simple site</h2>
<p>Let’s make a minimal static site to deploy. Create a folder with a few files:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>mkdir my-site && cd my-site
cat > index.html <<'EOF'
<!DOCTYPE html>
<html>
<head>
<title>My WREN Site</title>
<link rel="stylesheet" href="/assets/style.css">
</head>
<body>
<h1>Hello from WREN!</h1>
<p>Deployed with <code>wren deploy</code>.</p>
<a href="/about.html">About</a>
</body>
</html>
EOF
cat > about.html <<'EOF'
<!DOCTYPE html>
<html>
<head>
<title>About — My WREN Site</title>
<link rel="stylesheet" href="/assets/style.css">
</head>
<body>
<h1>About</h1>
<p>This site is versioned and served by WREN.</p>
<a href="/">Home</a>
</body>
</html>
EOF
mkdir -p assets
cat > assets/style.css <<'EOF'
body { font-family: system-ui, sans-serif; max-width: 640px; margin: 2rem auto; padding: 0 1rem; line-height: 1.6; }
h1 { color: #4338ca; }
a { color: #6366f1; }
EOF</pre>
</div>
<p>You now have <code>index.html</code>, <code>about.html</code>, and <code>assets/style.css</code>.</p>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="first-deploy">
<h2><span class="step-badge">2</span> First deploy</h2>
<p>Deploy the folder to a WREN tree. The <code>--public</code> flag creates a permission rule so anyone can view the site.</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>wren deploy . --tree my-site --public</pre>
</div>
<p>Output:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">output</span></div>
<pre>Found 3 files in .
Creating binary collection: my-site-assets
Uploaded 3 files...
Created public read permission for tree:my-site
Deployed to tree "my-site": 3 uploaded, 0 unchanged, 3 new paths
Preview: https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html</pre>
</div>
<div class="callout callout--info">
<strong>What just happened:</strong>
<ol style="margin:.5rem 0 0;padding-left:1.2rem">
<li>A binary collection <code>my-site-assets</code> was created to store your files</li>
<li>Each file was uploaded as a versioned binary document</li>
<li>Each file was assigned to a tree path matching its local path</li>
<li>A <code>principal=*</code> read permission was added so the site is public</li>
</ol>
</div>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="see-it-live">
<h2><span class="step-badge">3</span> See it live</h2>
<p>Open the URL from the output in your browser. Your site is live — HTML, CSS, and all. Links between pages work because tree paths match your directory structure.</p>
<p>You can also check it from the CLI:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>wren tree view my-site</pre>
</div>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">output</span></div>
<pre> /about.html [my-site-assets v1] size: 234
/assets/style.css [my-site-assets v1] size: 168
/index.html [my-site-assets v1] size: 265</pre>
</div>
<p>Every file is at version 1. The tree serves them at their local paths.</p>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="make-changes">
<h2><span class="step-badge">4</span> Make a change</h2>
<p>Edit <code>index.html</code> — change the heading:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">html</span></div>
<pre><h1>Hello from WREN! — Updated</h1>
<p>This is version 2 of the site.</p></pre>
</div>
<p>Re-deploy. Only the changed file uploads:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>wren deploy . --tree my-site</pre>
</div>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">output</span></div>
<pre>Found 3 files in .
Deployed to tree "my-site": 1 uploaded, 2 unchanged, 0 new paths</pre>
</div>
<p>WREN detected that <code>about.html</code> and <code>style.css</code> haven’t changed (same file size) and skipped them. Only <code>index.html</code> was uploaded as version 2.</p>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="deploy-preview">
<h2><span class="step-badge">5</span> Deploy as preview</h2>
<p>What if you want to test changes before the public sees them? Deploy with a label:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre># Make another change
sed -i '' 's/Updated/v3 Preview/' index.html
# Deploy with --label preview
wren deploy . --tree my-site --label preview</pre>
</div>
<p>The public site is unchanged — visitors still see the current version. You can see the preview by adding <code>?label=preview</code> to any URL:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre># Public site (unchanged):
open https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html
# Your preview (new version):
open https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html?label=preview</pre>
</div>
<div class="callout callout--info">
<strong>How labels control visibility:</strong> If you created a permission with <code>labelFilter: "published"</code>, anonymous visitors would <em>only</em> see the published label. The <code>--public</code> flag on the first deploy didn’t set a labelFilter, so visitors currently see the latest version. To enable preview → publish flow, set a labelFilter on the permission rule via the Admin UI or the API.
</div>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="promote">
<h2><span class="step-badge">6</span> Promote to published</h2>
<p>Happy with the preview? Promote it:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>wren promote my-site --from preview</pre>
</div>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">output</span></div>
<pre>Promoting 3 documents in tree "my-site" → label "published" (from "preview")...
Done: 3 documents labeled "published".
Public: https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html?label=published</pre>
</div>
<p>The <code>published</code> label now points to the same versions as <code>preview</code>. If your permission has <code>labelFilter: "published"</code>, the public site is updated.</p>
<p>You can also promote without a source label — this labels the current (latest) version of every document in the tree:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>wren promote my-site # defaults to --label published</pre>
</div>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="add-data">
<h2><span class="step-badge">7</span> Add JSON data alongside your site</h2>
<p>WREN isn’t just file hosting. Your site can read structured data from a collection via the API:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre># Create a JSON collection for your site's content
wren create pages '{"slug":"home","title":"Welcome","body":"This content is stored in WREN."}'
wren create pages '{"slug":"about","title":"About Us","body":"We are a team building with WREN."}'
# Your site's JavaScript can fetch from the public API:
# GET /api/v1/orgs/your-slug/pages</pre>
</div>
<p>Now your static site <em>and</em> its content data live in the same system. When you promote, both the HTML files and the JSON content can move to <code>published</code> together.</p>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="rollback">
<h2><span class="step-badge">8</span> Rollback</h2>
<p>Every file upload creates a new version. You can roll back any individual file:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre># See version history for a document
wren versions my-site-assets <document-id>
# Roll back to version 1
wren rollback my-site-assets <document-id> 1
# Re-promote to make the rollback live
wren promote my-site</pre>
</div>
<p>Or roll back the <em>entire site</em> by promoting an older label. If you labeled yesterday’s deploy as <code>v1</code>, just re-promote it:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>wren promote my-site --from v1 --label published</pre>
</div>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="cleanup">
<h2><span class="step-badge">9</span> Cleanup: remove deleted files</h2>
<p>If you delete a file locally and redeploy, the old tree path stays by default. Use <code>--clean</code> to remove paths that no longer exist in your local directory:</p>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">bash</span></div>
<pre>rm about.html
wren deploy . --tree my-site --clean</pre>
</div>
<div class="code-block">
<div class="code-block__header"><span class="code-block__lang">output</span></div>
<pre>Found 2 files in .
Deployed to tree "my-site": 0 uploaded, 2 unchanged, 0 new paths, 1 removed</pre>
</div>
<p><code>/about.html</code> is removed from the tree. The document still exists in the collection (soft-deleted or just unassigned) — nothing is permanently lost.</p>
</section>
<hr class="tutorial-divider" />
<!-- ─────────────────────────────────────────────────────────── -->
<section class="tutorial-section" id="whats-next">
<h2>What’s next</h2>
<ul style="line-height:2">
<li><a href="/tutorial">Full WREN tutorial</a> — covers the Admin UI, collections, schemas, labels, permissions, and more</li>
<li><a href="/docs">API Docs</a> — interactive reference for every endpoint</li>
<li><a href="/projects">Projects</a> — see live sites deployed on this WREN instance</li>
<li><a href="/admin">Admin UI</a> — browse your deployed files, manage permissions, and edit content</li>
</ul>
<div class="callout callout--info">
<strong>Quick reference:</strong>
<div class="code-block" style="margin-top:.75rem">
<pre>wren deploy ./dist --tree mysite --public # first deploy
wren deploy ./dist --tree mysite --label preview # preview deploy
wren promote mysite --from preview # go live
wren promote mysite # label current as published
wren deploy ./dist --tree mysite --clean # remove deleted files
wren tree view mysite # inspect the tree</pre>
</div>
</div>
</section>
</main>
</div>
<footer class="footer">
<div class="container">
<div class="footer__inner">
<p class="footer__brand"><strong>WREN</strong> — deploy, version, serve</p>
<ul class="footer__links">
<li><a href="/admin">Admin UI</a></li>
<li><a href="/docs">API Docs</a></li>
<li><a href="/projects">Projects</a></li>
</ul>
</div>
<p class="footer__copy">© 2026 WREN. Cloud or self-hosted. No vendor lock-in.</p>
</div>
</footer>
</body>
</html>