Rooba
/
perkeep
mirror of https://github.com/perkeep/perkeep.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Start fleshing out docs. 

Yay planes to help you focus.
This commit is contained in:
Brad Fitzpatrick 2011-01-28 12:05:36 -08:00
parent 01de991ab6
commit ac93867234
16 changed files with 246 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
website/content/cmd/camget Normal file
View File

@ -0,0 +1,10 @@
<h1>camget</h1>
<p>[<a href="/gw/clients/go/camget">code</a>]</p>
<p>A tool to fetch files, blobs and objects from a blob server.</p>
<h2>Usage</h2>
...

9
website/content/cmd/camput Normal file
View File

@ -0,0 +1,9 @@
<h1>camput</h1>
<p>[<a href="/gw/clients/go/camput">code</a>]</p>
<p>A tool to put files, blobs and objects into a blob server.</p>
<h2>Usage</h2>
...

4
website/content/cmd/index.html Normal file
View File

@ -0,0 +1,4 @@
<ul>
<li><a href="camput">camput</a></li>
<li><a href="camget">camget</a></li>
</ul>

2
website/content/contributors
View File

@ -11,3 +11,5 @@
<li><a href="http://nf.id.au/">Andrew Gerrand</a></li>
</ul>
<p>Want to help? See <a href="/docs/contributing">contributing</a>.</p>

3
website/content/docs/arch Normal file
View File

@ -0,0 +1,3 @@
<h1>Architecture</h1>
TODO

12
website/content/docs/contributing Normal file
View File

@ -0,0 +1,12 @@
<h1>Contributing</h1>
<p>Want to contribute to the project? Awesome!</h1>
<ul>
<li>Join the <a href="http://groups.google.com/group/camlistore/">mailing list</a>. Say hi.</li>
<li>Pick an area to tackle. Discuss it first, especially if it's large and/or not well designed yet.</li>
<li>Put your changes online somewhere for review &amp; git pulling.</li>
<li>Once you contribute good changes for awhile we'll get you direct commit access.</li>
</ul>

27
website/content/docs/index.html
View File

@ -1,6 +1,27 @@
<h1>Docs</h1>
<h1>Documentation</h1>
<p>Most documentation is currently in the git <a href="/code/?p=camlistore.git;a=tree;f=doc;hb=master">docs/ directory</a>.</p>
<p>Most documentation is currently in the
project's <a href="/gw/doc">doc/ directory</a> or in the source
itself. Some is now being promoted to HTML, though:</p>
<h2>Misc</h2>
<ul>
<li><a href="/docs/arch">Architecture</a>: the pieces, layers, and how they interact</li>
<li><a href="/docs/terms">Terminology</a>: let's agree on terms to stay sane</li>
<li><a href="/docs/schema">Schema</a>: how we model data in Camlistore</li>
<li><a href="/docs/uses">Use Cases</a>: what one might do with all this (or at least our aspirations)</li>
<li><a href="/docs/prior-art">Prior Art</a>: other projects doing similar stuff</li>
<li><a href="/docs/status">Project Status</a>: where we're at</li>
<li><a href="/docs/contributing">Contributing</a>: how to help</li>
</ul>
<h2>Commands</h2>
<ul>
<li><a href="/cmd/camput">camput</a>: add <a href="/docs/schema">files &amp; other blobs & objects</a> to one of your camli blob servers</a></li>
<li><a href="/cmd/camget">camget</a>: (less mature) fetch things from a blob server</li>
</ul>
<p>TODO: put more docs here</p>

15
website/content/docs/json-signing Normal file
View File

@ -0,0 +1,15 @@
<h1>JSON Signing</h1>
<p>Some Camlistore JSON blobs are signed.</p>
<h2>Background & spec</h2>
<p>See <a href="/gw/doc/json-signing/json-signing.txt">doc/json-signing/json-signing.txt</a> in the git repo.</p>
<h2>Libraries</h2>
<ul>
<li><a href="/code/?p=camlistore.git;a=tree;f=lib/go/jsonsign;hb=HEAD">Go</a></li>
</ul>
</ul>

12
website/content/docs/prior-art Normal file
View File

@ -0,0 +1,12 @@
<h1>Prior Art</h1>
<p>Other inspirational projects:</p>
<ul>
<li><b>Git</b></li>
<li><b>Venti / Fossil</b></li>
</ul>
<p>TODO: flesh out this page</p>

