hacking.md

Alkasir 2.0 overview and setup for developers

Introduction to the main components

The components are constructed from two main technological bases which are wither witten in Go or user facing javascript/html/browser extension.

A user runs two separate applications where one is a native binary client written in Go and the other is a (currently chrome only) browser extension, the client also has an internal web server which hosts the same content as the browser extension.

The server parts are also written in Go with the exception of a small administrative inteface wich is a Django application which currently more or less only is a way to view the central server database.

The most important components and repository tree locations

Go/Native binaries:

• cmd/alkasir-client - the end user client application.

• cmd/alkasir-gui - the end user client application with native platform extensions (an interactive tray/indicator-icon).

• cmd/alkasir-central - the main server software.

• cmd/alkasir-torpt-server - wrapper for tor pluggable transport server and regular socks5 proxy forwarder.

Generally, running one of these are not more complicated than using the standard go tool: go run cmd/alkasir-client/alkasir-client.go

Web browser stuff:

All JavaScript+React/CoffeeScript/HTML/CSS(LESS) code is compiled to two slightly different targets, one is an chrome browser extension and the other is packaged into alkasir-client and alaksir-gui. Except for some browser extension specific code the JavaScript code base is almost completely the same for both variations.

All browser targeted source is located in browser/script and browser/style.

The result of the scripts are build using the two webpack configurations webpack.config.js and webpack.chrome.config.js which are built into pkg/generated and browser/chrome-ext/src/javascripts

Development environment requirements

Required tooling

• Go 1.5.3 (1.5.0 will cause hanging in the native gui builds due to a runtime stack traversal issue between Go and C)

• (semi optional) A native C/objC compiler

The C compiler is required to build alkasir-gui, the native GUI version of alkasir-client.

For OSX Apples own xcode toolchain is used, in Windows mingw is used and in linux/debian/ubuntu regular GCC is used.

• Java

Java is required to run the database migrations which uses liquibase.

• go-bindata - bakes javascript/html resources into the two client binary variations.

After Go is installed, go-bindata can be installed using the go get command which comes with the go distribution.

go get -u github.com/jteeuwen/go-bindata/...

• nodejs - Support all js/html/css front end building stuff.

• webpack - Builds and bundles all js/html/css.

Webpack can be installed using npm which is included with the nodejs installer.

npm install -g webpack

Required support services for alkasir-central

The following services are reqired to be available

• PostgreSQL 9.4
• Redis 3

Quickest ways to get a development environment up and running

If you are on Linux which supports docker the recommended way to get up and running is to install the required tooling mentioned above and then use docker compose to get the required support services up and running.

To start PostgreSQL and Redis using docker-compose, just do this:

cd central-db
docker-compose up -d

For OSX and Windows a Vagrant Vagrantfile is provided and the recommended quick way to get started.

Vagrant will automatically configure a virtual machine with all tooling and docker/docker-compose and start all support services at once.

After setting up Vagrant you should be able to get started by just issuing this command:

vagrant up

Sample session setting things up from scratch and starting it all using vagrant.

Issue the vagrant up command:

vagrant up

Enter the vagrant virtual machine:

vagrant ssh

Fix some file permissions

sudo chown vagrant /home/vagrant/src

Prepare the required services:

(. provision/docker-compose-build.sh)

...and...

(. provision/docker-compose-up.sh)

Sample session setting things for local development on a ubuntu/debuan system

currently, this procedure requires a fairly clean ubuntu setup, some global profile environment variables will be modified when go is installed.

Check out the source code

git clone git@github.com:alkasir/alkasir.git ${HOME}/src/github.com/alkasir/alkasir

Enter the workspace:

cd ${HOME}/src/github.com/alkasir/alkasir

Install all requirements (nodejs,docker,go...):

NOTE: This will install/modify some things at the system level, look what all.sh does if you want to understand what is required.

(./provision/all.sh)

Some environment variables has been set up by the provisioning script, log in and out again to refresh the environment.

When an developent environment is up, start the parts.

This section continues from one of the previous scenarios.

Enter the workspace:

cd ${HOME}/src/github.com/alkasir/alkasir

build binaries

go install ../alkasir/cmd/...

Install node dependencies

make deps
npm install -g webpack  # or sudo npm install -g webpack

Build and package the browser parts of the code:

make browser chrome

Package the browser dependcies for the client builds:

make bindata

Run the tests to verify that everything seems to work:

make test-all

Start alkasir-client. The client should start and keep running, possibly spewing out some errors about not being able to reach the central server (we havent started that one yet)

go run cmd/alkasir-client/alkasir-client.go -authKey 0123456789ABCDEF -centralAddr 'http://localhost:8080/' -bindAddr :8899 -v 19 -logcolor -logtostderr

start a new terminal and navigate to the workspacce:

When using vagrant:

vagrant ssh

When NOT using vagrant: sh cd $GOPATH/src/github.com/alkasir/alkasir

Start the support services:

(cd central-db && sudo docker-compose up -d)

Wait a few seconds and run the database migrations:

(cd central-db && sudo ./liquibase update)

Start alkasir-central:

go run cmd/alkasir-central/alkasir-central.go -v 19 -logcolor -logtostderr

After the first BGPDump refresh has finished (~1-5minutes) the server will say it's up and the the client should stop logging that it cannot connect connect to the server.

Now everything should be up and running and the logs should be displaying something like this:

The development version chrome extension that was built previously can now be added to chrome by enabling the developer mode in the chrome extensions dialog and navigating and adding the browser/chrome-ext/src folder contained inside this repository.

The extension options dialog should open, enter the following item in the browserkey field:

0123456789ABCDEF::8899

The alkasir chrome icon should now be lit which means that the client and browser are connected.