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