uProxy is a browser extension that lets users share their internet connection.
uProxy is built using the following tools:
- Grunt to write the tasks that build uProxy
- Jasmine for testing
- Polymer for UI
- Travis for continuous integration
To manage dependencies we use:
- npm to install node modules that we use for our build process. (Specified in
- Bower to install libraries that we use in the UI
bower.json) including Polymer.
- Yarn. If you have npm, you can install with
npm install -g --production yarn.
- grunt-cli (once you've installed NPM, simply execute
yarn global add --prod grunt-cli)
First, to install required NPMs and configure the
build/ directory for TypeScript compilation, execute:
Then, to compile the TypeScript code and build uProxy and all of the demo apps, execute:
Having problems? To clean up from a partial, broken, or extremely out-dated build, try executing this command before repeating the above steps:
yarn run clean
Visual Studio Code supports TypeScript compilation, search, and refactoring out of the box - just point it at the directory containing your uProxy clone.
These are the steps to try uProxy in the Chrome browser.
- In Chrome, go to
chrome://extensions, make sure 'Developer mode' is enabled
- Click 'Load unpacked extension...' and select
- Click 'Load unpacked extension...' and select
You need both the uProxy Chrome App and the uProxy Extension.
You can use
grunt build_chrome from the root directory of the repository to re-compile just Chrome components.
These are the steps to try uProxy in the Firefox browser.
To run the add-on you need to have the Firefox add-on SDK installed. Instructions can be found here: https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Installation
- A quick way to get started is to download/extract the zip mentioned in "Prerequisites"
cfx runand Firefox should launch with the uProxy add-on installed
You can use
grunt build_firefox from the root directory of the repository to compile just Firefox comonents.
These can be found at
build/src/samples/. They are a mix of web sites, browser extensions (Chrome and Firefox), and Node.js apps.
To run web apps:
- start a webserver, e.g.
python -m SimpleHTTPServer
- open the relevant HTML file in your browser, e.g. http://localhost:8000/build/src/samples/simple-freedom-chat/main.html.
To run Chrome apps:
chrome://extensions, enable check Developer Mode, and load the unpacked extension from the relevant directory, e.g.
To run Firefox add-ons:
- install jpm via NPM, e.g.
yarn install jpm -g,
cdto the relevant directory, e.g.
build/src/samples/simple-socks-firefoxapp/, and execute
jpm run -b `which firefox`.
To run Node.js apps:
- Directly run
nodewith the entry point, e.g.
Note: until freedom-for-node supports core.rtcpeerconnection, this sample will not work
More on the demo apps themselves:
- simple-freedom-chat is a WebRTC-powered chat client, with both peers on the same page. This is the simplest possible demo
- copypaste-freedom-chat is the simplest possible, distributed,
src/peerconnectiondemo in which text boxes act as the signalling channel between two peers. Messages can be exchanged by email, IM, shared doc, etc.
- echo-server starts a TCP echo server on port 9998. Run
telnet 127.0.0.1 9998and then type some stuff to verify that echo server echoes what you send it. Press ctrl-D to have the echo server terminate the connection or press
quitto exit telnet.
- Simple SOCKS is the simplest possible, single-page, demo of the SOCKS proxy (
rtc-to-netdirectories). This command may be used to test the proxy:
curl -x socks5h://localhost:9999 www.example.com(
-hindicates that DNS requests are made through the proxy too)
- Zork is a distributed SOCKS proxy with a telnet-based signalling channel, intended for use with our Docker-based integration testing. Try connecting to Zork with
telnet localhost 9000.
- uProbe guess-timates your NAT type.
- copypaste-freedom-chat is just like copypaste-fredom-chat, except WebRTC traffic between the two peers is obfuscated.
Development and re-building uProxy
uProxy uses the Grunt build system for its build tasks. Here is a list of uProxy's Grunt commands:
build- Builds everything, making stuff in the
builddirectory (and runs tests).
build_chrome- Build Chrome app and extension
build_chrome_app- Build just Chrome app
build_chrome_ext- Build just Chrome extension
build_firefox- Build just Firefox
dist- Generates distribution files, including the Firefox xpi
clean- Cleans up
test- Run unit tests
integration_test- Run integration tests
everything- 'build', 'test' and then 'integration_test'
The easiest way to stay current is to pull changes, run
grunt build to build
your distribution, and re-run as you make changes to the files.
Before submitting any changes to the repository, make sure to run
to make sure it passes all unit tests. Failing tests are enough to immediately
reject submissions. :)
uProxy for Mobile
The development for mobile platforms uses the Cordova Chrome Apps (CCA) tool, also known as the Chrome Apps for Mobile Toolchain. You can find the platform-specific information below:
Layout of files
Configuration and setup files
Gruntfile.jsa file that specifies common tasks, e.g. how to build and package uProxy.
bower.jsonspecifies dependent libraries from Bower.
package.jsonspecifies dependent libraries from NPM.
.gitignorewhat git should ignore
.bowerrctells bower where to put files
third_party/tsd.jsonspecifies the typescript definitions to use
srcholds all source code; no compiled files
src/generic_uigeneric user interface code
src/generic_coregeneric uproxy core-functionality code
src/chrome/appcode specific to the chrome app
src/chrome/extensioncode specific to the chrome extension
src/firefoxcode specific to firefox
third_partyholds external libraries we depend on that are copied into this repository
node_modulesdynamically generated npm module dependencies
scrapstemporary holding for sharing scraps of code
Dynamically created directories (
grunt clean should remove them)
buildcreated by grunt tasks; holds the built code, but none of the code that was compiled.
build/distcreated by grunt tasks; holds final distribution versions
.gruntholds grunt cache stuff
.tscacheholds typescript cache stuff