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