doc/index.texi

   1 \input texinfo
   2 @settitle GoCheese
   3
   4 @copying
   5 Copyright @copyright{} 2019-2024 @email{stargrave@@stargrave.org, Sergey Matveev}
   6 @end copying
   7
   8 @node Top
   9 @top GoCheese
  10
  11 GoCheese is Python private package repository and caching proxy.
  12
  13 It serves two purposes:
  14
  15 @itemize
  16 @item proxying and caching of missing packages from upstream
  17     @url{https://pypi.org/, PyPI}, conforming to
  18     @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503}
  19     (Simple Repository API) and
  20     @url{https://warehouse.pypa.io/api-reference/json.html, JSON API}
  21 @item hosting of private locally uploaded packages, conforming to
  22     @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API}
  23 @end itemize
  24
  25 Why could you like it and how it can be better to fit your needs?
  26
  27 @itemize
  28 @item No database required. Only filesystem storage with few simple
  29     files per package. Package deletion, renaming, making it uploadable
  30     (private) is done with simple @command{mkdir}, @command{touch}, etc
  31     commands
  32 @item Just single statically compiled Go binary, UCSPI-TCP compatibility,
  33     high performance (including HTTP/2, keepalives and TLS session resumption)
  34 @item No configuration file, but several simple command line arguments
  35 @item Consistency (because of atomic synced operations) and integrity
  36     (because of cryptographic checksums stored nearby)
  37 @item Package's metadata and created times storing for uploaded and
  38     proxied packages
  39 @end itemize
  40
  41 Initially it was created as a fork of
  42 @url{https://github.com/c4s4/cheeseshop, cheeseshop},
  43 but nearly all the code was rewritten. It is aimed to be replacement for
  44 @command{PyShop} lacking huge quantity of features, reliability and
  45 consistency guarantees, workability without deprecated XML-RPC API, and
  46 suffering performance.
  47
  48 @itemize
  49
  50 @item Supports proxying and caching of non-internal packages from the
  51 upstream PyPI installation.
  52
  53 @item Supports uploading of internal packages through the standard
  54 Warehouse API, including signatures, metadata and checksums.
  55
  56 @item Supports @url{https://pythonwheels.com/, wheels},
  57 @url{https://packaging.python.org/specifications/core-metadata/, Metadata}
  58 with @url{https://www.python.org/dev/peps/pep-0566/, PEP-0566} compatible
  59 conversion to JSON, multiple (MD5, SHA256, SHA512, BLAKE2b-256) integrity
  60 checksums storing and verifying during uploading and proxying.
  61
  62 @item Supports Simple and JSON APIs, being able to replace PyPI for all
  63 downstream clients.
  64
  65 @item Stores package's creation time with solicitude as @code{mtime},
  66 giving it in HTTP headers and JSON API.
  67
  68 @item TLS and HTTP/2 capable transport to the upstream, with enabled
  69 keepalives and session resumption TLS tickets. Graceful HTTP server
  70 shutdown. Can work as a @url{https://cr.yp.to/ucspi-tcp.html, UCSPI-TCP}
  71 service.
  72
  73 @item Atomic and @code{fsync}ed reliable and consistent updates to the
  74 filesystem.
  75
  76 @item Has ability to authenticate upstream PyPI by its X.509
  77 certificate's SPKI hash.
  78
  79 @item User authentication supports passwords either hashed with SHA256
  80 or strengthened with @url{https://datatracker.ietf.org/doc/html/rfc9106, Argon2i}.
  81
  82 @end itemize
  83
  84 Also it contains @file{contrib/pyshop2packages.sh} migration script for
  85 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
  86 GoCheese one, including private packages.
  87
  88 GoCheese is
  89 @url{https://www.gnu.org/philosophy/pragmatic.html, copylefted}
  90 @url{https://www.gnu.org/philosophy/free-sw.html, free software}
  91 licenced under @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}.
  92
  93 Please send questions, bug reports and patches to @url{mailto:gocheese@@cypherpunks.ru}.
  94
  95 @insertcopying
  96
  97 @include install.texi
  98 @include usage.texi
  99 @include passwords.texi
 100 @include tls.texi
 101 @include storage.texi
 102
 103 @bye