Prepare for website

[gocheese.git] / gocheese.texi

diff --git a/gocheese.texi b/gocheese.texi
index 26ab1789dd4a75f1daa548d93789738c5b8cd103..626c0e37c1611bcc76dc856d4e2c936dc7dd96da 100644 (file)
--- a/gocheese.texi
+++ b/gocheese.texi
@@ -2,6 +2,10 @@
 @documentencoding UTF-8
 @settitle GoCheese
 
 @documentencoding UTF-8
 @settitle GoCheese
 

+@copying
+Copyright @copyright{} 2019 @email{stargrave@@stargrave.org, Sergey Matveev}
+@end copying
+

 @node Top
 @top
 
 @node Top
 @top
 


@@ -23,15 +27,17 @@ Initially it was created as a fork of
 but nearly all the code was rewritten. It has huge differences:
 
 @itemize
 but nearly all the code was rewritten. It has huge differences:
 
 @itemize

-@item proxying and caching of missing packages, including GPG signatures
+@item Proxying and caching of missing packages, including GPG signatures

 @item @url{https://pythonwheels.com/, Wheel} uploading support
 @item @url{https://pythonwheels.com/, Wheel} uploading support

-@item atomic packages store on filesystem
-@item SHA256-checksummed packages: storing checksums, giving them back,
-    verifying stored files integrity, verifying checksum of uploaded
-    packaged
-@item graceful HTTP-server shutdown
-@item no YAML configuration, just command-line arguments
-@item no package overwriting ability (as PyPI does too)
+@item Integrity check of proxied packages: MD5, SHA256, SHA512, BLAKE2b-256
+@item SHA256 checksums for stored packages
+@item Verifying of SHA256 checksum for uploaded packages
+@item Storing of uploaded GPG signatures
+@item Secure Argon2i (or SHA256) stored passwords hashing
+@item No YAML configuration, just command-line arguments
+@item No package overwriting ability (as PyPI does too)
+@item Graceful HTTP-server shutdown
+@item Atomic packages store on filesystem

 @end itemize
 
 Also it contains @file{pyshop2packages.sh} migration script for
 @end itemize
 
 Also it contains @file{pyshop2packages.sh} migration script for


@@ -42,13 +48,20 @@ GoCheese is free software, licenced under
 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
 see the file COPYING for copying conditions.
 
 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
 see the file COPYING for copying conditions.
 

+Please send questions, bug reports and patches to @url{gocheese@@cypherpunks.ru}.
+
+@insertcopying
+

 @menu
 @menu

+* Download::

 * Usage::
 * Password authentication: Passwords.
 * TLS support: TLS.
 * Storage format: Storage.
 @end menu
 
 * Usage::
 * Password authentication: Passwords.
 * TLS support: TLS.
 * Storage format: Storage.
 @end menu
 

+@include download.texi
+

 @node Usage
 @unnumbered Usage
 
 @node Usage
 @unnumbered Usage
 


@@ -91,7 +104,7 @@ file is checked against it.
 
 Pay attention that you have to manually create corresponding private
 package directory! You are not allowed to upload anything explicitly
 
 Pay attention that you have to manually create corresponding private
 package directory! You are not allowed to upload anything explicitly

-flagged as private.
+flagged as internal package.

 
 @node Passwords
 @unnumbered Password authentication
 
 @node Passwords
 @unnumbered Password authentication


@@ -183,31 +196,41 @@ Root directory has the following hierarchy:
 @verbatim
 root
   +-- public-package
 @verbatim
 root
   +-- public-package

-  |     +- public-package-0.1.tar.gz.sha256
+  |     +- public-package-0.1.tar.gz.md5
+  |     +- public-package-0.1.tar.gz.blake2_256
+  |     +- public-package-0.1.1.tar.gz.blake2_256

   |     +- public-package-0.2.tar.gz
   |     +- public-package-0.2.tar.gz.asc
   |     +- public-package-0.2.tar.gz.sha256
   +-- private-package
   |     +- .internal
   |     +- private-package-0.1.tar.gz
   |     +- public-package-0.2.tar.gz
   |     +- public-package-0.2.tar.gz.asc
   |     +- public-package-0.2.tar.gz.sha256
   +-- private-package
   |     +- .internal
   |     +- private-package-0.1.tar.gz

+  |     +- private-package-0.1.tar.gz.asc

   |     +- private-package-0.1.tar.gz.sha256
   |...
 @end verbatim
 
   |     +- private-package-0.1.tar.gz.sha256
   |...
 @end verbatim
 

-Each directory is a package name. When you try to list non existent
-directory contents (you are downloading package you have not seen
-before), then GoCheese will download information about package's
-versions with checksums and write them in corresponding @file{.sha256}
-files. However no package package tarball is downloaded.
+Each directory is a normalized package name. When you try to list non
+existent directory contents (you are downloading package you have not
+seen before), then GoCheese will download information about package's
+versions with checksums and write them in corresponding
+@file{.sha256}, @file{.blake2_256}, @file{.sha512}, @file{.md5} files.
+However no package package tarball is downloaded.

 
 When you request for particular package version, then its tarball is
 
 When you request for particular package version, then its tarball is

-downloaded and verified against the checksum. For example in the root
-directory above we have downloaded only @file{public-package-0.2}.
-If upstream has corresponding @file{.asc} file, then it also will be
-downloaded.
-
-Private packages contain @file{.internal} file, indicating that it must
-not be asked in PyPI if required version is missing. You have to create
-it manually.
+downloaded and verified against the stored checksum. But SHA256 is
+forced to be stored and used later.
+
+For example @file{public-package} has @code{0.1} version, downloaded a
+long time ago with MD5 checksum. @code{0.1.1} version is downloaded more
+recently with BLAKE2b-256 checksum, also storing that checksum for
+@code{0.1}. @code{0.2} version is downloaded tarball, having forced
+SHA256 recalculated checksum. Also upstream has corresponding
+@file{.asc} signature file.
+
+@file{private-package} is private package, because it contains
+@file{.internal} file. It can be uploaded and queries to it are not
+proxied to upstream PyPI. You have to create it manually. If you upload
+GPG signature, then it will be also stored.

 
 @bye
 
 @bye