-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathgetting-started.html
More file actions
639 lines (567 loc) · 20.9 KB
/
getting-started.html
File metadata and controls
639 lines (567 loc) · 20.9 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
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Getting Started - borg-anchor</title>
<meta name="description" content="Learn how to use borg-anchor for Bitcoin-timestamped backups - beginner's guide">
<style>
:root {
--bg: #fafafa;
--card: #ffffff;
--text: #2d3748;
--muted: #718096;
--accent: #3182ce;
--accent-light: #ebf4ff;
--border: #e2e8f0;
--code-bg: #1a202c;
--code-text: #e2e8f0;
--success: #48bb78;
--warning: #ed8936;
}
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: var(--bg);
color: var(--text);
line-height: 1.6;
}
.container { max-width: 900px; margin: 0 auto; padding: 2rem; }
nav {
display: flex;
justify-content: space-between;
align-items: center;
padding: 1rem 0;
border-bottom: 1px solid var(--border);
margin-bottom: 2rem;
}
nav a {
color: var(--accent);
text-decoration: none;
}
nav .brand {
font-weight: 700;
font-size: 1.1rem;
color: var(--text);
}
header {
text-align: center;
padding: 2rem 0 3rem;
}
h1 {
font-size: 2.2rem;
font-weight: 700;
margin-bottom: 0.5rem;
}
.subtitle {
font-size: 1.1rem;
color: var(--muted);
}
.toc {
background: var(--card);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1.5rem;
margin-bottom: 3rem;
}
.toc h2 {
font-size: 1rem;
margin-bottom: 1rem;
color: var(--muted);
text-transform: uppercase;
letter-spacing: 0.5px;
}
.toc ol {
margin-left: 1.5rem;
}
.toc li {
margin-bottom: 0.5rem;
}
.toc a {
color: var(--accent);
text-decoration: none;
}
.toc a:hover {
text-decoration: underline;
}
section {
margin: 3rem 0;
}
h2 {
font-size: 1.5rem;
margin-bottom: 1rem;
padding-bottom: 0.5rem;
border-bottom: 2px solid var(--border);
}
h3 {
font-size: 1.2rem;
margin: 1.5rem 0 0.75rem;
color: var(--text);
}
p {
margin-bottom: 1rem;
color: var(--muted);
}
p.lead {
font-size: 1.1rem;
color: var(--text);
}
pre {
background: var(--code-bg);
color: var(--code-text);
padding: 1.5rem;
border-radius: 8px;
overflow-x: auto;
font-family: 'SF Mono', Monaco, monospace;
font-size: 0.9rem;
line-height: 1.5;
margin: 1rem 0;
}
code {
font-family: 'SF Mono', Monaco, monospace;
background: var(--accent-light);
padding: 0.2rem 0.4rem;
border-radius: 4px;
font-size: 0.9em;
}
pre code {
background: none;
padding: 0;
}
.comment { color: #68d391; }
.prompt { color: #68d391; }
.callout {
padding: 1rem 1.5rem;
border-radius: 8px;
margin: 1.5rem 0;
border-left: 4px solid;
}
.callout-info {
background: var(--accent-light);
border-color: var(--accent);
}
.callout-success {
background: #f0fff4;
border-color: var(--success);
}
.callout-warning {
background: #fffaf0;
border-color: var(--warning);
}
.callout p {
margin: 0;
color: var(--text);
}
.callout strong {
display: block;
margin-bottom: 0.25rem;
}
.step {
display: flex;
gap: 1rem;
margin: 1.5rem 0;
}
.step-num {
flex-shrink: 0;
width: 2rem;
height: 2rem;
background: var(--accent);
color: white;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-weight: 700;
font-size: 0.9rem;
}
.step-content {
flex: 1;
}
.step-content h4 {
margin-bottom: 0.5rem;
}
.quick-win {
background: var(--card);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1.5rem;
margin: 1.5rem 0;
}
.quick-win h3 {
margin-top: 0;
display: flex;
align-items: center;
gap: 0.5rem;
}
.quick-win .badge {
background: var(--success);
color: white;
font-size: 0.7rem;
padding: 0.2rem 0.5rem;
border-radius: 4px;
text-transform: uppercase;
}
.concepts {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 1rem;
margin: 1.5rem 0;
}
.concept {
background: var(--card);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1rem;
}
.concept h4 {
margin-bottom: 0.5rem;
}
.concept p {
font-size: 0.9rem;
margin: 0;
}
ul, ol {
margin: 1rem 0 1rem 1.5rem;
color: var(--muted);
}
li {
margin-bottom: 0.5rem;
}
.next-steps {
background: linear-gradient(135deg, var(--accent-light), #f0fff4);
border-radius: 8px;
padding: 2rem;
margin-top: 3rem;
text-align: center;
}
.next-steps h2 {
border: none;
padding: 0;
}
.next-steps .links {
display: flex;
gap: 1rem;
justify-content: center;
flex-wrap: wrap;
margin-top: 1.5rem;
}
.next-steps a {
color: var(--accent);
text-decoration: none;
padding: 0.5rem 1rem;
border: 1px solid var(--accent);
border-radius: 6px;
transition: all 0.2s;
}
.next-steps a:hover {
background: var(--accent);
color: white;
}
footer {
text-align: center;
padding: 3rem 0;
color: var(--muted);
border-top: 1px solid var(--border);
margin-top: 3rem;
}
footer a { color: var(--accent); text-decoration: none; }
</style>
</head>
<body>
<div class="container">
<nav>
<a href="index.html" class="brand">borg-anchor</a>
<a href="https://github.com/solid-live/borg-anchor">GitHub</a>
</nav>
<header>
<h1>Getting Started</h1>
<p class="subtitle">From zero to Bitcoin-timestamped backups in 10 minutes</p>
</header>
<div class="toc">
<h2>On This Page</h2>
<ol>
<li><a href="#what-is-borg">What is Borg? (30-second explainer)</a></li>
<li><a href="#prerequisites">Install Prerequisites</a></li>
<li><a href="#quick-win-1">Quick Win #1: Your First Backup</a></li>
<li><a href="#quick-win-2">Quick Win #2: Fund Your Testnet Wallet</a></li>
<li><a href="#quick-win-3">Quick Win #3: Bitcoin Timestamping</a></li>
<li><a href="#quick-win-4">Quick Win #4: Restore Your Data</a></li>
<li><a href="#concepts">Key Concepts</a></li>
<li><a href="#next-steps">Next Steps</a></li>
</ol>
</div>
<!-- What is Borg -->
<section id="what-is-borg">
<h2>What is Borg?</h2>
<p class="lead">
<strong>BorgBackup</strong> (or just "Borg") is a backup program that's smart about storage.
Instead of copying everything every time, it only stores what's changed.
</p>
<div class="concepts">
<div class="concept">
<h4>Deduplication</h4>
<p>Have 10 copies of the same photo? Borg stores it once. Back up daily? Only changes are stored.</p>
</div>
<div class="concept">
<h4>Compression</h4>
<p>Your data is compressed automatically. A 100GB backup might only take 30GB of space.</p>
</div>
<div class="concept">
<h4>Encryption</h4>
<p>Optional AES-256 encryption. Even if someone gets your backup, they can't read it.</p>
</div>
</div>
<div class="callout callout-info">
<p><strong>What does borg-anchor add?</strong></p>
<p>borg-anchor wraps Borg and adds <strong>Bitcoin timestamping</strong>. After each backup, the fingerprint (hash) of your data is recorded on the Bitcoin blockchain. This creates mathematical proof that your backup existed at a specific point in time.</p>
</div>
</section>
<!-- Prerequisites -->
<section id="prerequisites">
<h2>Install Prerequisites</h2>
<p>You'll need three things installed. This takes about 5 minutes.</p>
<div class="step">
<div class="step-num">1</div>
<div class="step-content">
<h4>Install BorgBackup</h4>
<p>The backup engine that does the heavy lifting.</p>
<pre><code><span class="comment"># Ubuntu/Debian</span>
sudo apt install borgbackup
<span class="comment"># macOS</span>
brew install borgbackup
<span class="comment"># Verify installation</span>
borg --version</code></pre>
</div>
</div>
<div class="step">
<div class="step-num">2</div>
<div class="step-content">
<h4>Install Node.js 18+</h4>
<p>Required to run borg-anchor.</p>
<pre><code><span class="comment"># Check if you have it</span>
node --version
<span class="comment"># If not, install via your package manager or:</span>
<span class="comment"># https://nodejs.org/</span></code></pre>
</div>
</div>
<div class="step">
<div class="step-num">3</div>
<div class="step-content">
<h4>Install borg-anchor</h4>
<pre><code>npm install -g borg-anchor
<span class="comment"># Verify installation</span>
borg-anchor --version</code></pre>
</div>
</div>
<div class="step">
<div class="step-num">4</div>
<div class="step-content">
<h4>Install blocktrails (for Bitcoin anchoring)</h4>
<p>This handles the Bitcoin transaction side.</p>
<pre><code>git clone https://github.com/blocktrails/blocktrails.git
cd blocktrails
npm install</code></pre>
<p style="margin-top: 0.5rem; font-size: 0.9rem;">
See <a href="https://github.com/blocktrails/blocktrails">blocktrails repo</a> for full setup.
</p>
</div>
</div>
</section>
<!-- Quick Win 1 -->
<section id="quick-win-1">
<div class="quick-win">
<h3>Quick Win #1: Your First Backup <span class="badge">5 min</span></h3>
<p class="lead">Let's back up your Documents folder.</p>
<h4>Initialize a backup repository</h4>
<pre><code><span class="comment"># Create and initialize the backup location</span>
borg-anchor init ~/backups</code></pre>
<p>This creates a new directory with a Borg repository inside. You'll see output like:</p>
<pre><code> Initializing borg-anchor in /home/you/backups
Creating borg repo: /home/you/backups/repo
✓ Borg repository created
✓ Config saved: .borg-anchor.json
✓ Git initialized</code></pre>
<h4>Create your first backup</h4>
<pre><code><span class="comment"># Back up ~/Documents to ~/backups</span>
borg-anchor backup ~/Documents ~/backups --name my-backup --no-anchor</code></pre>
<div class="callout callout-success">
<p><strong>You did it!</strong></p>
<p>Your data is now safely backed up with Borg. The <code>--no-anchor</code> flag skipped Bitcoin timestamping for this test run.</p>
</div>
<h4>See what you've backed up</h4>
<pre><code>borg-anchor list</code></pre>
<p>You'll see your backup with its unique fingerprint (SHA-256 hash).</p>
</div>
</section>
<!-- Quick Win 2 -->
<section id="quick-win-2">
<div class="quick-win">
<h3>Quick Win #2: Fund Your Testnet Wallet <span class="badge">5 min</span></h3>
<p class="lead">Before you can anchor on Bitcoin, you need a keypair and some testnet coins.</p>
<div class="callout callout-info">
<p><strong>What's testnet?</strong></p>
<p>Bitcoin testnet is a separate blockchain for testing. The coins have no value, so you can experiment freely. borg-anchor uses testnet4 (<code>tbtc4</code>) by default.</p>
</div>
<h4>Generate a keypair</h4>
<p>You need a hex private key to sign Bitcoin transactions. Use our helper script or generate one manually:</p>
<pre><code><span class="comment"># Option 1: Use the helper script (recommended)</span>
<span class="comment"># Download and run from the borg-anchor repo</span>
curl -sL https://raw.githubusercontent.com/solid-live/borg-anchor/gh-pages/scripts/keygen.sh | bash
<span class="comment"># Option 2: Generate manually with openssl</span>
openssl rand -hex 32</code></pre>
<p>This outputs a 64-character hex string like:</p>
<pre><code>a1b2c3d4e5f6789...your64characterhexkey...9876543210ab</code></pre>
<div class="callout callout-warning">
<p><strong>Save your private key!</strong></p>
<p>Copy this key somewhere safe. If you lose it, you lose access to your testnet funds and UTXO chain.</p>
</div>
<h4>Configure borg-anchor with your key</h4>
<pre><code><span class="comment"># Navigate to your backup repository</span>
cd ~/backups
<span class="comment"># Store the private key in git config (local to this repo)</span>
git config nostr.privkey YOUR_64_CHAR_HEX_KEY
<span class="comment"># Initialize blocktrails (creates .blocktrail.json)</span>
blocktrails init</code></pre>
<h4>Get your testnet address</h4>
<p>Use blocktrails to derive your address from the private key:</p>
<pre><code><span class="comment"># Show your wallet info including address</span>
blocktrails show</code></pre>
<p>Copy the testnet4 address that's displayed (starts with <code>tb1...</code> or similar).</p>
<h4>Get free testnet coins from a faucet</h4>
<p>Visit one of these testnet4 faucets and paste your address:</p>
<ul>
<li><a href="https://github.com/testnet4/awesome-testnet4?tab=readme-ov-file#faucets" target="_blank">Testnet4 Faucet List</a> - curated list of working faucets</li>
</ul>
<p>Request a small amount (0.001 tBTC is plenty for many anchors).</p>
<h4>Verify your balance</h4>
<pre><code><span class="comment"># Check that the coins arrived</span>
blocktrails show</code></pre>
<p>Wait a few minutes for the transaction to confirm. You should see a balance.</p>
<div class="callout callout-success">
<p><strong>Wallet funded!</strong></p>
<p>You now have testnet coins ready to anchor backups. Each anchor uses a small amount, so this will last for many backups.</p>
</div>
</div>
</section>
<!-- Quick Win 3 -->
<section id="quick-win-3">
<div class="quick-win">
<h3>Quick Win #3: Bitcoin Timestamping <span class="badge">5 min</span></h3>
<p class="lead">Now let's anchor a backup on Bitcoin testnet.</p>
<h4>Create a Bitcoin-timestamped backup</h4>
<pre><code><span class="comment"># Back up WITH Bitcoin anchoring</span>
borg-anchor backup ~/Documents ~/backups --name my-backup-anchored</code></pre>
<p>The output will show the fingerprint being anchored:</p>
<pre><code> Creating backup: my-backup-anchored
Source: /home/you/Documents
Repo: /home/you/backups/repo
Fingerprint: 7a3b9c...
Anchoring on Bitcoin...
✓ Backup complete!</code></pre>
<h4>Verify it's anchored</h4>
<pre><code>borg-anchor verify my-backup-anchored ~/backups</code></pre>
<div class="callout callout-success">
<p><strong>Your backup is now on Bitcoin!</strong></p>
<p>The fingerprint of your data has been recorded in a Bitcoin transaction. Anyone can verify that this exact data existed at the time of the block.</p>
</div>
</div>
</section>
<!-- Quick Win 4 -->
<section id="quick-win-4">
<div class="quick-win">
<h3>Quick Win #4: Restore Your Data <span class="badge">2 min</span></h3>
<p class="lead">The whole point of backups - getting your data back.</p>
<h4>Restore to a new location</h4>
<pre><code><span class="comment"># Restore your backup to ~/restored/</span>
borg-anchor restore my-backup ~/restored ~/backups</code></pre>
<h4>Check the restored files</h4>
<pre><code>ls ~/restored/
<span class="comment"># Your files are under the original path structure:</span>
ls ~/restored/home/you/Documents/</code></pre>
<div class="callout callout-success">
<p><strong>Data restored!</strong></p>
<p>Borg preserves the full path structure. Your files are exactly as they were when backed up.</p>
</div>
</div>
</section>
<!-- Key Concepts -->
<section id="concepts">
<h2>Key Concepts</h2>
<h3>Repository vs Archive</h3>
<p>
A <strong>repository</strong> is where all your backups are stored (like <code>~/backups/repo</code>).
An <strong>archive</strong> is a single backup within that repository (like <code>my-backup</code>).
</p>
<pre><code>Repository: ~/backups/repo/
├── Archive: my-backup (Jan 1)
├── Archive: second-backup (Jan 2)
└── Archive: weekly-backup (Jan 7)</code></pre>
<h3>Fingerprints</h3>
<p>
Every archive has a unique <strong>fingerprint</strong> - a SHA-256 hash of its contents.
If even one byte changes, the fingerprint is completely different.
This fingerprint is what gets anchored on Bitcoin.
</p>
<h3>The Anchor Chain</h3>
<p>
borg-anchor uses a chained UTXO trail, meaning each backup links to the previous one.
This creates an unbroken chain of proofs you can reconstruct at any time.
</p>
<h3>Networks</h3>
<ul>
<li><strong>tbtc4</strong> (testnet4) - Default. Free to use. Great for testing and non-critical backups.</li>
<li><strong>btc</strong> (mainnet) - Real Bitcoin. Use for important data that needs permanent, trusted timestamps.</li>
</ul>
<pre><code><span class="comment"># Use mainnet for production</span>
borg-anchor init ~/important-backups --network btc</code></pre>
</section>
<!-- Common Commands -->
<section>
<h2>Command Reference</h2>
<pre><code><span class="comment"># Initialize a new backup repository</span>
borg-anchor init ~/backups
borg-anchor init ~/backups --encryption repokey <span class="comment"># with encryption</span>
borg-anchor init ~/backups --network btc <span class="comment"># use mainnet</span>
<span class="comment"># Create backups</span>
borg-anchor backup ~/mydata ~/backups <span class="comment"># auto-named backup-YYYY-MM-DD</span>
borg-anchor backup ~/mydata ~/backups --name daily <span class="comment"># custom name</span>
borg-anchor backup ~/mydata ~/backups --no-anchor <span class="comment"># skip Bitcoin</span>
borg-anchor backup ~/mydata ~/backups --dry <span class="comment"># dry run</span>
<span class="comment"># View backups</span>
borg-anchor info <span class="comment"># dashboard of all projects</span>
borg-anchor list ~/backups <span class="comment"># list all archives</span>
borg-anchor show ~/backups <span class="comment"># show config & trail status</span>
<span class="comment"># Verify & restore</span>
borg-anchor verify my-backup ~/backups <span class="comment"># check if anchored</span>
borg-anchor restore my-backup ~/dest ~/backups <span class="comment"># restore files</span></code></pre>
</section>
<!-- Next Steps -->
<section id="next-steps" class="next-steps">
<h2>Next Steps</h2>
<p>You now know the basics. Here's where to go next:</p>
<div class="links">
<a href="index.html">Full Documentation</a>
<a href="https://borgbackup.readthedocs.io/">BorgBackup Docs</a>
<a href="https://github.com/blocktrails/blocktrails">blocktrails</a>
<a href="https://github.com/solid-live/borg-anchor">GitHub</a>
</div>
</section>
<!-- Troubleshooting -->
<section>
<h2>Troubleshooting</h2>
<h3>borg: command not found</h3>
<p>BorgBackup isn't installed or not in your PATH. Install it with your package manager.</p>
<h3>blocktrails CLI not found</h3>
<p>You need to install blocktrails. See <a href="https://github.com/blocktrails/blocktrails">the repo</a> for instructions.</p>
<h3>No config found</h3>
<p>You're not in a borg-anchor directory. Either <code>cd</code> into your backup folder or run <code>borg-anchor init</code> first.</p>
<h3>Backup not anchored</h3>
<p>Make sure you've set up your private key with <code>git config nostr.privkey</code> and have testnet coins if needed.</p>
</section>
<footer>
<p>AGPL-3.0 © 2026 <a href="https://melvincarvalho.com">Melvin Carvalho</a></p>
<p style="margin-top: 0.5rem;">Part of the <a href="https://solid.live">solid.live</a> ecosystem</p>
</footer>
</div>
</body>
</html>