daemontools friendliness

[gocheese.git] / gocheese.texi

diff --git a/gocheese.texi b/gocheese.texi
index 626c0e37c1611bcc76dc856d4e2c936dc7dd96da..f4b6f811371e278cf2e003c220c52becfab598fb 100644 (file)
--- a/gocheese.texi
+++ b/gocheese.texi
@@ -3,7 +3,7 @@
 @settitle GoCheese
 
 @copying
 @settitle GoCheese
 
 @copying

-Copyright @copyright{} 2019 @email{stargrave@@stargrave.org, Sergey Matveev}
+Copyright @copyright{} 2019-2020 @email{stargrave@@stargrave.org, Sergey Matveev}

 @end copying
 
 @node Top
 @end copying
 
 @node Top


@@ -22,6 +22,19 @@ It serves two purposes:
     @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API}
 @end itemize
 
     @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API}
 @end itemize
 

+Why could you like it and how it can be better to fit your needs?
+
+@itemize
+@item No database required. Only filesystem storage with few simple
+    files per package. Package deletion, renaming, making it uploadable
+    (private) is done with simple @command{mkdir}, @command{touch}, etc
+    commands
+@item Just single statically compiled Go binary
+@item No configuration file, but several simple command line arguments
+@item Consistency (because of atomic synced operations) and integrity
+    (because of SHA256 checksums stored nearby)
+@end itemize
+

 Initially it was created as a fork of
 @url{https://github.com/c4s4/cheeseshop, cheeseshop},
 but nearly all the code was rewritten. It has huge differences:
 Initially it was created as a fork of
 @url{https://github.com/c4s4/cheeseshop, cheeseshop},
 but nearly all the code was rewritten. It has huge differences:


@@ -40,7 +53,7 @@ but nearly all the code was rewritten. It has huge differences:
 @item Atomic packages store on filesystem
 @end itemize
 
 @item Atomic packages store on filesystem
 @end itemize
 

-Also it contains @file{pyshop2packages.sh} migration script for
+Also it contains @file{contrib/pyshop2packages.sh} migration script for

 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
 GoCheese one, including private packages.
 
 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
 GoCheese one, including private packages.
 


@@ -53,24 +66,24 @@ Please send questions, bug reports and patches to @url{gocheese@@cypherpunks.ru}
 @insertcopying
 
 @menu
 @insertcopying
 
 @menu

-* Download::
+* Install::

 * 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
+@include install.texi

 
 @node Usage
 @unnumbered Usage
 
 To use it for download purposes, just configure your @file{pip.conf}:
 
 
 @node Usage
 @unnumbered Usage
 
 To use it for download purposes, just configure your @file{pip.conf}:
 

-@verbatim
+@example

 [install]
 index-url = http://gocheese.host:8080/simple/
 [install]
 index-url = http://gocheese.host:8080/simple/

-@end verbatim
+@end example

 
 @option{-refresh} URL (@code{/simple/} by default) automatically
 refreshes metainformation (available versions and their checksums)
 
 @option{-refresh} URL (@code{/simple/} by default) automatically
 refreshes metainformation (available versions and their checksums)


@@ -83,21 +96,21 @@ package files.
 
 You can upload packages to it with @url{https://pypi.org/project/twine/, twine}:
 
 
 You can upload packages to it with @url{https://pypi.org/project/twine/, twine}:
 

-@verbatim
+@example

 twine upload
     --repository-url http://gocheese.host:8080/simple/ \
     --username spam \
     --password foo dist/tarball.tar.gz
 twine upload
     --repository-url http://gocheese.host:8080/simple/ \
     --username spam \
     --password foo dist/tarball.tar.gz

-@end verbatim
+@end example

 
 Or you can store it permanently in @file{.pypirc}:
 
 
 Or you can store it permanently in @file{.pypirc}:
 

-@verbatim
+@example

 [pypi]
 repository: https://gocheese.host/simple/
 username: spam
 password: foo
 [pypi]
 repository: https://gocheese.host/simple/
 username: spam
 password: foo

-@end verbatim
+@end example

 
 If @command{twine} sends SHA256 checksum in the request, then uploaded
 file is checked against it.
 
 If @command{twine} sends SHA256 checksum in the request, then uploaded
 file is checked against it.


@@ -106,6 +119,9 @@ Pay attention that you have to manually create corresponding private
 package directory! You are not allowed to upload anything explicitly
 flagged as internal package.
 
 package directory! You are not allowed to upload anything explicitly
 flagged as internal package.
 

+It is advisable to run GoCheese under some kind of
+@url{http://cr.yp.to/daemontools.html, daemontools}.
+

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


@@ -113,9 +129,9 @@ Password authentication is required for packages uploading.
 You have to store your authentication data in @option{-passwd} file in
 following format:
 
 You have to store your authentication data in @option{-passwd} file in
 following format:
 

-@verbatim
+@example

 username:hashed-password
 username:hashed-password

-@end verbatim
+@end example

 
 Empty lines and having @verb{|#|} at the beginning are skipped.
 
 
 Empty lines and having @verb{|#|} at the beginning are skipped.
 


@@ -126,8 +142,8 @@ Supported hashing algorithms are:
 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
     To get Argon2i hashed-password you can use any of following tools:
     @itemize
 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
     To get Argon2i hashed-password you can use any of following tools:
     @itemize

-    @item @url{https://github.com/balakhonova/argon2i,
-        go get github.com/balakhonova/argon2i} (Go)
+    @item go get @url{https://github.com/balakhonova/argon2i,
+        github.com/balakhonova/argon2i} (Go)

     @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
     @end itemize
     Example user @code{foo} with password @code{bar} can have the
     @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
     @end itemize
     Example user @code{foo} with password @code{bar} can have the


@@ -140,13 +156,14 @@ foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9
 @item SHA256
     You can use your operating system tools:
 
 @item SHA256
     You can use your operating system tools:
 

-@verbatim
+@example

 # BSD-based systems:
 $ echo -n "password" | sha256
 
 # GNU/Linux-based systems
 $ echo -n "password" | sha256sum
 # BSD-based systems:
 $ echo -n "password" | sha256
 
 # GNU/Linux-based systems
 $ echo -n "password" | sha256sum

-@end verbatim
+@end example
+

     Example user @code{foo} with password @code{bar} will have the
     following password file entry:
 
     Example user @code{foo} with password @code{bar} will have the
     following password file entry:
 


@@ -158,10 +175,10 @@ foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
 
 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
 
 
 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
 

-@verbatim
+@example

 $ pkill -HUP gocheese
 $ kill -HUP `pidof gocheese`
 $ pkill -HUP gocheese
 $ kill -HUP `pidof gocheese`

-@end verbatim
+@end example

 
 Before refreshing it's recommended to check @option{-passwd} file with
 @option{-passwd-check} option to prevent daemon failure.
 
 Before refreshing it's recommended to check @option{-passwd} file with
 @option{-passwd-check} option to prevent daemon failure.


@@ -175,7 +192,7 @@ negotiation, Keep-Alives, modern ciphersuites and ECC.
 
 For example generate some self-signed certificate using GnuTLS toolset:
 
 
 For example generate some self-signed certificate using GnuTLS toolset:
 

-@verbatim
+@example

 $ certtool --generate-privkey --ecc --outfile prv.pem
 $ cert_template=`mktemp`
 $ echo cn=gocheese.host > $cert_template
 $ certtool --generate-privkey --ecc --outfile prv.pem
 $ cert_template=`mktemp`
 $ echo cn=gocheese.host > $cert_template


@@ -186,7 +203,7 @@ $ certtool \
     --outfile=cert.pem
 $ rm $cert_template
 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
     --outfile=cert.pem
 $ rm $cert_template
 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]

-@end verbatim
+@end example

 
 @node Storage
 @unnumbered Storage format
 
 @node Storage
 @unnumbered Storage format