From c576240f769376cce57823e24158ab4bdaae324c Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Tue, 3 Dec 2019 17:45:47 +0300 Subject: [PATCH] Make Texinfo/Info documentation --- .gitignore | 2 + INSTALL | 25 +++----- Makefile | 8 +++ README | 97 +------------------------------ gocheese.texi | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 177 insertions(+), 112 deletions(-) create mode 100644 .gitignore create mode 100644 gocheese.texi diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..592ed2d --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +gocheese +gocheese.info diff --git a/INSTALL b/INSTALL index 51d1ff2..74eeccf 100644 --- a/INSTALL +++ b/INSTALL @@ -1,22 +1,15 @@ -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: diff --git a/Makefile b/Makefile index 3e93e1a..aa71341 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,13 @@ +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 diff --git a/README b/README index 494f25e..bd87b59 100644 --- a/README +++ b/README @@ -1,97 +1,2 @@ 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. diff --git a/gocheese.texi b/gocheese.texi new file mode 100644 index 0000000..8ad7b69 --- /dev/null +++ b/gocheese.texi @@ -0,0 +1,157 @@ +\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 -- 2.44.0