gocheese.texi

   1 \input texinfo
   2 @documentencoding UTF-8
   3 @settitle GoCheese
   4
   5 @copying
   6 Copyright @copyright{} 2019 @email{stargrave@@stargrave.org, Sergey Matveev}
   7 @end copying
   8
   9 @node Top
  10 @top
  11
  12 GoCheese is Python private package repository and caching proxy.
  13
  14 It serves two purposes:
  15
  16 @itemize
  17 @item proxying and caching of missing packages from upstream
  18     @url{https://pypi.org/, PyPI}, conforming to
  19     @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503}
  20     (Simple Repository API)
  21 @item hosting of private locally uploaded packages, conforming to
  22     @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API}
  23 @end itemize
  24
  25 Initially it was created as a fork of
  26 @url{https://github.com/c4s4/cheeseshop, cheeseshop},
  27 but nearly all the code was rewritten. It has huge differences:
  28
  29 @itemize
  30 @item Proxying and caching of missing packages, including GPG signatures
  31 @item @url{https://pythonwheels.com/, Wheel} uploading support
  32 @item Integrity check of proxied packages: MD5, SHA256, SHA512, BLAKE2b-256
  33 @item SHA256 checksums for stored packages
  34 @item Verifying of SHA256 checksum for uploaded packages
  35 @item Storing of uploaded GPG signatures
  36 @item Secure Argon2i (or SHA256) stored passwords hashing
  37 @item No YAML configuration, just command-line arguments
  38 @item No package overwriting ability (as PyPI does too)
  39 @item Graceful HTTP-server shutdown
  40 @item Atomic packages store on filesystem
  41 @end itemize
  42
  43 Also it contains @file{pyshop2packages.sh} migration script for
  44 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
  45 GoCheese one, including private packages.
  46
  47 GoCheese is free software, licenced under
  48 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
  49 see the file COPYING for copying conditions.
  50
  51 Please send questions, bug reports and patches to @url{gocheese@@cypherpunks.ru}.
  52
  53 @insertcopying
  54
  55 @menu
  56 * Download::
  57 * Usage::
  58 * Password authentication: Passwords.
  59 * TLS support: TLS.
  60 * Storage format: Storage.
  61 @end menu
  62
  63 @include download.texi
  64
  65 @node Usage
  66 @unnumbered Usage
  67
  68 To use it for download purposes, just configure your @file{pip.conf}:
  69
  70 @verbatim
  71 [install]
  72 index-url = http://gocheese.host:8080/simple/
  73 @end verbatim
  74
  75 @option{-refresh} URL (@code{/simple/} by default) automatically
  76 refreshes metainformation (available versions and their checksums)
  77 from the upstream, when queried for package directory listing.
  78 @option{-norefresh} prevents upstream queries.
  79
  80 @option{-gpgupdate} is useful mainly for migrated for Pyshop migrated
  81 repositories. It forces GPG signature files downloading for all existing
  82 package files.
  83
  84 You can upload packages to it with @url{https://pypi.org/project/twine/, twine}:
  85
  86 @verbatim
  87 twine upload
  88     --repository-url http://gocheese.host:8080/simple/ \
  89     --username spam \
  90     --password foo dist/tarball.tar.gz
  91 @end verbatim
  92
  93 Or you can store it permanently in @file{.pypirc}:
  94
  95 @verbatim
  96 [pypi]
  97 repository: https://gocheese.host/simple/
  98 username: spam
  99 password: foo
 100 @end verbatim
 101
 102 If @command{twine} sends SHA256 checksum in the request, then uploaded
 103 file is checked against it.
 104
 105 Pay attention that you have to manually create corresponding private
 106 package directory! You are not allowed to upload anything explicitly
 107 flagged as internal package.
 108
 109 @node Passwords
 110 @unnumbered Password authentication
 111
 112 Password authentication is required for packages uploading.
 113 You have to store your authentication data in @option{-passwd} file in
 114 following format:
 115
 116 @verbatim
 117 username:hashed-password
 118 @end verbatim
 119
 120 Empty lines and having @verb{|#|} at the beginning are skipped.
 121
 122 Supported hashing algorithms are:
 123
 124 @table @asis
 125
 126 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
 127     To get Argon2i hashed-password you can use any of following tools:
 128     @itemize
 129     @item @url{https://github.com/balakhonova/argon2i,
 130         go get github.com/balakhonova/argon2i} (Go)
 131     @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
 132     @end itemize
 133     Example user @code{foo} with password @code{bar} can have the
 134     following password file entry:
 135
 136 @verbatim
 137 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
 138 @end verbatim
 139
 140 @item SHA256
 141     You can use your operating system tools:
 142
 143 @verbatim
 144 # BSD-based systems:
 145 $ echo -n "password" | sha256
 146
 147 # GNU/Linux-based systems
 148 $ echo -n "password" | sha256sum
 149 @end verbatim
 150     Example user @code{foo} with password @code{bar} will have the
 151     following password file entry:
 152
 153 @verbatim
 154 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
 155 @end verbatim
 156
 157 @end table
 158
 159 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
 160
 161 @verbatim
 162 $ pkill -HUP gocheese
 163 $ kill -HUP `pidof gocheese`
 164 @end verbatim
 165
 166 Before refreshing it's recommended to check @option{-passwd} file with
 167 @option{-passwd-check} option to prevent daemon failure.
 168
 169 @node TLS
 170 @unnumbered TLS support
 171
 172 You can enable TLS support by specifying PEM-encoded X.509 certificate
 173 and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2
 174 negotiation, Keep-Alives, modern ciphersuites and ECC.
 175
 176 For example generate some self-signed certificate using GnuTLS toolset:
 177
 178 @verbatim
 179 $ certtool --generate-privkey --ecc --outfile prv.pem
 180 $ cert_template=`mktemp`
 181 $ echo cn=gocheese.host > $cert_template
 182 $ certtool \
 183     --generate-self-signed \
 184     --load-privkey=prv.pem \
 185     --template $cert_template \
 186     --outfile=cert.pem
 187 $ rm $cert_template
 188 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
 189 @end verbatim
 190
 191 @node Storage
 192 @unnumbered Storage format
 193
 194 Root directory has the following hierarchy:
 195
 196 @verbatim
 197 root
 198   +-- public-package
 199   |     +- public-package-0.1.tar.gz.md5
 200   |     +- public-package-0.1.tar.gz.blake2_256
 201   |     +- public-package-0.1.1.tar.gz.blake2_256
 202   |     +- public-package-0.2.tar.gz
 203   |     +- public-package-0.2.tar.gz.asc
 204   |     +- public-package-0.2.tar.gz.sha256
 205   +-- private-package
 206   |     +- .internal
 207   |     +- private-package-0.1.tar.gz
 208   |     +- private-package-0.1.tar.gz.asc
 209   |     +- private-package-0.1.tar.gz.sha256
 210   |...
 211 @end verbatim
 212
 213 Each directory is a normalized package name. When you try to list non
 214 existent directory contents (you are downloading package you have not
 215 seen before), then GoCheese will download information about package's
 216 versions with checksums and write them in corresponding
 217 @file{.sha256}, @file{.blake2_256}, @file{.sha512}, @file{.md5} files.
 218 However no package package tarball is downloaded.
 219
 220 When you request for particular package version, then its tarball is
 221 downloaded and verified against the stored checksum. But SHA256 is
 222 forced to be stored and used later.
 223
 224 For example @file{public-package} has @code{0.1} version, downloaded a
 225 long time ago with MD5 checksum. @code{0.1.1} version is downloaded more
 226 recently with BLAKE2b-256 checksum, also storing that checksum for
 227 @code{0.1}. @code{0.2} version is downloaded tarball, having forced
 228 SHA256 recalculated checksum. Also upstream has corresponding
 229 @file{.asc} signature file.
 230
 231 @file{private-package} is private package, because it contains
 232 @file{.internal} file. It can be uploaded and queries to it are not
 233 proxied to upstream PyPI. You have to create it manually. If you upload
 234 GPG signature, then it will be also stored.
 235
 236 @bye