+\input texinfo
+@documentencoding UTF-8
+@settitle GoCheese
+
+@node Top
+@top
+
+GoCheese is Python private package repository and caching proxy.
+
+It serves two purposes:
+
+@itemize
+@item hosting of private locally uploaded packages (conforming to
+ @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503} (Simple
+ Repository API))
+@item proxying and caching of missing packages from upstream
+ @url{https://pypi.org/, PyPI}
+@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:
+
+@itemize
+@item proxying and caching of missing packages
+@item atomic packages store on filesystem
+@item SHA256-checksummed packages (both uploaded and proxied one)
+@item no TLS support
+@item no YAML configuration, just command-line arguments
+@item no package overwriting ability
+@end itemize
+
+GoCheese is free software, licenced under
+@url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3} conditions:
+see the file COPYING for copying conditions.
+
+@menu
+* Usage::
+* Password authentication: Passwords.
+* Storage format: Storage.
+@end menu
+
+@node Usage
+@unnumbered Usage
+
+To use it for download purposes, just configure your @file{pip.conf}:
+
+@verbatim
+[install]
+index-url = http://gocheese.host:8080/simple/
+@end verbatim
+
+@option{-refresh} URL behaves the same way as @option{-simple} one, but
+is always refreshes package versions from PyPI when listing it. You can
+use it to forcefully update known package versions.
+
+You can upload packages to it with
+@url{https://pypi.org/project/twine/, twine}:
+
+@verbatim
+twine upload
+ --repository-url http://gocheese.host:8080/simple/ \
+ --username spam \
+ --passwd foo dist/tarball.tar.gz
+@end verbatim
+
+@node Passwords
+@unnumbered Password authentication
+
+Password authentication is required for packages uploading.
+You have to store your authentication data in @option{-passwd} file in
+following format:
+
+@verbatim
+username:hashed-password
+@end verbatim
+
+Supported hashing algorithms are:
+
+@table @asis
+
+@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 @url{https://github.com/p-h-c/phc-winner-argon2} (C)
+ @end itemize
+ Example user @code{foo} with password @code{bar} can have the
+ following password file entry:
+
+@verbatim
+foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
+@end verbatim
+
+@item SHA256
+ You can use your operating system tools:
+
+@verbatim
+# BSD-based systems:
+$ echo -n "password" | sha256
+
+# GNU/Linux-based systems
+$ echo -n "password" | sha256sum
+@end verbatim
+ Example user @code{foo} with password @code{bar} will have the
+ following password file entry:
+
+@verbatim
+foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
+@end verbatim
+
+@end table
+
+You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
+
+@verbatim
+$ pkill -HUP gocheese
+$ kill -HUP `pidof gocheese`
+@end verbatim
+
+Before refreshing it's recommended to check @option{-passwd} file with
+@option{-passwd-check} option to prevent daemon failure.
+
+@node Storage
+@unnumbered Storage format
+
+Root directory has the following hierarchy:
+
+@verbatim
+root
+ +-- public-package
+ | +- public-package-0.1.tar.gz.sha256
+ | +- public-package-0.2.tar.gz
+ | +- public-package-0.2.tar.gz.sha256
+ +-- private-package
+ | +- .private
+ | +- private-package-0.1.tar.gz
+ | +- 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.
+
+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}.
+
+Private packages contain @file{.private} file, indicating that it must
+not be asked in PyPI if required version is missing. You have to create
+it manually.
+
+@bye