Skip to content

feat: initial documentation for Logos Storage#166

Open
gmega wants to merge 9 commits into
mainfrom
feat/libstorage-tutorial
Open

feat: initial documentation for Logos Storage#166
gmega wants to merge 9 commits into
mainfrom
feat/libstorage-tutorial

Conversation

@gmega
Copy link
Copy Markdown
Member

@gmega gmega commented Feb 3, 2026

This PR adds:

  1. a welcome page for Logos Storage;
  2. a libstorage-based tutorial which covers some flavour of the the v0.1 testnet use cases.

This will be complemented by the Logos Storage UI app and its documentation.


Doc Packet info:

A. Outcome + value (required)

Outcome (end goal): They'll have an idea of what's possible to do with Logos Storage; i.e., publish and share files. They'll also have an overview of what libstorage enables, and of its flows (albeit in a simplified manner).
Why it matters: the journey summarises the main use cases for Logos Storage in v0.1: create / download / delete / retrieve files using Logos Storage.

B. Scope + ownership

Journey name: Use the Logos Storage module API (create / download / delete / retrieve) to manage files on a local storage-enabled node (though this is not the Logos Storage module API yet, it's libstorage).
Owner (GitHub + Discord): @gmega
Applies to: https://github.com/logos-storage/easylibstorage, commit 36b0242.
Runtime target: local (could be easily modified to run on the Logos testnet v0.1).

C. Runnable happy path

The tutorial describes all of this.

D. Configuration

Again, all described in the tutorial.

E. Hardware requirements (required for node/client journeys)

Should work on any x86_64 or arm64 computer. Needs minimal RAM (e.g. 4GB), minimal disk space (e.g. 100 MB).

F. Verify + troubleshoot

Included in the tutorial.

G. Limits for v0.1

None to report (for now).

H. References

None yet, will probably put together architecture docs over time but those are not there yet.

Optional (only if you can)

  • Takes 10-30 mins to complete (depending on expertise).
  • Nothing noteworthy in terms of security/safety.

Comment thread docs/storage/libstorage-tutorial.md Outdated
@@ -0,0 +1,238 @@
# Getting Started with libstorage

In this tutorial, we will build a simple [libstorage-based](https://github.com/logos-storage/logos-storage-nim) C application which allows sharing files over the Logos Storage network. Since libstorage is a low-level API and its main use case are library and not application developers, however, we will use a higher-level C wrapper developed for this tutorial which we refer to as [easylibstorage](https://github.com/logos-storage/easylibstorage).
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In this tutorial, we will build a simple [libstorage-based](https://github.com/logos-storage/logos-storage-nim) C application which allows sharing files over the Logos Storage network. Since libstorage is a low-level API and its main use case are library and not application developers, however, we will use a higher-level C wrapper developed for this tutorial which we refer to as [easylibstorage](https://github.com/logos-storage/easylibstorage).
In this tutorial, we will build a simple [libstorage-based](https://github.com/logos-storage/logos-storage-nim) C application which allows sharing files over the Logos Storage network. Since libstorage is a low-level API, its main use case is to be used as a library and wrapped into a higher-level abstraction. As such, we will use a higher-level C wrapper developed for this tutorial called [easylibstorage](https://github.com/logos-storage/easylibstorage).

Comment thread docs/storage/README.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
Comment thread docs/storage/libstorage-tutorial.md Outdated
kashepavadan and others added 3 commits May 11, 2026 09:30
README

Co-authored-by: Sasha <118575614+weboko@users.noreply.github.com>
@weboko
Copy link
Copy Markdown
Contributor

weboko commented May 19, 2026

@kashepavadan should I give it another review?

@kashepavadan
Copy link
Copy Markdown
Contributor

@kashepavadan should I give it another review?

Yes please

@@ -0,0 +1,210 @@
---
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this file is called libstorage-tutorial.md which is not correct anymore

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, fixed

Comment thread docs/storage/libstorage-tutorial.md Outdated
authors:
owner: logos
doc_version: 1
slug: libstorage-tutorial
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: this too seems better to rename

@fryorcraken
Copy link
Copy Markdown
Contributor

Cross-checked the tutorial against logos-storage-ui (the internal app exercising the same module). Each bullet is a one-line divergence — happy to expand any of them.

Divergences

  • Skeleton repo is in a different org. Doc points to logos-storage/logos-storage-app-skeleton; the storage UI we build internally uses mkLogosQmlModule from logos-co/logos-module-builder (same as delivery-demo and chat-ui).
  • Title says "Build a CLI app" but content is the C++/Qt module API, not libstorage and not a CLI.
  • Streaming uploads (uploadInit/uploadChunk/uploadFinalize) are documented but not used internally — the UI only calls uploadUrl() (StorageBackend.cpp:325).
  • ~10 module APIs the UI relies on are absent from the doc: exists, remove, fetch, downloadManifest, manifests, space, debug, version, peerId, spr, dataDir (StorageBackend.cpp:285,366,379,395,408,448,461,474,487,514,527).
  • NAT traversal / UPnP / port-forwarding / onboarding is unmentioned — it's ~60% of the storage UI's user-visible surface.
  • Threading caveat is undocumented: the UI README warns "do not call storage module functions from within a callback"; production devs will hit this.
  • API version pin (v0.3.2) is older than logos-storage-module HEAD — worth re-anchoring or dropping the version.
  • Doubled paren in markdown link (Step 2 API Reference): [API Reference]((https://...)).

Naming inflation (cross-cutting, but most visible here)

The PR uses Logos Storage / Logos Storage Module / libstorage / logos-storage-nim / easylibstorage in close proximity. The UI consistently uses storage_module, StorageBackend, StorageUIPlugin. The doc would benefit from one early paragraph nailing down which name maps to which artifact (and what libstorage vs. the C++ module API actually buys you).

cc @gmega

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants