mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-18 21:16:47 +00:00
Remove storage configuration details from README
Removed detailed storage configuration and provisioning instructions from the README.
This commit is contained in:
Maurice
@@ -490,99 +490,6 @@ Caddy handles TLS and WebSockets automatically.
|
||||
|
||||
</details>
|
||||
|
||||
<br />
|
||||
|
||||
<h2 id="storage">Storage</h2>
|
||||
|
||||
TREK separates *what* it stores (eight content categories — trip documents,
|
||||
journey photos, cover images, profile pictures, place images, the two photo
|
||||
caches, and backups) from *where* it stores it (named backends). Out of the
|
||||
box everything lives on local disk (`uploads/` and `data/backups`). From
|
||||
**Admin → Storage** you can:
|
||||
|
||||
- **Add S3-compatible backends** (AWS S3, Cloudflare R2, Backblaze B2, Garage,
|
||||
MinIO/AIStor) and assign any category to them.
|
||||
- **Replicate a backend**: edit it and pick **Mirror targets** — every write is
|
||||
then also copied to each target. The classic off-site backup setup is:
|
||||
add an S3 backend, edit `backups-local`, tick the S3 backend as a mirror
|
||||
target, save. Replica writes happen one after another during each upload, so
|
||||
a slow or unreachable target slows every upload of every category on that
|
||||
backend — fine for backups, worth weighing for hot categories. Existing
|
||||
objects are not replicated when you add a target — press **Sync now** on
|
||||
the backend to copy them (one sync at a time; progress and cancel in the
|
||||
panel).
|
||||
- **Watch the Health strip**: replica failures never fail the original
|
||||
request; they are recorded and shown there instead. All-clear means every
|
||||
replicated write landed. Failures also notify admins over the configured
|
||||
notification channels (first failure immediately, then hourly summaries) —
|
||||
tune it under Admin → Notifications.
|
||||
- **Test** any backend from its row (for a replicated backend it probes the
|
||||
primary and each target individually). Targets must be saved before Test
|
||||
can probe them.
|
||||
- **Usage**: per-category and per-backend object counts and sizes, scanned
|
||||
nightly and on demand.
|
||||
|
||||
Backend credentials are encrypted at rest. Without an explicit
|
||||
`ENCRYPTION_KEY` the implicit key from the data directory is used — that
|
||||
works, but the implicit key rides inside backups, so setting `ENCRYPTION_KEY`
|
||||
explicitly is recommended for credentialed backends. On an existing install
|
||||
that has been running without an explicit key, do not just set a new one —
|
||||
that would orphan already-stored secrets; use the key-rotation procedure (see
|
||||
*Rotating the Encryption Key* under Updating) to move to an explicit key.
|
||||
|
||||
Notes and limits: reassigning a populated category prompts to move its
|
||||
existing objects — accepting copies everything to the new backend, flips the
|
||||
category, then sweeps any writes that raced the copy; source objects are kept
|
||||
(not deleted) and reported as reclaimable (count + size) to reclaim manually;
|
||||
declining routes only new writes to the new backend, leaving old objects in
|
||||
place as before. Only one storage job (a mirror sync or a category migration)
|
||||
runs at a time, cancelling before the flip is always safe, and a failed copy
|
||||
never flips the category; media categories on S3 work but every served byte
|
||||
proxies through the server — the proxy answers conditional GETs (ETag /
|
||||
Last-Modified) and a single `Range` request, while a multi-range request is
|
||||
answered with the full object; AWS buckets
|
||||
with Object-Lock or checksum-requiring policies
|
||||
reject the server's uploads; self-hosted endpoints (MinIO/Garage) should be
|
||||
addressed by IP or `localhost` unless configured for virtual-hosted buckets.
|
||||
The legacy `/uploads/photos` directory from older TREK versions is still
|
||||
served and included in backups, but it is not a configurable category.
|
||||
Running the storage contract suite against a live MinIO/AIStor is a
|
||||
license-gated procedure — CI runs it automatically for same-repo pull
|
||||
requests (fork PRs skip it, since they have no access to the license
|
||||
secret); to run it yourself locally, see `docker-compose.minio-test.yml`'s
|
||||
header for the manual procedure.
|
||||
|
||||
### Provisioning at first boot (seed file)
|
||||
|
||||
For infrastructure-as-code setups, mount a `storage-config.json` into the
|
||||
data directory — it is imported **once**, on the first boot that has no
|
||||
stored storage configuration, and loudly ignored afterwards:
|
||||
|
||||
```jsonc
|
||||
// storage-config.json — secrets may be plaintext (encrypted on import)
|
||||
// or already-encrypted enc:v1: values.
|
||||
{
|
||||
"backends": [
|
||||
{ "name": "off-site", "type": "s3", "options": {
|
||||
"endpoint": "https://s3.example.com", "bucket": "trek",
|
||||
"accessKeyId": "…", "secretAccessKey": "…" } },
|
||||
{ "name": "backups-mirror", "type": "mirror", "options": {
|
||||
"primary": "backups-local", "replicas": ["off-site"] } }
|
||||
],
|
||||
"categories": { "backups": "backups-mirror" }
|
||||
}
|
||||
```
|
||||
|
||||
(The panel presents this exact setup as **Mirror targets** on `backups-local`.)
|
||||
|
||||
```yaml
|
||||
# docker-compose: add under the trek service's volumes
|
||||
- ./storage-config.json:/app/data/storage-config.json:ro
|
||||
```
|
||||
|
||||
An invalid seed file aborts boot with the exact validation error — an
|
||||
actively-provisioning operator sees the problem instead of a silent default.
|
||||
|
||||
### Recovery and restore
|
||||
|
||||
To reset storage configuration to the built-in defaults (or to re-import a
|
||||
|
||||
Reference in New Issue
Block a user