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