castor-tor/README.md

# CasTor :beaver:

Tor proxy with balanced Tor instances.

![Tor balance schema](docs/tor-balance.png)

## Requirements

- [docker](https://docs.docker.com/engine/install/)
- [docker-compose](https://docs.docker.com/compose/install/)

## Usage

### Quickstart

This command will start one Tor instance and HAProxy:

```bash
docker-compose up
```

By default the proxy will be a SOCKS5 proxy running on port **8080**.

### Start multiple Tor instances

Use the docker-compose scale option to set the number of Tor instance to start

For instance to start 5 Tor instances:

```bash
docker-compose up --scale tor=5
```

By default, 5 tor instances are started. This also can be tunned in [`docker-compose.yml`](docker-compose.yml) file by editing the `scale` parameter of tor service.

### Use HTTP CONNECT proxy

Tor also provides an HTTP CONNECT proxy; you can use it by setting the environment variable `PROXY_MODE` to "http". This can be done by editing the [`.env`](.env) file or dirrectly in the shell such as:

```bash
export PROXY_MODE="http"
```

### Run proxy on a different port

Proxy port can be set using the environement varaible `PROXY_PORT`. You can specify it in the [`.env`](.env) file or dirrectly in the shell such as:

```bash
export PROXY_PORT=8080
```

## Test the proxy

Once the application is started, you can test your proxy with `curl`:

```bash
# test without the proxy
$ curl https://ipinfo.io/ip
A.B.C.D     # => your current IP address

# test with the proxy (with the default proxy conf)
$ curl -x socks5://localhost:8080 https://ipinfo.io/ip
W.X.Y.Z     # => Tor exit node IP address
``` 

## How is it working ?

When you run the command `docker-compose up`, you start at least 3 services (more if you scaled up the number of Tor instances): **tor**, **conf-generator** and **haproxy**.

1. The first service started is **tor**, this service is running a Tor instance with a SOCKS5 proxy (and with a Tor HTTP Tunnel if you use the "http" mode).

2. The second service is **conf-generator**, this service runs a python script that does the following things:

   1. get all the IP address of the Tor instances within the docker network (using the Docker API)
   2. generate an HAProxy configuration file with the retrieved IPs and the proxy mode

3. The final service is an HAProxy load balancer using the configuration file generated by **conf-generator**.