Fix up some errors in the packaging.

[quix0rs-apt-p2p.git] / README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..a6b1d5f
--- /dev/null
+++ b/README
@@ -0,0 +1,86 @@
+Apt-DHT: a peer-to-peer proxy for apt downloads
+
+### Goal
+
+Similar to DebTorrent[1], Apt-DHT will act as a proxy between apt
+requests and a debian repository server, downloading any requested
+files from peers (if possible), but falling back to a direct HTTP
+download. Unlike DebTorrent, Apt-DHT will be simple, efficient, and
+fast.
+
+[1]: http://debtorrent.alioth.debian.org/
+
+### Features
+
+* Downloads from peers, increasing the available bandwidth to the 
+  user
+* Reduces the bandwidth requirements needed to setup a repository 
+  of packages
+* Seamlessly integrates with the current APT tool
+* Automatically falls back to downloading from an HTTP mirror when 
+  peers are not available
+* Builds on other already existing tools where possible
+* Fast and requires limited CPU and memory
+* Will try to download any file it can find a hash for from peers
+  (including Packages.bz2, Sources.gz, ...)
+
+This software is open-source and is released at no charge under the 
+terms of the GPL v2 license[2].
+
+[2]: http://www.opensource.org/licenses/gpl-license.php
+
+### Requirements
+
+To run the full program (e.g. to actually download something):
+
+* Python 2.4 or higher
+* Twisted[3] 2.4 or higher
+  - including Twisted Web2[4] 0.2 or higher
+* python-apt[5] 0.6.20 or higher
+* An APT-based package management system (such as Debian distributions 
+  have)
+
+If you just want to run the DHT part of the program (e.g. to provide a
+bootstrap node), then you only need:
+
+* Python 2.4 or higher
+* Twisted[3] 2.4 or higher
+
+[3]: http://twistedmatrix.com/trac/
+[4]: http://twistedmatrix.com/trac/wiki/TwistedWeb2
+[5]: http://packages.debian.org/unstable/python/python-apt
+
+### Development Status
+
+This project is still undergoing massive code and protocol changes
+and hasn't yet seen a release. The code has worked, and is
+occasionally working, and will definitely be working soon in the
+future.
+
+### Installing
+
+There are detailed instructions on the web site[6] showing how to
+install the Apt-DHT program. If you have any trouble using the
+program, you can email me[7], or come and find me in the
+DebTorrent IRC channel (#debtorrent on OFTC[8]). If you think
+you've found a bug in the program, please let me know.
+
+[6]: http://www.camrdale.org/apt-dht.html
+[7]: mailto:camrdale@gmail.com
+[8]: http://irc.oftc.net
+
+### The Code
+
+The latest code for the project is currently hosted in a Git 
+repository[9]. It is publicly readable, and there are instructions
+there for downloading the code. It is originally based on the
+khashmir[10] implementation of the kademlia DHT[11]. All of the
+networking is handled by the Twisted and Twisted Web2
+libraries. Dealing with apt's repository files is handled by
+python-apt, the code for which is based on that of the
+apt-proxy[12] program.
+
+[9]: http://git.camrdale.org/?p=apt-dht.git;a=summary
+[10]: http://khashmir.sourceforge.net/
+[11]: http://en.wikipedia.org/wiki/Kademlia
+[12]: http://apt-proxy.sourceforge.net/