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 too)
  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 (@code{/simple/} by default) automatically
  63 refreshes metainformation (available versions and their checksums)
  64 from the upstream, when queried for package directory listing.
  65 @option{-norefresh} prevents upstream queries.
  66
  67 @option{-gpgupdate} is useful mainly for migrated for Pyshop migrated
  68 repositories. It forces GPG signature files downloading for all existing
  69 package files.
  70
  71 You can upload packages to it with @url{https://pypi.org/project/twine/, twine}:
  72
  73 @verbatim
  74 twine upload
  75     --repository-url http://gocheese.host:8080/simple/ \
  76     --username spam \
  77     --password foo dist/tarball.tar.gz
  78 @end verbatim
  79
  80 Or you can store it permanently in @file{.pypirc}:
  81
  82 @verbatim
  83 [pypi]
  84 repository: https://gocheese.host/simple/
  85 username: spam
  86 password: foo
  87 @end verbatim
  88
  89 If @command{twine} sends SHA256 checksum in the request, then uploaded
  90 file is checked against it.
  91
  92 Pay attention that you have to manually create corresponding private
  93 package directory! You are not allowed to upload anything explicitly
  94 flagged as private.
  95
  96 @node Passwords
  97 @unnumbered Password authentication
  98
  99 Password authentication is required for packages uploading.
 100 You have to store your authentication data in @option{-passwd} file in
 101 following format:
 102
 103 @verbatim
 104 username:hashed-password
 105 @end verbatim
 106
 107 Empty lines and having @verb{|#|} at the beginning are skipped.
 108
 109 Supported hashing algorithms are:
 110
 111 @table @asis
 112
 113 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
 114     To get Argon2i hashed-password you can use any of following tools:
 115     @itemize
 116     @item @url{https://github.com/balakhonova/argon2i,
 117         go get github.com/balakhonova/argon2i} (Go)
 118     @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
 119     @end itemize
 120     Example user @code{foo} with password @code{bar} can have the
 121     following password file entry:
 122
 123 @verbatim
 124 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
 125 @end verbatim
 126
 127 @item SHA256
 128     You can use your operating system tools:
 129
 130 @verbatim
 131 # BSD-based systems:
 132 $ echo -n "password" | sha256
 133
 134 # GNU/Linux-based systems
 135 $ echo -n "password" | sha256sum
 136 @end verbatim
 137     Example user @code{foo} with password @code{bar} will have the
 138     following password file entry:
 139
 140 @verbatim
 141 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
 142 @end verbatim
 143
 144 @end table
 145
 146 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
 147
 148 @verbatim
 149 $ pkill -HUP gocheese
 150 $ kill -HUP `pidof gocheese`
 151 @end verbatim
 152
 153 Before refreshing it's recommended to check @option{-passwd} file with
 154 @option{-passwd-check} option to prevent daemon failure.
 155
 156 @node TLS
 157 @unnumbered TLS support
 158
 159 You can enable TLS support by specifying PEM-encoded X.509 certificate
 160 and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2
 161 negotiation, Keep-Alives, modern ciphersuites and ECC.
 162
 163 For example generate some self-signed certificate using GnuTLS toolset:
 164
 165 @verbatim
 166 $ certtool --generate-privkey --ecc --outfile prv.pem
 167 $ cert_template=`mktemp`
 168 $ echo cn=gocheese.host > $cert_template
 169 $ certtool \
 170     --generate-self-signed \
 171     --load-privkey=prv.pem \
 172     --template $cert_template \
 173     --outfile=cert.pem
 174 $ rm $cert_template
 175 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
 176 @end verbatim
 177
 178 @node Storage
 179 @unnumbered Storage format
 180
 181 Root directory has the following hierarchy:
 182
 183 @verbatim
 184 root
 185   +-- public-package
 186   |     +- public-package-0.1.tar.gz.sha256
 187   |     +- public-package-0.2.tar.gz
 188   |     +- public-package-0.2.tar.gz.asc
 189   |     +- public-package-0.2.tar.gz.sha256
 190   +-- private-package
 191   |     +- .internal
 192   |     +- private-package-0.1.tar.gz
 193   |     +- private-package-0.1.tar.gz.sha256
 194   |...
 195 @end verbatim
 196
 197 Each directory is a package name. When you try to list non existent
 198 directory contents (you are downloading package you have not seen
 199 before), then GoCheese will download information about package's
 200 versions with checksums and write them in corresponding @file{.sha256}
 201 files. However no package package tarball is downloaded.
 202
 203 When you request for particular package version, then its tarball is
 204 downloaded and verified against the checksum. For example in the root
 205 directory above we have downloaded only @file{public-package-0.2}.
 206 If upstream has corresponding @file{.asc} file, then it also will be
 207 downloaded.
 208
 209 Private packages contain @file{.internal} file, indicating that it must
 210 not be asked in PyPI if required version is missing. You have to create
 211 it manually.
 212
 213 @bye