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 TLS support
  30 @item no YAML configuration, just command-line arguments
  31 @item no package overwriting ability (as PyPI does)
  32 @end itemize
  33
  34 GoCheese is free software, licenced under
  35 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3} conditions:
  36 see the file COPYING for copying conditions.
  37
  38 @menu
  39 * Usage::
  40 * Password authentication: Passwords.
  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 Storage
 129 @unnumbered Storage format
 130
 131 Root directory has the following hierarchy:
 132
 133 @verbatim
 134 root
 135   +-- public-package
 136   |     +- public-package-0.1.tar.gz.sha256
 137   |     +- public-package-0.2.tar.gz
 138   |     +- public-package-0.2.tar.gz.sha256
 139   +-- private-package
 140   |     +- .private
 141   |     +- private-package-0.1.tar.gz
 142   |     +- private-package-0.1.tar.gz.sha256
 143   |...
 144 @end verbatim
 145
 146 Each directory is a package name. When you try to list non existent
 147 directory contents (you are downloading package you have not seen
 148 before), then GoCheese will download information about package's
 149 versions with checksums and write them in corresponding @file{.sha256}
 150 files. However no package package tarball is downloaded.
 151
 152 When you request for particular package version, then its tarball is
 153 downloaded and verified against the checksum. For example in the root
 154 directory above we have downloaded only @file{public-package-0.2}.
 155
 156 Private packages contain @file{.private} file, indicating that it must
 157 not be asked in PyPI if required version is missing. You have to create
 158 it manually.
 159
 160 @bye