README

   1 GoCheese is Python private package repository and caching proxy.
   2
   3 It serves two purposes:
   4
   5 * hosting of private locally uploaded packages
   6   (conforming to PEP-0503 (Simple Repository API))
   7 * proxying and caching of missing packages from upstream PyPI
   8
   9 To use it, just configure your pip.conf:
  10
  11     [install]
  12     index-url = http://gocheese.host:8080/simple/
  13
  14 You can upload packages to it with twine:
  15
  16     twine upload
  17         --repository-url http://gocheese.host:8080/simple/ \
  18         --username spam \
  19         --passwd foo dist/tarball.tar.gz
  20
  21 -refresh URL behaves the same way as -simple one, but is always
  22 refreshes package versions from PyPI when listing it. You can use it to
  23 forcefully update package version.
  24
  25 Initially it was created as a fork of https://github.com/c4s4/cheeseshop,
  26 but nearly all the code was rewritten. It has huge differences:
  27
  28 * no TLS support
  29 * no YAML configuration, just command-line arguments
  30 * no package overwriting ability
  31 * atomic packages store on filesystem
  32 * proxying and caching of missing packages
  33 * SHA256-checksummed packages (both uploaded and proxied one)
  34
  35 GoCheese is free software: see the file COPYING for copying conditions.
  36
  37                         Password authentication
  38                         =======================
  39
  40 You have to store your authentication data in a file (specified
  41 with -passwd option) with following format:
  42
  43     username:hashed-password
  44
  45 Supported hashing algorithms are SHA256 and Argon2i.
  46 It's recommended to use Argon2i.
  47
  48 To get Argon2i hashed-password you can use any of following tools:
  49
  50     https://github.com/balakhonova/argon2i (Go)
  51     https://github.com/p-h-c/phc-winner-argon2 (C)
  52
  53 To get SHA256 hashed-password you can use your operating system tools:
  54
  55     # BSD-based systems:
  56     $ echo -n 'password' | sha256
  57     # GNU/Linux-based systems
  58     $ echo -n 'password' | sha256sum
  59
  60 For example user "foo" with password "bar" can have the following
  61 hashed passwords:
  62
  63     foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
  64     foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
  65
  66 While daemon working you can refresh -passwd file with SIGHUP:
  67
  68     $ kill -HUP `pidof gocheese`
  69
  70 Before refreshing it's recommended to check -passwd file with -passwd-check
  71 option to prevent daemon failure.
  72
  73                          On-disk storage format
  74                          ======================
  75
  76 Root directory has the following hierarchy:
  77
  78     root
  79       +-- public-package
  80       |     +- public-package-0.1.tar.gz.sha256
  81       |     +- public-package-0.2.tar.gz
  82       |     +- public-package-0.2.tar.gz.sha256
  83       +-- private-package
  84       |     +- .private
  85       |     +- private-package-0.1.tar.gz
  86       |     +- private-package-0.1.tar.gz.sha256
  87       |...
  88
  89 Each directory is a package name. When you trie to list unexistent
  90 directory contents (you are downloading package you have not seen
  91 before), then GoCheese will download all its package versions with
  92 checksums and write then in .sha256 files. So you know what versions are
  93 available at the moment. When you asks for particular package, then its
  94 tarball is really downloaded and verified against the checksum. For
  95 example in the root directory above we have downloaded only
  96 public-package-0.2. Private packages contain .private file, indicating
  97 that it must not be asked in PyPI if required version is missing.