20
website/content/docs/schema Normal file
View File

@ -0,0 +1,20 @@
<h1>Schema</h1>
<p>At the lowest layer Camlistore doesn't care what you put in it
(everything is just dumb bytes) and you're free to adopt your own data
model. However, the upper layers of Camlistore standardize on a <a href="/gw/doc/schema">common
schema</a> to represent various classes of data.</p>
<p>Here are some of the models we've started to formalize a <a href="http://json.org/">JSON</a> schema for:</p>
<ul>
<li><a href="/gw/doc/schema/files">Files</a>: traditional filesystems. Files, directories, inodes, symlinks, etc.</li>
<li><a href="/gw/doc/schema/objects/permanode.txt">Permanodes</a>: the immutable root "anchor" of mutable Camli objects (see <a href="terms">terminology</a>). Must be <a href="/doc/json-signing">signed</a>.</li>
<li><a href="/docs/json-signing">Signing</a></li>
<li><a href="/gw/doc/schema/objects/keep.txt">Keep claims</a></li>
</ul>

3
website/content/docs/sharing Normal file
View File

@ -0,0 +1,3 @@
<h1>Sharing</h1>
....

47
website/content/docs/status Normal file
View File

@ -0,0 +1,47 @@
<h1>Status</h1>
<p>Camlistore has <a href="/docs/arch">many pieces</a> and many <a
href="/docs/uses">potential use cases</a>. Here are some of the
pieces and use cases, and where they're at.</p>
<h2>Specification</h2>
<table class='status'>
<tr><th>Item</th><th>Status</th><th>Notes</th></tr>
<tr><td>Blob Server</td><td>95%</td><td>See <a href="/gw/doc/protocol">doc/protocol/</a></td></tr>
<tr><td>Sharing</td><td>50%</td><td>See mailing list thread "Example of sharing"</td></tr>
</table>
<h2>Servers</h2>
<table class='status'>
<tr><th>Item</th><th>Status</th><th>Notes</th></tr>
<tr><td>Blob Server (Local, Go)</td><td>95%</td><td>See <a href="/gw/server/go/blobserver">server/go/blobserver</a></td></tr>
<tr><td>Blob Server (Hosted, App Engine)</td><td>95%</td><td>See <a href="/gw/server/appengine/blobserver">server/appengine/blobserver</td></tr>
<tr><td>Blob Server test suite</td><td>80%</td><td>See <a href="/gw/server/tester/bs-test.pl">server/tester/bs-test.pl</a></td></tr>
<tr><td>Search / indexer server</td><td>5%</td><td>Toy prototype started. See <a href="/gw/indexing/basic">indexing/basic</a>. Upcoming area of focus.</td></tr>
<tr><td>JSON signing / verification server (Go)</td><td>80%</td><td>See <a href="/gw/server/go/sigserver">server/go/sigserver</a>. Does JSON signing and verification, but doesn't yet permit uploading keys. This isn't a formal part of Camlistore but is rather a temporary bootstrapping component, a crutch for JavaScript.</td></tr>
<tr><td>JSON signing / verification server (App Engine)</td><td>70%</td><td>See <a href="/gw/server/appengine/sigserver">server/appengine/sigserver</a>. Does JSON signing and verification, but doesn't yet permit uploading keys. This isn't a formal part of Camlistore but is rather a temporary bootstrapping component, a crutch for JavaScript.</td></tr>
</table>
<h2>Tools</h2>
<table class='status'>
<tr><th>Item</th><th>Status</th><th>Notes</th></tr>
<tr><td><a href="/cmd/camput">camput</a></td><td>50%</td><td>the kitchen sink tool to inject content into a blobserver.</td></tr>
<tr><td><a href="/cmd/camget">camget</a></td><td>10%</td><td>tool to retrieve content from a blobserver.</td></tr>
</table>
<h2>High-Level Use Cases</h2>
<p>... TODO: table for the various <a href="/docs/uses">use cases</a>.</p>

33
website/content/docs/terms Normal file
View File

