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