2 @documentencoding UTF-8
8 GoCheese is Python private package repository and caching proxy.
10 It serves two purposes:
13 @item hosting of private locally uploaded packages
14 (conforming to @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503}
15 (Simple Repository API))
16 @item proxying and caching of missing packages from upstream
17 @url{https://pypi.org/, PyPI}
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:
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 graceful HTTP-server shutdown
29 @item no YAML configuration, just command-line arguments
30 @item no package overwriting ability (as PyPI does)
33 Also it contains @file{pyshop2packages.sh} migration script for
34 converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
35 GoCheese one, including private packages.
37 GoCheese is free software, licenced under
38 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
39 see the file COPYING for copying conditions.
43 * Password authentication: Passwords.
45 * Storage format: Storage.
51 To use it for download purposes, just configure your @file{pip.conf}:
55 index-url = http://gocheese.host:8080/simple/
58 @option{-refresh} URL behaves the same way as @option{-simple} one, but
59 is always refreshes package versions from PyPI when listing it. You can
60 use it to forcefully update known package versions.
62 You can upload packages to it with
63 @url{https://pypi.org/project/twine/, twine}:
67 --repository-url http://gocheese.host:8080/simple/ \
69 --password foo dist/tarball.tar.gz
73 @unnumbered Password authentication
75 Password authentication is required for packages uploading.
76 You have to store your authentication data in @option{-passwd} file in
80 username:hashed-password
83 Empty lines and having @verb{|#|} at the beginning are skipped.
85 Supported hashing algorithms are:
89 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
90 To get Argon2i hashed-password you can use any of following tools:
92 @item @url{https://github.com/balakhonova/argon2i,
93 go get github.com/balakhonova/argon2i} (Go)
94 @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
96 Example user @code{foo} with password @code{bar} can have the
97 following password file entry:
100 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
104 You can use your operating system tools:
108 $ echo -n "password" | sha256
110 # GNU/Linux-based systems
111 $ echo -n "password" | sha256sum
113 Example user @code{foo} with password @code{bar} will have the
114 following password file entry:
117 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
122 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
125 $ pkill -HUP gocheese
126 $ kill -HUP `pidof gocheese`
129 Before refreshing it's recommended to check @option{-passwd} file with
130 @option{-passwd-check} option to prevent daemon failure.
133 @unnumbered TLS support
135 You can enable TLS support by specifying PEM-encoded X.509 certificate
136 and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2
137 negotiation, Keep-Alives, modern ciphersuites and ECC.
139 For example generate some self-signed certificate using GnuTLS toolset:
142 $ certtool --generate-privkey --ecc --outfile prv.pem
143 $ cert_template=`mktemp`
144 $ echo cn=gocheese.host > $cert_template
146 --generate-self-signed \
147 --load-privkey=prv.pem \
148 --template $cert_template \
151 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
155 @unnumbered Storage format
157 Root directory has the following hierarchy:
162 | +- public-package-0.1.tar.gz.sha256
163 | +- public-package-0.2.tar.gz
164 | +- public-package-0.2.tar.gz.sha256
167 | +- private-package-0.1.tar.gz
168 | +- private-package-0.1.tar.gz.sha256
172 Each directory is a package name. When you try to list non existent
173 directory contents (you are downloading package you have not seen
174 before), then GoCheese will download information about package's
175 versions with checksums and write them in corresponding @file{.sha256}
176 files. However no package package tarball is downloaded.
178 When you request for particular package version, then its tarball is
179 downloaded and verified against the checksum. For example in the root
180 directory above we have downloaded only @file{public-package-0.2}.
182 Private packages contain @file{.private} file, indicating that it must
183 not be asked in PyPI if required version is missing. You have to create