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