-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocs.html
More file actions
396 lines (377 loc) · 14.9 KB
/
docs.html
File metadata and controls
396 lines (377 loc) · 14.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
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Docs · BucketDock</title>
<meta
name="description"
content="Connect AWS S3, Cloudflare R2 or any S3-compatible endpoint to BucketDock — and learn the keyboard shortcuts and transfer queue."
/>
<link rel="icon" type="image/svg+xml" href="assets/logo.svg" />
<link
rel="icon"
type="image/png"
sizes="32x32"
href="assets/favicon-32.png"
/>
<link rel="apple-touch-icon" href="assets/icon-512.png" />
<link rel="canonical" href="https://bucketdock.com/docs.html" />
<link rel="stylesheet" href="styles.css" />
</head>
<body>
<header class="nav">
<div class="container nav-inner">
<a class="brand" href="/">
<img
src="assets/logo.svg"
alt="BucketDock logo"
width="28"
height="28"
/>
BucketDock
</a>
<nav class="nav-links">
<a href="index.html#features">Features</a>
<a href="docs.html">Docs</a>
<a href="install.html">Install</a>
<a
href="https://github.com/bucketdock/bucketdock"
target="_blank"
rel="noopener"
>GitHub</a
>
</nav>
<button
class="nav-menu-btn"
id="nav-open"
aria-label="Open menu"
aria-expanded="false"
aria-controls="nav-overlay"
>
<svg
width="18"
height="18"
viewBox="0 0 18 18"
fill="none"
stroke="currentColor"
stroke-width="1.8"
stroke-linecap="round"
>
<line x1="2" y1="5" x2="16" y2="5" />
<line x1="2" y1="9" x2="16" y2="9" />
<line x1="2" y1="13" x2="16" y2="13" />
</svg>
</button>
</div>
</header>
<!-- Mobile full-screen nav overlay -->
<div
id="nav-overlay"
class="nav-overlay"
role="dialog"
aria-modal="true"
aria-label="Site navigation"
>
<button class="nav-overlay-close" id="nav-close" aria-label="Close menu">
×
</button>
<nav class="nav-overlay-links">
<a href="index.html">Home</a>
<a href="docs.html" class="is-current">Docs</a>
<a href="install.html">Install</a>
<a
href="https://github.com/bucketdock/bucketdock"
target="_blank"
rel="noopener"
>GitHub ↗</a
>
</nav>
</div>
<main>
<section>
<div class="container prose">
<h1>Docs</h1>
<p>
BucketDock is a desktop app, so all storage operations run inside
the app itself. There is no service or login. You add a connection,
the app talks to S3 from your Mac, and access keys are stored in the
macOS Keychain.
</p>
<h2 id="install">Install</h2>
<p>
Download the latest <code>.dmg</code> from the
<a href="install.html">download and install page</a>, drag
<code>BucketDock.app</code> into <code>Applications</code>, and
launch it.
</p>
<p>
Current public builds are unsigned developer previews. If macOS says
BucketDock is damaged or blocks the first launch, follow the
Terminal steps on the
<a href="install.html#macos-notice">macOS install guide</a>.
</p>
<h2 id="add-connection">Add a connection</h2>
<p>
Click the <strong>+</strong> button in the sidebar and fill in the
form.
</p>
<h3>AWS S3</h3>
<pre><code>Provider: AWS S3
Region: eu-central-1
Endpoint: (leave empty)
Buckets: (leave empty to auto-list, or list specific names)</code></pre>
<h3>Cloudflare R2</h3>
<pre><code>Provider: Cloudflare R2
Endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
Region: auto
Buckets: your-bucket-name</code></pre>
<p>
Use the <strong>account endpoint</strong>, not a bucket-appended
URL. For bucket-scoped credentials, list the bucket names in the
<code>Buckets</code> field — comma, space, newline or semicolon
separated.
</p>
<h3>S3-compatible (MinIO, Backblaze B2, etc.)</h3>
<pre><code>Provider: Custom (S3-compatible)
Endpoint: https://your-endpoint.example.com
Region: us-east-1
Buckets: optional list</code></pre>
<h2 id="transfers">Transfer queue</h2>
<p>
Every upload, download and bucket-to-bucket copy is tracked in the
dock at the bottom-right of the window. Each row shows live progress
(multipart uploads emit per-part progress) and a status indicator.
You can:
</p>
<ul>
<li><strong>Cancel</strong> a running transfer</li>
<li><strong>Retry</strong> a failed transfer in place</li>
<li>
<strong>Clear finished</strong> entries to keep the dock tidy
</li>
</ul>
<h2 id="browse">Browse, filter and preview</h2>
<ul>
<li>
The top toolbar carries
<strong>back / forward</strong> buttons (or <code>⌘[</code> /
<code>⌘]</code>) plus the current folder name. The full clickable
<strong>path bar</strong> sits at the bottom of the window — click
any segment to jump straight there. The toolbar never wraps onto a
second row: when the window narrows, lower-priority actions
collapse into a <strong>“…” overflow menu</strong> on the right.
</li>
<li>
Folder rows have a small ">"
<strong>disclosure triangle</strong>. Click it to expand the
folder inline and see its contents indented under the row, without
navigating into it. Click again to collapse.
</li>
<li>
The toolbar has an inline <strong>filter</strong> box that narrows
the current listing by case-insensitive substring.
</li>
<li>
Click any column header to <strong>sort</strong> by Name, Type,
Storage Class, Size or Modified. Click again to reverse the
direction.
</li>
<li>
The Type column shows the
<strong>real <code>Content-Type</code></strong> the server
returns. <code>list_objects_v2</code> doesn’t include it, so
BucketDock fires batched <code>HEAD</code> requests in the
background and fills the cells in as they arrive. While the HEADs
are still in flight (or for folders with no real type) you’ll see
the default S3 fallback (
<code>application/octet-stream</code> for files,
<code>—</code> for folders).
</li>
<li>
Selecting a connection without a bucket shows a
<strong>bucket grid</strong> in the right pane.
</li>
<li>
The trailing <code>…</code> button on each row opens the same menu
as a right-click.
</li>
<li>
Double-click a file (or pick <strong>Preview</strong> from the
menu) to open an inline preview for images, audio, video, PDFs and
text files.
</li>
<li>
Pick <strong>Get Info</strong> to inspect headers and user
metadata read-only, or <strong>Edit Headers…</strong> to change
Content-Type, Cache-Control, custom user metadata and more.
</li>
<li>
Renaming a folder or copying a folder between buckets is
implemented as a recursive copy of every object below the prefix,
followed by a delete of the originals on rename.
</li>
<li>
<strong>Renaming</strong> also moves an object inside the same
bucket — type a path with slashes (e.g.
<code>archive/2024/photo.jpg</code>) and the file or folder is
copied to that prefix and the original removed.
</li>
</ul>
<h2 id="menu">macOS application menu</h2>
<p>
BucketDock installs a native menu bar with the standard macOS
arrangement — <strong>File</strong> (New Connection, New Folder,
Upload Files…, Upload Folder…, Refresh, Get Info),
<strong>Edit</strong> (with native Cut / Copy / Paste / Find),
<strong>View</strong>, <strong>Window</strong>, and
<strong>Help</strong> with links to
<a href="https://bucketdock.com">bucketdock.com</a>, this
documentation page,
<a href="https://github.com/bucketdock/bucketdock"
>the GitHub repository</a
>
and
<a href="https://github.com/bucketdock/bucketdock/issues"
>the issue tracker</a
>.
</p>
<h2 id="copy">Copy and move between buckets</h2>
<p>
Right-click one or more files <em>or folders</em> and choose
<strong>Copy to…</strong> or <strong>Move to…</strong>. Pick a
destination connection (it can be a different provider) and a
bucket. The destination is then chosen from a
<strong>folder tree</strong>: click a row’s disclosure triangle to
expand its children inline, click the row body to select it as the
destination. The <strong>New Folder</strong> button creates a
sub-folder under the current selection so you can carve out a fresh
destination without leaving the dialog — the new folder is then
auto-selected so the next click queues the transfer.
</p>
<p>
Each file becomes a tracked transfer that streams through the
desktop and reports progress as it goes. Folders are expanded
recursively and every object below the prefix is queued.
</p>
<p>
<strong>Move</strong> is implemented as copy-then-delete-source, but
each individual source object is removed only after its own copy
completes successfully. Folders are tracked as a group: the source
prefix is wiped only when every file in the subtree copied cleanly.
A partial, cancelled or failed copy leaves the original untouched so
you can safely retry.
</p>
<h2 id="window">Window behaviour on macOS</h2>
<p>
BucketDock follows the standard macOS pattern: clicking the red
traffic-light button <strong>hides</strong> the window so the app
keeps running in the background. Click the BucketDock icon in the
dock to bring the window back. Use <code>⌘Q</code> (or
<strong>BucketDock → Quit</strong>) to actually quit.
</p>
<h2 id="shortcuts">Keyboard shortcuts</h2>
<ul>
<li>
<code>Delete</code> / <code>Backspace</code> — delete the current
selection
</li>
<li><code>Enter</code> on a single folder — open the folder</li>
<li><code>⌘A</code> — select all visible items</li>
<li>
<code>⌘I</code> — open <em>Get Info</em> for the selected file
</li>
</ul>
<h2 id="storage">Where data lives</h2>
<p>Connection metadata is stored at:</p>
<pre><code>~/Library/Application Support/BucketDock/connections.json</code></pre>
<p>
Secret access keys are stored separately in the macOS Keychain under
the service name <code>com.bucketdock.app</code>. As of the latest
build all secrets live in a
<strong>single bundled entry</strong> (account
<code>bucketdock://secrets-v2</code>) so macOS prompts you once per
session instead of once per connection. Legacy per-connection
entries are migrated forward on first launch and removed.
</p>
<h2 id="build-from-source">Build from source</h2>
<pre><code>git clone https://github.com/bucketdock/bucketdock.git
cd bucketdock
pnpm install
pnpm tauri build</code></pre>
<p>
Build artifacts are written under
<code>src-tauri/target/release/bundle/</code>.
</p>
<h2 id="not-yet">Not yet implemented</h2>
<ul>
<li>Object tags</li>
<li>Finder reveal</li>
<li>Bucket policy inspection</li>
</ul>
</div>
</section>
</main>
<footer>
<div class="container footer-inner">
<div class="brand">
<img
src="assets/logo.svg"
alt="BucketDock logo"
width="22"
height="22"
/>
<span>BucketDock</span>
</div>
<div class="footer-links">
<a href="docs.html">Docs</a>
<a href="install.html">Install</a>
<a
href="https://github.com/bucketdock/bucketdock"
target="_blank"
rel="noopener"
>GitHub</a
>
<a
href="https://github.com/bucketdock/bucketdock/blob/main/LICENSE"
target="_blank"
rel="noopener"
>License</a
>
</div>
</div>
<div class="container" style="margin-top: 18px; color: var(--text-faint)">
© <span id="y"></span> BucketDock. Apache License 2.0.
</div>
</footer>
<script>
document.getElementById("y").textContent = new Date().getFullYear();
(function () {
var btn = document.getElementById("nav-open");
var closeBtn = document.getElementById("nav-close");
var overlay = document.getElementById("nav-overlay");
function openMenu() {
overlay.classList.add("is-open");
btn.setAttribute("aria-expanded", "true");
document.body.style.overflow = "hidden";
closeBtn.focus();
}
function closeMenu() {
overlay.classList.remove("is-open");
btn.setAttribute("aria-expanded", "false");
document.body.style.overflow = "";
btn.focus();
}
btn.addEventListener("click", openMenu);
closeBtn.addEventListener("click", closeMenu);
overlay.addEventListener("click", function (e) {
if (e.target === overlay) closeMenu();
});
document.addEventListener("keydown", function (e) {
if (e.key === "Escape" && overlay.classList.contains("is-open"))
closeMenu();
});
})();
</script>
</body>
</html>