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 (conforming to
14 @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503} (Simple
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 GoCheese is free software, licenced under
34 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
35 see the file COPYING for copying conditions.
39 * Password authentication: Passwords.
41 * Storage format: Storage.
47 To use it for download purposes, just configure your @file{pip.conf}:
51 index-url = http://gocheese.host:8080/simple/
54 @option{-refresh} URL behaves the same way as @option{-simple} one, but
55 is always refreshes package versions from PyPI when listing it. You can
56 use it to forcefully update known package versions.
58 You can upload packages to it with
59 @url{https://pypi.org/project/twine/, twine}:
63 --repository-url http://gocheese.host:8080/simple/ \
65 --passwd foo dist/tarball.tar.gz
69 @unnumbered Password authentication
71 Password authentication is required for packages uploading.
72 You have to store your authentication data in @option{-passwd} file in
76 username:hashed-password
79 Empty lines and having @verb{|#|} at the beginning are skipped.
81 Supported hashing algorithms are:
85 @item @url{https://www.argon2i.com/, Argon2i} (recommended one!)
86 To get Argon2i hashed-password you can use any of following tools:
88 @item @url{https://github.com/balakhonova/argon2i,
89 go get github.com/balakhonova/argon2i} (Go)
90 @item @url{https://github.com/p-h-c/phc-winner-argon2} (C)
92 Example user @code{foo} with password @code{bar} can have the
93 following password file entry:
96 foo:$argon2i$v=19$m=32768,t=3,p=4$OGU5MTM3YjVlYzQwZjhkZA$rVn53v6Ckpf7WH0676ZQLr9Hbm6VH3YnL6I9ONJcIIU
100 You can use your operating system tools:
104 $ echo -n "password" | sha256
106 # GNU/Linux-based systems
107 $ echo -n "password" | sha256sum
109 Example user @code{foo} with password @code{bar} will have the
110 following password file entry:
113 foo:$sha256$fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
118 You can refresh passwords by sending @code{SIGHUP} signal to the working daemon:
121 $ pkill -HUP gocheese
122 $ kill -HUP `pidof gocheese`
125 Before refreshing it's recommended to check @option{-passwd} file with
126 @option{-passwd-check} option to prevent daemon failure.
129 @unnumbered TLS support
131 You can enable TLS support by specifying PEM-encoded X.509 certificate
132 and private key files. Go's TLS implementation supports TLS 1.3, HTTP/2
133 negotiation, Keep-Alives, modern ciphersuites and ECC.
135 For example generate some self-signed certificate using GnuTLS toolset:
138 $ certtool --generate-privkey --ecc --outfile prv.pem
139 $ cert_template=`mktemp`
140 $ echo cn=gocheese.host > $cert_template
142 --generate-self-signed \
143 --load-privkey=prv.pem \
144 --template $cert_template \
147 $ gocheese -tls-cert cert.pem -tls-key prv.pem [...]
151 @unnumbered Storage format
153 Root directory has the following hierarchy:
158 | +- public-package-0.1.tar.gz.sha256
159 | +- public-package-0.2.tar.gz
160 | +- public-package-0.2.tar.gz.sha256
163 | +- private-package-0.1.tar.gz
164 | +- private-package-0.1.tar.gz.sha256
168 Each directory is a package name. When you try to list non existent
169 directory contents (you are downloading package you have not seen
170 before), then GoCheese will download information about package's
171 versions with checksums and write them in corresponding @file{.sha256}
172 files. However no package package tarball is downloaded.
174 When you request for particular package version, then its tarball is
175 downloaded and verified against the checksum. For example in the root
176 directory above we have downloaded only @file{public-package-0.2}.
178 Private packages contain @file{.private} file, indicating that it must
179 not be asked in PyPI if required version is missing. You have to create