[tor-commits] [bridgedb/master] Update the README with deployment instructions.
asn at torproject.org
asn at torproject.org
Tue Jul 23 22:16:45 UTC 2013
commit 8115774d7e2c2729a231f33200b91d8017cdc717
Author: Isis Lovecruft <isis at torproject.org>
Date: Fri Jul 5 01:40:49 2013 +0000
Update the README with deployment instructions.
* CHANGED the README to markdown format.
* ADD user friendly instructions at the top, so that anyone who is confused
and looking for bridges or TBBs is pointed in the right direction.
* ADD detailed maintainer instructions at the bottom, including sections on
dependencies, using in a virtualenv, setup and configuration (this should
probably still be updated more, as not all the the options in the testing
CONFIG in lib/bridgedb/Main.py are in bridgedb.conf), enabling additional
features, and running.
---
README | 107 ------------------------------
README.md | 219 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 219 insertions(+), 107 deletions(-)
diff --git a/README b/README
deleted file mode 100644
index 4fdeff1..0000000
--- a/README
+++ /dev/null
@@ -1,107 +0,0 @@
-To set up:
- - Install Python 2.4 or later.
- - Install depdencencies. On Debian, you can do:
- sudo apt-get install python-twisted python-openssl python-ipaddr \
- python-gpgme python-babel python-recaptcha python-beautifulsoup \
- python-mako
- - If you use a virtualenv, we recommend you use pip 1.3.1 or later, else it
- will download over http. You can install dependencies with:
- pip install -r requirements.txt
- Note that some dependencies (ipaddr) do not have SSL URLs in the pypi index
- and will still download over http.
- - To run unit tests, "python setup.py test"
- - Set the prefix in setup.cfg, or comment out if using a virtualenv
- - python setup.py install
- - To generate translation files, run "python setup.py trans"
- - Run "python setup.py install_data" to install them
- - Edit bridgedb.conf; put it somewhere good.
- - Make sure that the input files referred to in bridgedb.conf exist.
- - You can make a self-signed certificate with
- openssl req -x509 -new -nodes > cert
- - Set up PYTHONPATH to include "~/lib/python2.6/site-packages/".
- - To install Maxmind GeoIP
- - Debian: apt-get install python-geoip
- - Others: http://www.maxmind.com/app/python
- - To enable recaptcha support
- - set the options RECAPTCHA_ENABLED, RECAPTCHA_PUB_KEY,
- and RECAPTCHA_PRIV_KEY in bridgedb.conf.
- - A recaptcha.net account is required.
- - Install these required packages:
- - Debian: apt-get install python-recaptcha python-beautifulsoup
- python-gpgme
- - Python: pip install recaptcha-client BeautifulSoup pygpgme
- - Others: http://pypi.python.org/pypi/recaptcha-client
- http://pypi.python.org/pypi/BeautifulSoup
- http://pypi.python.org/pypi/pygpgme
-
-To translate:
- - extract all strings:
- python setup.py extract_messages
- a .pot file will be created in ./i18n/templates/bridgedb.pot
- - init catalogs for each desired languages:
- python setup.py init_catalog -l LANG
- (where 'LANG' is the 2 or 4 letter country-code, eg. 'es')
- - edit strings in ./i18n/LANG/bridgedb.po
- - convert to binary format
- python setup.py compile_catalog
- - Don't forget to reinstall to update the templates!:
- python setup.py install
-
-To run:
- - Run "python -m TorBridgeDB bridgedb.conf"
-
- - When you have new lists of bridges, replace the old files and send the
- process a sighup.
-
-To extract bucket files with unallocated bridges:
-
- - Edit the configuration file value 'FILE_BUCKETS' according to your needs.
- For example, the following is a possible configuration:
-
- FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 }
-
- This configuration for buckets would result in 3 files being created for
- bridge distribution: name1-2010-07-17.brdgs, name2-2010-07-17.brdgs and
- foobar-2010-07-17.brdgs. The first file would contain 10 bridges from
- BridgeDB's 'unallocated' pool. The second file would contain 15 bridges
- from the same pool and the third one similarly 3 bridges. These files can
- then be handed out to trusted parties via mail or fed to other distribution
- mechanisms such as twitter.
-
-To use with HTTPS:
- - Just connect to the appropriate port.
-
-To use with email:
- - Any mail sent to the email port with a subject or a single line _exactly_
- equal to "get bridges" will get answered, assuming the domain is okay.
-
-To indicate which bridges are blocked:
- - Uncomment or add COUNTRY_BLOCK_FILE to your bridgedb.conf
- - The syntax of the COUNTRY_BLOCK_FILE, 1 entry per line:
- fingerprint <bridge fingerprint> country-code <country code>
- - If this file is present, bridgedb will filter blocked bridges from responses
- - For GeoIP support make sure to install Maxmind GeoIP
-
-To sign emails with gpg:
- - Add these two options to your bridgedb.conf:
-
- EMAIL_GPG_SIGNING_ENABLED, EMAIL_GPG_SIGNING_KEY
-
- The former may be either True or False, and the latter must
- point to the ascii-armored key file. The keyfile must not be
- passphrase protected.
-
-To update the SQL schema:
- - Install sqlite3:
- - Debian: apt-get install sqlite3
- - Others: http://www.sqlite.org/download.html
- - Run "sqlite3 path/to/bridgedist.db.sqlite"
- - Enter the following commands at the prompt: sqlite>
- CREATE TABLE BlockedBridges ( id INTEGER PRIMARY KEY NOT NULL, hex_key, blocking_country);
- CREATE INDEX BlockedBridgesBlockingCountry on BlockedBridges(hex_key);
- CREATE TABLE WarnedEmails ( email PRIMARY KEY NOT NULL, when_warned);
- CREATE INDEX WarnedEmailsWasWarned on WarnedEmails ( email );
- REPLACE INTO Config VALUES ( 'schema-version', 2 );
-
-Support
- - Send your questions to aagbsn at torproject.org.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9a50246
--- /dev/null
+++ b/README.md
@@ -0,0 +1,219 @@
+## BridgeDB
+-----------
+
+BridgeDB is a collection of backend servers used to distribute
+[Tor Bridges](https://www.torproject.org/docs/bridges). It currently consists
+of a webserver with [an HTTPS interface](https://bridges.torproject.org), an
+email responder, and an SQLite database.
+
+#### What are Tor Bridges?
+[Tor Bridges](https://www.torproject.org/docs/bridges) are special Tor relays
+which are not listed in the public relay directory. They are used to help
+circumvent [censorship](https://ooni.torproject.org) by providing users with
+connections to the public relays in the Tor network.
+
+Tor Bridges are different from normal relays in another important way: they
+can run what are called *Pluggable* *Transports*.
+
+#### What's a Pluggable Transport?
+A
+[Pluggable Transport](https://www.torproject.org/docs/pluggable-transports.html.en)
+is a program which is *pluggable* — meaning that it is meant to work with lots
+of other anonymity and censorship circumvention software, not just Tor — and
+is a *transport* — meaning that it transports your internet traffic, usually
+in a way which makes it look different. For example,
+[Obfsproxy](https://www.torproject.org/projects/obfsproxy.html.en) is a
+Pluggable Transport which disguises your traffic by adding an obfuscating
+layer of encryption.
+
+#### So how do I use this?
+Well, probably, you don't. But if you're looking for bridges, you can use
+[BridgeDB's web interface](https://bridges.torproject.org), which has
+instructions on getting the Pluggable Transports Tor Browser Bundle, as well
+as instructions for getting extra Bridges.
+
+
+## Maintainer Setup
+
+### Dependencies and installation
+BridgeDB requires the following OS-level dependencies:
+
+ - Python>=2.6
+ - OpenSSL>=1.0.1e
+ - [SQLite3](http://www.maxmind.com/app/python)
+ - [MaxMind GeoIP](https://www.maxmind.com/en/geolocation_landing)
+ - [python-setuptools](https://pypi.python.org/pypi/setuptools)
+
+As well as the following Python dependencies (from ./requirements.txt):
+
+ Babel==0.9.6
+ BeautifulSoup==3.2.1
+ Mako==0.8.1
+ MarkupSafe==0.18
+ Twisted>=13.0.0
+ argparse>=1.2.1
+ distribute>=0.6.46
+ ipaddr>=2.1.10
+ pyOpenSSL>=0.13
+ pygeoip>=0.2.6
+ pygpgme==0.3
+ recaptcha>=1.0rc1
+ recaptcha-client>=1.0.6
+ wsgiref>=0.1.2
+ zope.interface>=4.0.5
+
+### Deploying BridgeDB in a Python virtualenv
+
+ - Install Python 2.6 or later, and other OS-level dependencies. On Debian,
+ you can do:
+
+ sudo apt-get install python openssl sqlite3 tor-geoip
+
+ - Install Pip 1.3.1 or later. Debian sid has this version, but if you're
+ tracking a different release, the easiest way to install a newer Pip is to
+ use the Pip development teams's
+ [getpip script](https://raw.github.com/pypa/pip/master/contrib/get-pip.py):
+
+ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
+ sudo python get-pip.py
+
+ - Use Pip to install virtualenv and [virtualenvwrapper](https://virtualenvwrapper.readthedocs.org):
+
+ sudo pip install --upgrade virtualenv virtualenvwrapper
+
+ - Configure virtualenvwrapper and create a virtualenv for Bridgedb:
+
+ WORKON_HOME=${HOME}/.virtualenvs
+ export WORKON_HOME
+ mkdir -p $WORKON_HOME
+ source $(which virtualenvwrapper.sh)
+ git clone https://git.torproject.org/bridgedb.git && cd bridgedb
+ mkvirtualenv -a $PWD -r requirements.txt --unzip-setuptools \
+ --setuptools bridgedb
+
+ From now on, to use BridgeDB's virtualenv, just do ```$ workon bridgedb```
+ (after sourcing virtualenvwrapper.sh, as before). To exit the virtualenv
+ without exiting the shell, do ```$ deactivate```.
+
+ - To run unit tests:
+
+ python setup.py test
+
+ - To install BridgeDB:
+
+ python setup.py install
+
+
+### Enabling additional features:
+
+#### Translations
+ - To extract all strings from BridgeDB's source:
+
+ python setup.py extract_messages
+
+ A .pot file will be created in ./i18n/templates/bridgedb.pot
+ - Initialise catalogs for each desired language:
+
+ python setup.py init_catalog -l LANG
+
+ where ```LANG``` is the 2 or 4 letter country-code, eg. 'es'.
+ - Edit strings in ./i18n/LANG/bridgedb.po, and then convert them to binary
+ format:
+
+ python setup.py compile_catalog
+
+ Don't forget to reinstall BridgeDB to update the templates!
+
+ python setup.py install
+
+ - To generate translation files, and then install them, do:
+
+ python setup.py trans && python setup.py install_data
+
+#### Enabling HTTPS
+Create a self-signed certificate with:
+
+ openssl req -x509 -new -nodes > cert
+
+Or, place an existing certificate in the path specified in bridgedb.conf by
+the ```HTTPS_CERT_FILE``` option, and a private key where ```HTTPS_KEY_FILE```
+points to. The defaults are 'cert' and 'privkey.pem', respectively.
+
+#### CAPTCHAs
+To enable Captchas on the webserver interface, set the options in
+bridgedb.conf:
+
+ RECAPTCHA_ENABLED
+ RECAPTCHA_PUB_KEY
+ RECAPTCHA_PRIV_KEY
+
+A [recaptcha.net](https://www.google.com/recaptcha) account is required.
+
+#### GnuPG email signing
+Add these two options to your bridgedb.conf:
+
+ EMAIL_GPG_SIGNING_ENABLED
+ EMAIL_GPG_SIGNING_KEY
+
+The former may be either True or False, and the latter must point to the
+ascii-armored private key file. The keyfile must not be passphrase protected.
+
+#### Preventing already-blocked bridges from being distributed
+Uncomment or add ```COUNTRY_BLOCK_FILE``` to your bridgedb.conf. This file
+should contain one bridge entry per line, in the format:
+
+ fingerprint <bridge fingerprint> country-code <country code>
+
+If the ```COUNTRY_BLOCK_FILE``` file is present, bridgedb will filter blocked
+bridges from the responses it gives to clients requesting bridges.
+
+#### Updating the SQL schema
+Make sure that SQLite3 is installed. (You should have installed it already
+during the setup and installation stage.) To update, do:
+
+ sqlite3 path/to/bridgedist.db.sqlite
+
+Enter the following commands at the ```sqlite>``` prompt:
+
+ CREATE TABLE BlockedBridges ( id INTEGER PRIMARY KEY NOT NULL, hex_key, blocking_country);
+ CREATE INDEX BlockedBridgesBlockingCountry on BlockedBridges(hex_key);
+ CREATE TABLE WarnedEmails ( email PRIMARY KEY NOT NULL, when_warned);
+ CREATE INDEX WarnedEmailsWasWarned on WarnedEmails ( email );
+ REPLACE INTO Config VALUES ( 'schema-version', 2 );
+
+
+## Running BridgeDB
+To run BridgeDB, simply make any necessary changes to bridgedb.conf, and do:
+
+ python -m TorBridgeDB -c bridgedb.conf
+
+When you have new lists of bridges, replace the old files and send the process
+a SIGHUP.
+
+Make sure that the files and directories referred to in bridgedb.conf
+exist. However, many of them, if not found, will be touched on disk so that
+attempts to read/write from/to them will not raise excessive errors.
+
+#### To extract bucket files of all unallocated bridges:
+Edit the configuration file value ```FILE_BUCKETS``` according to your
+needs. For example, the following is a possible configuration:
+
+ FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 }
+
+This configuration for buckets would result in 3 files being created for
+bridge distribution: name1-2010-07-17.brdgs, name2-2010-07-17.brdgs and
+foobar-2010-07-17.brdgs. The first file would contain 10 bridges from
+BridgeDB's 'unallocated' pool. The second file would contain 15 bridges from
+the same pool and the third one similarly 3 bridges. These files can then be
+handed out to trusted parties via mail or fed to other distribution mechanisms
+such as twitter.
+
+#### To use with HTTPS:
+Just connect to the appropriate port.
+
+#### To use with email:
+Any mail sent to the email port with a subject or a single line _exactly_
+equal to "get bridges" will get answered, assuming the domain is okay.
+
+### Support
+Send your questions to aagbsn at torproject.org.
More information about the tor-commits
mailing list