@ -0,0 +1,33 @@
<h1>Terminology</h1>
<p>To stay sane and communicate effectively we try hard to use
consistent terminology throughout the pieces of the project. Please let us know
if things here are confusing or lacking.</p>
<dl class='terms'>
<dt>blob</dt>
<dd>an immutable sequence of 0 or more bytes, with no extra metadata</dd>
<dt>blobref</dt>
<dd>a reference to a blob, consisting of a cryptographic hash
function name and that hash function's digest of the blob's bytes,
in hex. Examples of valid blobrefs include:
<pre>
sha1-f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
md5-d3b07384d113edec49eaa6238ad5ff00
sha256-b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c</pre>
Concatenating the two together with a hyphen is the common
representation, with both parts in all lower case.
</dd>
<dt>blob server</dt>
<dd>the simplest and lowest layer of the Camlistore servers. A blob server,
while potentially shared between users, is <em>logically private to a single user</em>
and holds that user's blobs (<a href="/docs/schema">whatever they may represent</a>).
</dl>

22
website/content/docs/uses Normal file
View File

@ -0,0 +1,22 @@
<h1>Use Cases</h1>
<p>Camlistore is currently more of a vision than a product, but let us
at least lay out some of that vision here.</p>
<p>What could one potentially do with all this?</p>
<ul class='lispaced'>
<li><b>Filesystem backups</b>: easy initial use case. Since you can easily put <a href="/docs/schema">files & directories and such</a> in camlistore with <a href="/cmd/camput">camput</a>, you can use Camlistore for your backups. Incremental backups are basically free.</lil>
<li><b>Efficient remote filesystem</b>: should be easy to do an aggressively caching remote FUSE filesystem. Read-only is trivial. Read-write shouldn't be too painful.</li>
<li><b>Decentralized sharing system</b>: share anything of yours with anybody or everybody (private is the default). This is already starting to work. See <a href="/docs/sharing">sharing</a>.</li>
<li><b>Blog / photo hosting / Document Management CMS:</b> I intend to run my personal blog and photo / gallery hosting (with permissions) off of Camlistore. I also intend to replace my "scanningcabinet" document management software and use Camlistore instead.</li>
<li><b>Decentralized social networking</b>: a lofty but persistent goal</li>
<li><b>Import/export adapters for hosted web services:</b> Don't worry about web services shutting down or going downhill. Mirror all your data online in your private store. Create it either in Camlistore (using open tools) and export to hosted services, or create content in hosted services and continually mirror it back into your private Camlistore. Relax knowing that your data is yours, forever.</li>
</ul>

10
website/content/index.html
View File

@ -1,9 +1,9 @@
<h1>What is Camlistore?</h1>
<h1 class='bustTitleRegexp'>What is Camlistore?</h1>
<p>Camlistore is:</p>
<ul>
<li>a way to store, sync, share, model and back up content</li>
<li>a work in progress</li>
<li>a <a href="/docs/status">work in progress</a></li>
<li>Open Source (Apache licensed)</li>
<li>an acronym for <i>"Content-Addressable Multi-Layer Indexed Storage"</i>, hinting that Camlistore is about:
<ul>
@ -13,11 +13,11 @@
</ul></li>
<li>your "home directory for the web"</li>
<li>pro-JSON (yet aggressively format agnostic)</li>
<li>pro-GnuPG (for signing claims)</li>
<li>pro-GnuPG (for <a href="/docs/json-signing">signing claims</a>)</li>
<li>pro-paranoia and privacy</li>
<li>ambitious, but ...</li>
<li><a href="/docs/uses">ambitious</a>, but ...</li>
<li>simple!</li>
<li>programning language-agnostic (parts and different implementations in <a href="http://golang.org/">Go</a>, Python, Java, Perl, Bash, ... the language doesn't matter.)</li>
<li>programning language-agnostic (parts and different implementations in <a href="http://golang.org/">Go</a>, Python, Java, Perl, Bash, ... the language doesn't matter.) What matters is well-defined, simple HTTP interfaces.</li>
<li>neither "Cloud" nor "Local". happily both.</li>
<li>a "20% project" from a few Google employees, but not Google-centric nor endorsed by Google (other than them letting us open source our side project)</li>
<li>not yet ready for users</li>

25
website/static/all.css
View File

@ -53,3 +53,28 @@ div.content {
text-align: center;
font-size: 75%;
}
table.status {
border: 2px solid black;
width: 100%;
}
table.status td {
border: 1px solid #999;
padding: 0.4em;
}
table.status th {
border: 1px solid black;
padding: 0.4em;
}
dl.terms dt {
margin-top: 0.5em;
font-weight: bold;
font-style: italic;
}
ul.lispaced li {
margin-top: 0.8em;
}