2 @documentencoding UTF-8
8 GoCheese is Python private package repository and caching proxy.
10 It serves two purposes:
13 @item proxying and caching of missing packages from upstream
14 @url{https://pypi.org/, PyPI}, conforming to
15 @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503}
16 (Simple Repository API)
17 @item hosting of private locally uploaded packages, conforming to
18 @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API}
21 Initially it was created as a fork of
22 @url{https://github.com/c4s4/cheeseshop, cheeseshop},
23 but nearly all the code was rewritten. It has huge differences:
26 @item proxying and caching of missing packages, including GPG signatures
27 @item @url{https://pythonwheels.com/, Wheel} uploading support
28 @item integrity check of proxied packages: MD5, SHA256, SHA512, BLAKE2b-256
29 @item SHA256 checksums for stored packages
30 @item verifying of SHA256 checksum for uploaded packages
31 @item storing of uploaded GPG signatures
32 @item secure Argon2i (or SHA256) stored passwords hashing
33 @item no YAML configuration, just command-line arguments
34 @item no package overwriting ability (as PyPI does too)
35 @item atomic packages store on filesystem
36 @item graceful HTTP-server shutdown
39 Also it contains @file{pyshop2packages.sh} migration script for
40 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
41 GoCheese one, including private packages.
43 GoCheese is free software, licenced under
44 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
45 see the file COPYING for copying conditions.
49 * Password authentication: Passwords.
51 * Storage format: Storage.
57 To use it for download purposes, just configure your @file{pip.conf}:
61 index-url = http://gocheese.host:8080/simple/
64 @option{-refresh} URL (@code{/simple/} by default) automatically
65 refreshes metainformation (available versions and their checksums)
66 from the upstream, when queried for package directory listing.
67 @option{-norefresh} prevents upstream queries.
69 @option{-gpgupdate} is useful mainly for migrated for Pyshop migrated
70 repositories. It forces GPG signature files downloading for all existing
73 You can upload packages to it with @url{https://pypi.org/project/twine/, twine}:
77 --repository-url http://gocheese.host:8080/simple/ \
79 --password foo dist/tarball.tar.gz
82 Or you can store it permanently in @file{.pypirc}:
86 repository: https://gocheese.host/simple/
91 If @command{twine} sends SHA256 checksum in the request, then uploaded
92 file is checked against it.
94 Pay attention that you have to manually create corresponding private
95 package directory! You are not allowed to upload anything explicitly
96 flagged as internal package.
99 @unnumbered Password authentication
101 Password authentication is required for packages uploading.
102 You have to store your authentication data in @option{-passwd} file in
106 username:hashed-password
109 Empty lines and having @verb{|#|} at the beginning are skipped.
111 Supported hashing algorithms are:
115 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
116 To get Argon2i hashed-password you can use any of following tools:
118 @item @url{https://github.com/balakhonova/argon2i,
119 go get github.com/balakhonova/argon2i} (Go)
120 @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
122 Example user @code{foo} with password @code{bar} can have the
123 following password file entry:
126 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
130 You can use your operating system tools:
134 $ echo -n "password" | sha256
136 # GNU/Linux-based systems
137 $ echo -n "password" | sha256sum
139 Example user @code{foo} with password @code{bar} will have the
140 following password file entry:
143 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
148 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
151 $ pkill -HUP gocheese
152 $ kill -HUP `pidof gocheese`
155 Before refreshing it's recommended to check @option{-passwd} file with
156 @option{-passwd-check} option to prevent daemon failure.
159 @unnumbered TLS support
161 You can enable TLS support by specifying PEM-encoded X.509 certificate
162 and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2
163 negotiation, Keep-Alives, modern ciphersuites and ECC.
165 For example generate some self-signed certificate using GnuTLS toolset:
168 $ certtool --generate-privkey --ecc --outfile prv.pem
169 $ cert_template=`mktemp`
170 $ echo cn=gocheese.host > $cert_template
172 --generate-self-signed \
173 --load-privkey=prv.pem \
174 --template $cert_template \
177 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
181 @unnumbered Storage format
183 Root directory has the following hierarchy:
188 | +- public-package-0.1.tar.gz.md5
189 | +- public-package-0.1.tar.gz.blake2_256
190 | +- public-package-0.1.1.tar.gz.blake2_256
191 | +- public-package-0.2.tar.gz
192 | +- public-package-0.2.tar.gz.asc
193 | +- public-package-0.2.tar.gz.sha256
196 | +- private-package-0.1.tar.gz
197 | +- private-package-0.1.tar.gz.asc
198 | +- private-package-0.1.tar.gz.sha256
202 Each directory is a normalized package name. When you try to list non
203 existent directory contents (you are downloading package you have not
204 seen before), then GoCheese will download information about package's
205 versions with checksums and write them in corresponding
206 @file{.sha256}, @file{.blake2_256}, @file{.sha512}, @file{.md5} files.
207 However no package package tarball is downloaded.
209 When you request for particular package version, then its tarball is
210 downloaded and verified against the stored checksum. But SHA256 is
211 forced to be stored and used later.
213 For example @file{public-package} has @code{0.1} version, downloaded a
214 long time ago with MD5 checksum. @code{0.1.1} version is downloaded more
215 recently with BLAKE2b-256 checksum, also storing that checksum for
216 @code{0.1}. @code{0.2} version is downloaded tarball, having forced
217 SHA256 recalculated checksum. Also upstream has corresponding
218 @file{.asc} signature file.
220 @file{private-package} is private package, because it contains
221 @file{.internal} file. It can be uploaded and queries to it are not
222 proxied to upstream PyPI. You have to create it manually. If you upload
223 GPG signature, then it will be also stored.