2 @documentencoding UTF-8
6 Copyright @copyright{} 2019 @email{stargrave@@stargrave.org, Sergey Matveev}
12 GoCheese is Python private package repository and caching proxy.
14 It serves two purposes:
17 @item proxying and caching of missing packages from upstream
18 @url{https://pypi.org/, PyPI}, conforming to
19 @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503}
20 (Simple Repository API)
21 @item hosting of private locally uploaded packages, conforming to
22 @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API}
25 Initially it was created as a fork of
26 @url{https://github.com/c4s4/cheeseshop, cheeseshop},
27 but nearly all the code was rewritten. It has huge differences:
30 @item Proxying and caching of missing packages, including GPG signatures
31 @item @url{https://pythonwheels.com/, Wheel} uploading support
32 @item Integrity check of proxied packages: MD5, SHA256, SHA512, BLAKE2b-256
33 @item SHA256 checksums for stored packages
34 @item Verifying of SHA256 checksum for uploaded packages
35 @item Storing of uploaded GPG signatures
36 @item Secure Argon2i (or SHA256) stored passwords hashing
37 @item No YAML configuration, just command-line arguments
38 @item No package overwriting ability (as PyPI does too)
39 @item Graceful HTTP-server shutdown
40 @item Atomic packages store on filesystem
43 Also it contains @file{pyshop2packages.sh} migration script for
44 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
45 GoCheese one, including private packages.
47 GoCheese is free software, licenced under
48 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
49 see the file COPYING for copying conditions.
51 Please send questions, bug reports and patches to @url{gocheese@@cypherpunks.ru}.
58 * Password authentication: Passwords.
60 * Storage format: Storage.
63 @include download.texi
68 To use it for download purposes, just configure your @file{pip.conf}:
72 index-url = http://gocheese.host:8080/simple/
75 @option{-refresh} URL (@code{/simple/} by default) automatically
76 refreshes metainformation (available versions and their checksums)
77 from the upstream, when queried for package directory listing.
78 @option{-norefresh} prevents upstream queries.
80 @option{-gpgupdate} is useful mainly for migrated for Pyshop migrated
81 repositories. It forces GPG signature files downloading for all existing
84 You can upload packages to it with @url{https://pypi.org/project/twine/, twine}:
88 --repository-url http://gocheese.host:8080/simple/ \
90 --password foo dist/tarball.tar.gz
93 Or you can store it permanently in @file{.pypirc}:
97 repository: https://gocheese.host/simple/
102 If @command{twine} sends SHA256 checksum in the request, then uploaded
103 file is checked against it.
105 Pay attention that you have to manually create corresponding private
106 package directory! You are not allowed to upload anything explicitly
107 flagged as internal package.
110 @unnumbered Password authentication
112 Password authentication is required for packages uploading.
113 You have to store your authentication data in @option{-passwd} file in
117 username:hashed-password
120 Empty lines and having @verb{|#|} at the beginning are skipped.
122 Supported hashing algorithms are:
126 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
127 To get Argon2i hashed-password you can use any of following tools:
129 @item @url{https://github.com/balakhonova/argon2i,
130 go get github.com/balakhonova/argon2i} (Go)
131 @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
133 Example user @code{foo} with password @code{bar} can have the
134 following password file entry:
137 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
141 You can use your operating system tools:
145 $ echo -n "password" | sha256
147 # GNU/Linux-based systems
148 $ echo -n "password" | sha256sum
150 Example user @code{foo} with password @code{bar} will have the
151 following password file entry:
154 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
159 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
162 $ pkill -HUP gocheese
163 $ kill -HUP `pidof gocheese`
166 Before refreshing it's recommended to check @option{-passwd} file with
167 @option{-passwd-check} option to prevent daemon failure.
170 @unnumbered TLS support
172 You can enable TLS support by specifying PEM-encoded X.509 certificate
173 and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2
174 negotiation, Keep-Alives, modern ciphersuites and ECC.
176 For example generate some self-signed certificate using GnuTLS toolset:
179 $ certtool --generate-privkey --ecc --outfile prv.pem
180 $ cert_template=`mktemp`
181 $ echo cn=gocheese.host > $cert_template
183 --generate-self-signed \
184 --load-privkey=prv.pem \
185 --template $cert_template \
188 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
192 @unnumbered Storage format
194 Root directory has the following hierarchy:
199 | +- public-package-0.1.tar.gz.md5
200 | +- public-package-0.1.tar.gz.blake2_256
201 | +- public-package-0.1.1.tar.gz.blake2_256
202 | +- public-package-0.2.tar.gz
203 | +- public-package-0.2.tar.gz.asc
204 | +- public-package-0.2.tar.gz.sha256
207 | +- private-package-0.1.tar.gz
208 | +- private-package-0.1.tar.gz.asc
209 | +- private-package-0.1.tar.gz.sha256
213 Each directory is a normalized package name. When you try to list non
214 existent directory contents (you are downloading package you have not
215 seen before), then GoCheese will download information about package's
216 versions with checksums and write them in corresponding
217 @file{.sha256}, @file{.blake2_256}, @file{.sha512}, @file{.md5} files.
218 However no package package tarball is downloaded.
220 When you request for particular package version, then its tarball is
221 downloaded and verified against the stored checksum. But SHA256 is
222 forced to be stored and used later.
224 For example @file{public-package} has @code{0.1} version, downloaded a
225 long time ago with MD5 checksum. @code{0.1.1} version is downloaded more
226 recently with BLAKE2b-256 checksum, also storing that checksum for
227 @code{0.1}. @code{0.2} version is downloaded tarball, having forced
228 SHA256 recalculated checksum. Also upstream has corresponding
229 @file{.asc} signature file.
231 @file{private-package} is private package, because it contains
232 @file{.internal} file. It can be uploaded and queries to it are not
233 proxied to upstream PyPI. You have to create it manually. If you upload
234 GPG signature, then it will be also stored.