--- /dev/null
+gocheese
+gocheese.info
-There are several installation possibilities:
-
-* using go get (although there is no explicit authentication against my
- public PGP key!):
-
- $ go get go.cypherpunks.ru/gocheese
-
- will install gocheese executable in GOPATH/bin/gocheese.
+ # or use https://git.cypherpunks.ru/git/gocheese.git
+ $ git clone --depth 1 --branch v2.0.0 git://git.cypherpunks.ru/gocheese.git
+ $ cd gocheese
+ $ git tag --verify v2.0.0
+ $ make
-* using manual build:
+gocheese binary and gocheese.info documentation should be built.
+Although you can also use:
- $ git clone https://git.cypherpunks.ru/git/gocheese.git
- or
- $ git clone git://git.cypherpunks.ru/gocheese.git
- $ cd gocheese
- $ git tag -v v1.0.0
- $ go build
+ go get go.cypherpunks.ru/gocheese
- will place gocheese executable in ./gocheese.
+but neither PGP-based authentication is performed, nor documentation build.
For the very first time it is necessary to get signing public key and
import it for verifying git's tag. Its fingerprint is:
+GO ?= go
+MAKEINFO ?= makeinfo
+
VERSION != cat VERSION
LDFLAGS = -X main.Version=$(VERSION)
+all: gocheese gocheese.info
+
gocheese: gocheese.go
GOPATH=$(GOPATH) go build -ldflags "$(LDFLAGS)"
+
+gocheese.info: gocheese.texi
+ $(MAKEINFO) -o $@ gocheese.texi
GoCheese is Python private package repository and caching proxy.
-
-It serves two purposes:
-
-* hosting of private locally uploaded packages
- (conforming to PEP-0503 (Simple Repository API))
-* proxying and caching of missing packages from upstream PyPI
-
-To use it, just configure your pip.conf:
-
- [install]
- index-url = http://gocheese.host:8080/simple/
-
-You can upload packages to it with twine:
-
- twine upload
- --repository-url http://gocheese.host:8080/simple/ \
- --username spam \
- --passwd foo dist/tarball.tar.gz
-
--refresh URL behaves the same way as -simple one, but is always
-refreshes package versions from PyPI when listing it. You can use it to
-forcefully update package version.
-
-Initially it was created as a fork of https://github.com/c4s4/cheeseshop,
-but nearly all the code was rewritten. It has huge differences:
-
-* no TLS support
-* no YAML configuration, just command-line arguments
-* no package overwriting ability
-* atomic packages store on filesystem
-* proxying and caching of missing packages
-* SHA256-checksummed packages (both uploaded and proxied one)
-
-GoCheese is free software: see the file COPYING for copying conditions.
-
- Password authentication
- =======================
-
-You have to store your authentication data in a file (specified
-with -passwd option) with following format:
-
- username:hashed-password
-
-Supported hashing algorithms are SHA256 and Argon2i.
-It's recommended to use Argon2i.
-
-To get Argon2i hashed-password you can use any of following tools:
-
- https://github.com/balakhonova/argon2i (Go)
- https://github.com/p-h-c/phc-winner-argon2 (C)
-
-To get SHA256 hashed-password you can use your operating system tools:
-
- # BSD-based systems:
- $ echo -n 'password' | sha256
- # GNU/Linux-based systems
- $ echo -n 'password' | sha256sum
-
-For example user "foo" with password "bar" can have the following
-hashed passwords:
-
- foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
- foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
-
-While daemon working you can refresh -passwd file with SIGHUP:
-
- $ kill -HUP `pidof gocheese`
-
-Before refreshing it's recommended to check -passwd file with -passwd-check
-option to prevent daemon failure.
-
- On-disk storage format
- ======================
-
-Root directory has the following hierarchy:
-
- 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
- |...
-
-Each directory is a package name. When you trie to list unexistent
-directory contents (you are downloading package you have not seen
-before), then GoCheese will download all its package versions with
-checksums and write then in .sha256 files. So you know what versions are
-available at the moment. When you asks for particular package, then its
-tarball is really downloaded and verified against the checksum. For
-example in the root directory above we have downloaded only
-public-package-0.2. Private packages contain .private file, indicating
-that it must not be asked in PyPI if required version is missing.
+See gocheese.{info,texi} and INSTALL for more documentation.
--- /dev/null
+\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