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 Supported hashing algorithms are:
  79
  80 @table @asis
  81
  82 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
  83     To get Argon2i hashed-password you can use any of following tools:
  84     @itemize
  85     @item @url{https://github.com/balakhonova/argon2i,
  86         go get github.com/balakhonova/argon2i} (Go)
  87     @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
  88     @end itemize
  89     Example user @code{foo} with password @code{bar} can have the
  90     following password file entry:
  91
  92 @verbatim
  93 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
  94 @end verbatim
  95
  96 @item SHA256
  97     You can use your operating system tools:
  98
  99 @verbatim
 100 # BSD-based systems:
 101 $ echo -n "password" | sha256
 102
 103 # GNU/Linux-based systems
 104 $ echo -n "password" | sha256sum
 105 @end verbatim
 106     Example user @code{foo} with password @code{bar} will have the
 107     following password file entry:
 108
 109 @verbatim
 110 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
 111 @end verbatim
 112
 113 @end table
 114
 115 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
 116
 117 @verbatim
 118 $ pkill -HUP gocheese
 119 $ kill -HUP `pidof gocheese`
 120 @end verbatim
 121
 122 Before refreshing it's recommended to check @option{-passwd} file with
 123 @option{-passwd-check} option to prevent daemon failure.
 124
 125 @node Storage
 126 @unnumbered Storage format
 127
 128 Root directory has the following hierarchy:
 129
 130 @verbatim
 131 root
 132   +-- public-package
 133   |     +- public-package-0.1.tar.gz.sha256
 134   |     +- public-package-0.2.tar.gz
 135   |     +- public-package-0.2.tar.gz.sha256
 136   +-- private-package
 137   |     +- .private
 138   |     +- private-package-0.1.tar.gz
 139   |     +- private-package-0.1.tar.gz.sha256
 140   |...
 141 @end verbatim
 142
 143 Each directory is a package name. When you try to list non existent
 144 directory contents (you are downloading package you have not seen
 145 before), then GoCheese will download information about package's
 146 versions with checksums and write them in corresponding @file{.sha256}
 147 files. However no package package tarball is downloaded.
 148
 149 When you request for particular package version, then its tarball is
 150 downloaded and verified against the checksum. For example in the root
 151 directory above we have downloaded only @file{public-package-0.2}.
 152
 153 Private packages contain @file{.private} file, indicating that it must
 154 not be asked in PyPI if required version is missing. You have to create
 155 it manually.
 156
 157 @bye