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