README

   1 Package-cache is a simple caching proxy for package downloads.  Just
   2 configure a list of upstream sources (with the ``--source`` option)
   3 and point clients at the package-cache server.  The first time a
   4 package is requested, we download that package from one of the sources
   5 and cache it locally, while also streaming it to the client.  Future
   6 requests for that package are streamed directly from the local cache.
   7 This helps reduce the load on the network and source servers, if you
   8 have a number of local clients that will repeatedly request the same
   9 files (e.g. `Gentoo's distfiles`_).
  10
  11 We don't do anything fancy with `Cache-Control headers`_, since
  12 package source files should include the version stamp in the filename
  13 itself (e.g. ``my-package-0.1.2.tar.gz``).  Files are cached after the
  14 first request, and stored forever.  This means that every package
  15 you've ever requested will still be there if you need it later.
  16 That's nice, but it will end up consuming a fair amount of disk space.
  17 You might want to periodically cull the cache, using access times to
  18 see which files you are unlikely to want in the future.
  19
  20 Package-cache is written in Python, and has no dependencies outside
  21 the standard library.
  22
  23 Running package-cache
  24 =====================
  25
  26 By default, we'll use `Python's reference WSGI implementation`_ to run
  27 our application::
  28
  29   $ package-cache --source http://distfiles.gentoo.org/
  30
  31 For other command-line options, see::
  32
  33   $ package-cache --help
  34
  35 If you need a more perfomant backend, you might try Gunicorn_.
  36
  37 Gentoo
  38 ======
  39
  40 There's an OpenRC_ init script in ``contrib/openrc/init.d``, and a
  41 package-cache ebuild in my `wtk overlay`_.  To use package-cache as a
  42 caching proxy for your distfiles downloads, add the ``wtk`` overlay to
  43 layman_ and run::
  44
  45   # emerge --ask --verbose net-proxy/package-cache
  46   # rc-update add default net-proxy/package-cache
  47   # rc-service package-cache start
  48
  49 You can tweak the parameters by setting variables in
  50 ``/etc/conf.d/package-cache`` (``PC_USER``, ``PC_GROUP``,
  51 ``CACHE_DIR``, ``HOST``, ``PORT``, ``SOURCES``, and ``PC_OPTS``).  See
  52 the init script for default values.
  53
  54 Once you've setup your package-cache service, just point your local
  55 package manager to the cache server instead of the usual mirror.  For
  56 Portage_, that's going to be something like:
  57
  58   GENTOO_MIRRORS="http://my-package-cache-server.net:4000/"
  59
  60 in your ``/etc/portage/make.conf``.
  61
  62 If you *don't* want to tweak your clients (perhaps there are many of
  63 them, or they are out of your direct control), you can add some
  64 firewall rules to your router to transparently proxy specific Gentoo
  65 mirrors.  With an internal ``eth1`` and an internal proxy on
  66 192.168.0.11, that looks something like::
  67
  68   # CACHE_IP=192.168.0.11
  69   # for SOURCE_IP in $(dig +short distfiles.gentoo.org);
  70   > do
  71   >   iptables --table nat --append PREROUTING --protocol tcp \
  72   >     --in-interface eth1 ! --source "${CACHE_IP}" \
  73   >     --destination "${SOURCE_IP}" \
  74   >     --match tcp --destination-port 80 \
  75   >     --jump DNAT --to-destination "${CACHE_IP}:4000" ;
  76   > done
  77
  78 To remove those entries later, repeat the command with ``--delete``
  79 instead of ``--append``.  You may need to list the ``SOURCE_IP`` values
  80 explicitly if the DNS entries have changed.  Run::
  81
  82   # iptables --table nat --list PREROUTING --numeric
  83
  84 to list the entries.  See ``iptables(8)`` and
  85 ``iptables-extensions(8)`` for more details.
  86
  87 .. _Gentoo's distfiles:
  88   https://wiki.gentoo.org/wiki/Project:Infrastructure/Source_mirrors
  89 .. _Cache-Control headers:
  90   https://tools.ietf.org/html/rfc2616#section-14.9
  91 .. _Python's reference WSGI implementation:
  92   http://docs.python.org/3/library/wsgiref.html
  93 .. _Gunicorn:
  94   http://gunicorn-docs.readthedocs.org/en/latest/run.html#gunicorn
  95 .. _OpenRC: http://www.gentoo.org/proj/en/base/openrc/
  96 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
  97 .. _layman: https://wiki.gentoo.org/wiki/Layman
  98 .. _Portage: http://wiki.gentoo.org/wiki/Project:Portage