X-Git-Url: http://www.git.cypherpunks.ru/?p=gocheese.git;a=blobdiff_plain;f=gocheese.texi;h=8bb6b9cdbbcd7a95a8041d45662ca053317460df;hp=8ad7b69db949fd0919d28e95cc2b8941c1fb5507;hb=b036ee436eb9bd8889734232a22d3f24be5c9ee2;hpb=c576240f769376cce57823e24158ab4bdaae324c diff --git a/gocheese.texi b/gocheese.texi index 8ad7b69..8bb6b9c 100644 --- a/gocheese.texi +++ b/gocheese.texi @@ -10,11 +10,12 @@ 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} + @url{https://pypi.org/, PyPI}, conforming to + @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503} + (Simple Repository API) +@item hosting of private locally uploaded packages, conforming to + @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API} @end itemize Initially it was created as a fork of @@ -22,21 +23,30 @@ Initially it was created as a fork of 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 proxying and caching of missing packages, including GPG signatures +@item @url{https://pythonwheels.com/, Wheel} uploading support +@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 no YAML configuration, just command-line arguments -@item no package overwriting ability +@item no package overwriting ability (as PyPI does too) +@item atomic packages store on filesystem +@item graceful HTTP-server shutdown @end itemize +Also it contains @file{pyshop2packages.sh} migration script for +converting @url{https://pypi.org/project/pyshop/, Pyshop} database into +GoCheese one, including private packages. + GoCheese is free software, licenced under -@url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3} conditions: +@url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}: see the file COPYING for copying conditions. @menu * Usage:: * Password authentication: Passwords. +* TLS support: TLS. * Storage format: Storage. @end menu @@ -50,20 +60,40 @@ To use it for download purposes, just configure your @file{pip.conf}: 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. +@option{-refresh} URL (@code{/simple/} by default) automatically +refreshes metainformation (available versions and their checksums) +from the upstream, when queried for package directory listing. +@option{-norefresh} prevents upstream queries. -You can upload packages to it with -@url{https://pypi.org/project/twine/, twine}: +@option{-gpgupdate} is useful mainly for migrated for Pyshop migrated +repositories. It forces GPG signature files downloading for all existing +package files. + +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 + --password foo dist/tarball.tar.gz @end verbatim +Or you can store it permanently in @file{.pypirc}: + +@verbatim +[pypi] +repository: https://gocheese.host/simple/ +username: spam +password: foo +@end verbatim + +If @command{twine} sends SHA256 checksum in the request, then uploaded +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 +flagged as internal package. + @node Passwords @unnumbered Password authentication @@ -75,6 +105,8 @@ following format: username:hashed-password @end verbatim +Empty lines and having @verb{|#|} at the beginning are skipped. + Supported hashing algorithms are: @table @asis @@ -122,6 +154,28 @@ $ kill -HUP `pidof gocheese` Before refreshing it's recommended to check @option{-passwd} file with @option{-passwd-check} option to prevent daemon failure. +@node TLS +@unnumbered TLS support + +You can enable TLS support by specifying PEM-encoded X.509 certificate +and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2 +negotiation, Keep-Alives, modern ciphersuites and ECC. + +For example generate some self-signed certificate using GnuTLS toolset: + +@verbatim +$ certtool --generate-privkey --ecc --outfile prv.pem +$ cert_template=`mktemp` +$ echo cn=gocheese.host > $cert_template +$ certtool \ + --generate-self-signed \ + --load-privkey=prv.pem \ + --template $cert_template \ + --outfile=cert.pem +$ rm $cert_template +$ gocheese -tls-cert cert.pem -tls-key prv.pem [...] +@end verbatim + @node Storage @unnumbered Storage format @@ -130,28 +184,41 @@ Root directory has the following hierarchy: @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 - | +- .private + | +- .internal | +- private-package-0.1.tar.gz + | +- private-package-0.1.tar.gz.asc | +- 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 -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. +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