gocheese.texi

   1 \input texinfo
   2 @documentencoding UTF-8
   3 @settitle GoCheese
   4
   5 @node Top
   6 @top
   7
   8 GoCheese is Python private package repository and caching proxy.
   9
  10 It serves two purposes:
  11
  12 @itemize
  13 @item hosting of private locally uploaded packages
  14     (conforming to @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503}
  15     (Simple Repository API))
  16 @item proxying and caching of missing packages from upstream
  17     @url{https://pypi.org/, PyPI}
  18 @end itemize
  19
  20 Initially it was created as a fork of
  21 @url{https://github.com/c4s4/cheeseshop, cheeseshop},
  22 but nearly all the code was rewritten. It has huge differences:
  23
  24 @itemize
  25 @item proxying and caching of missing packages
  26 @item atomic packages store on filesystem
  27 @item SHA256-checksummed packages: storing checksums, giving them back,
  28     verifying stored files integrity, verifying checksum of uploaded
  29     packaged
  30 @item graceful HTTP-server shutdown
  31 @item no YAML configuration, just command-line arguments
  32 @item no package overwriting ability (as PyPI does)
  33 @end itemize
  34
  35 Also it contains @file{pyshop2packages.sh} migration script for
  36 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
  37 GoCheese one, including private packages.
  38
  39 GoCheese is free software, licenced under
  40 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
  41 see the file COPYING for copying conditions.
  42
  43 @menu
  44 * Usage::
  45 * Password authentication: Passwords.
  46 * TLS support: TLS.
  47 * Storage format: Storage.
  48 @end menu
  49
  50 @node Usage
  51 @unnumbered Usage
  52
  53 To use it for download purposes, just configure your @file{pip.conf}:
  54
  55 @verbatim
  56 [install]
  57 index-url = http://gocheese.host:8080/simple/
  58 @end verbatim
  59
  60 @option{-refresh} URL behaves the same way as @option{-simple} one, but
  61 is always refreshes package versions from PyPI when listing it. You can
  62 use it to forcefully update known package versions.
  63
  64 You can upload packages to it with
  65 @url{https://pypi.org/project/twine/, twine}:
  66
  67 @verbatim
  68 twine upload
  69     --repository-url http://gocheese.host:8080/simple/ \
  70     --username spam \
  71     --password foo dist/tarball.tar.gz
  72 @end verbatim
  73
  74 If @command{twine} sends SHA256 checksum in the request, then uploaded
  75 file is checked against it.
  76
  77 @node Passwords
  78 @unnumbered Password authentication
  79
  80 Password authentication is required for packages uploading.
  81 You have to store your authentication data in @option{-passwd} file in
  82 following format:
  83
  84 @verbatim
  85 username:hashed-password
  86 @end verbatim
  87
  88 Empty lines and having @verb{|#|} at the beginning are skipped.
  89
  90 Supported hashing algorithms are:
  91
  92 @table @asis
  93
  94 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
  95     To get Argon2i hashed-password you can use any of following tools:
  96     @itemize
  97     @item @url{https://github.com/balakhonova/argon2i,
  98         go get github.com/balakhonova/argon2i} (Go)
  99     @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
 100     @end itemize
 101     Example user @code{foo} with password @code{bar} can have the
 102     following password file entry:
 103
 104 @verbatim
 105 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
 106 @end verbatim
 107
 108 @item SHA256
 109     You can use your operating system tools:
 110
 111 @verbatim
 112 # BSD-based systems:
 113 $ echo -n "password" | sha256
 114
 115 # GNU/Linux-based systems
 116 $ echo -n "password" | sha256sum
 117 @end verbatim
 118     Example user @code{foo} with password @code{bar} will have the
 119     following password file entry:
 120
 121 @verbatim
 122 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
 123 @end verbatim
 124
 125 @end table
 126
 127 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
 128
 129 @verbatim
 130 $ pkill -HUP gocheese
 131 $ kill -HUP `pidof gocheese`
 132 @end verbatim
 133
 134 Before refreshing it's recommended to check @option{-passwd} file with
 135 @option{-passwd-check} option to prevent daemon failure.
 136
 137 @node TLS
 138 @unnumbered TLS support
 139
 140 You can enable TLS support by specifying PEM-encoded X.509 certificate
 141 and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2
 142 negotiation, Keep-Alives, modern ciphersuites and ECC.
 143
 144 For example generate some self-signed certificate using GnuTLS toolset:
 145
 146 @verbatim
 147 $ certtool --generate-privkey --ecc --outfile prv.pem
 148 $ cert_template=`mktemp`
 149 $ echo cn=gocheese.host > $cert_template
 150 $ certtool \
 151     --generate-self-signed \
 152     --load-privkey=prv.pem \
 153     --template $cert_template \
 154     --outfile=cert.pem
 155 $ rm $cert_template
 156 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
 157 @end verbatim
 158
 159 @node Storage
 160 @unnumbered Storage format
 161
 162 Root directory has the following hierarchy:
 163
 164 @verbatim
 165 root
 166   +-- public-package
 167   |     +- public-package-0.1.tar.gz.sha256
 168   |     +- public-package-0.2.tar.gz
 169   |     +- public-package-0.2.tar.gz.sha256
 170   +-- private-package
 171   |     +- .private
 172   |     +- private-package-0.1.tar.gz
 173   |     +- private-package-0.1.tar.gz.sha256
 174   |...
 175 @end verbatim
 176
 177 Each directory is a package name. When you try to list non existent
 178 directory contents (you are downloading package you have not seen
 179 before), then GoCheese will download information about package's
 180 versions with checksums and write them in corresponding @file{.sha256}
 181 files. However no package package tarball is downloaded.
 182
 183 When you request for particular package version, then its tarball is
 184 downloaded and verified against the checksum. For example in the root
 185 directory above we have downloaded only @file{public-package-0.2}.
 186
 187 Private packages contain @file{.private} file, indicating that it must
 188 not be asked in PyPI if required version is missing. You have to create
 189 it manually.
 190
 191 @bye