Skip to content

1 Install, Configure and Run AWE

Jump to bottom Edit New page
Travis Harrison edited this page Jul 14, 2016 · 52 revisions

The recommended installation method for AWE is with Docker (Section 1), but you can also run AWE without Docker (Section 0).

0. Install AWE (without Docker)

Prerequisite software

sudo apt-get -y install mongodb-server bzr make gcc mercurial git

Note that mongodb-server is only needed for the AWE server.

Golang

apt-get install golang

or

cd ~
mkdir -p ~/gopath
hg clone -u release https://code.google.com/p/go
cd ~/go/src ./all.bash
export GOPATH=/home/<user>/gopath
export PATH=$PATH:/home/<user>/go/bin:/home/<user>/gopath/bin
export PATH=$PATH:${GOPATH}/src/github.com/MG-RAST/AWE/utils

Compile AWE

go get github.com/MG-RAST/AWE/...

or, if you want to include the git commit number in the binary

export GITHASH=$(git -C ${GOPATH}/src/github.com/MG-RAST/AWE rev-parse HEAD)
echo ${GITHASH}
go get -ldflags "-X github.com/MG-RAST/AWE/lib/conf.GIT_COMMIT_HASH ${GITHASH}" github.com/MG-RAST/AWE/...

Both awe-server and awe-client binaries are compiled at this point. Test with:

${GOPATH}/bin/awe-client --help
${GOPATH}/bin/awe-client --show_git_commit_hash

Continue with Section 3.

1. Install Docker

If you prefer a manual installation please use our Dockerfiles for instructions. Note that these Dockerfiles create statically compiled binaries that you can easily extract. (Also note that the AWE worker binary is named awe-client.)

To install Docker, e.g. using ubuntu:

sudo apt-get update && sudo apt-get -y install docker.io

Optional:
Docker requires quite some disk space, you can set these environment variables to tell docker to use ephemeral disk space in the docker config file:

# /etc/default/docker.io
export TMPDIR=/media/ephemeral/tmp/
export DOCKER_OPTS="-g=/media/ephemeral/docker"

Create tmp dir:

mkdir /media/ephemeral/tmp/

And restart docker:

sudo service docker.io restart

2. Get AWE Docker image / binaries

Download AWE image from DockerHub:

sudo docker pull mgrast/awe
sudo docker pull mgrast/mongodb # only needed for AWE server

Optional: Build image from Dockerfile

You can also build the image on you own from Dockerfiles. The Dockerfiles for AWE worker and AWE server can be found here:

AWE worker and AWE server: https://github.com/MG-RAST/AWE/tree/master/dockerfiles/awe

MongoDB: https://github.com/MG-RAST/AWE/tree/master/dockerfiles/mongodb

Example to build image:

export TAG=`date +"%Y%m%d.%H%M"`
docker build --force-rm --no-cache --rm -t mgrast/awe:$TAG https://raw.githubusercontent.com/MG-RAST/AWE/master/dockerfiles/awe/Dockerfile

Optional: Binaries

If you need binaries, either download binaries for the latest tagged version from github https://github.com/MG-RAST/AWE/releases/latest), or extract the very latest version from the Dockerimage:

docker create --name awe mgrast/awe
docker cp awe:/gopath/bin/awe-server .
docker cp awe:/gopath/bin/awe-client .
docker rm awe

3. Run AWE

3.1 AWE worker

This example assumes you run the AWE worker in a container. If you do not use Docker, ignore the line that starts with "docker run". The AWE worker will store files on the host in the DATADIR directory. Do not forget to specifiy the AWE server url. Here the AWE worker is completely configured by command line parameters and does not need a configuration file. This command will run AWE worker as a demonized container:

export DATADIR=/media/ephemeral/awe-client/
mkdir -p ${DATADIR}
/usr/bin/docker run -d --name awe-client -v /var/run/docker.sock:/var/run/docker.sock -v ${DATADIR}:${DATADIR}  mgrast/awe \
/gopath/bin/awe-client --data=${DATADIR}/data --logs=${DATADIR}/logs --workpath=${DATADIR}/work  --serverurl=<awe_server> --group=docker --supported_apps=*

To run in foreground replace "-d" with "-t -i --rm"

/usr/bin/docker run -t -i --rm --name ...

Verify the container is running:

sudo docker ps

3.2 AWE server

The AWE server requires a Mongodb instance. On ubuntu the mongo server should already be running once installed. With Docker you can start an instance like this:

export DATADIR="/media/ephemeral/awe-server/"
/usr/bin/docker run --rm --name awe-server-mongodb -v ${DATADIR}mongodb/:/data/db --expose=27017 mgrast/mongodb /usr/bin/mongod

You can configure the AWE server with a configuration file and via command line options. You can start with out template config file for the AWE server and then make changes:

/usr/bin/curl -o ${DATADIR}awe-server.cfg https://raw.githubusercontent.com/MG-RAST/AWE/master/templates/awes.cfg.template

This is the command to start the AWE server. If you do not use Docker, ignore the line that starts with "docker run":

export TITLE="my server"
export PUBLIC_IPV4=<PUBLIC IP>
docker run --rm --name awe-server -p 80:80 -p 8001:8001 -v ${DATADIR}awe-server.cfg:/awe-config/awe-server.cfg -v ${DATADIR}data/:/mnt/data/awe/ --link=awe-server-mongodb:mongodb mgrast/awe \
/gopath/bin/awe-server --hosts=mongodb --debuglevel=1 --conf=/awe-config/awe-server.cfg --use_app_defs=yes --site-port=80 --api-port=8001 --api-url=http://${PUBLIC_IPV4}:8001 --site-url=http://${PUBLIC_IPV4}:80 --title="${TITLE}"

Comments:
port 80: AWE server monitor
port 8001: AWE server API
"-v" mounts host to container directories
"--link" connects AWE server and mongodb

If you run awe server binary directly, note that you will need the "site" sub-directory in the AWE git repository (https://github.com/MG-RAST/AWE/tree/master/site) to use the AWE monitor.

awe-server configuration file template:

https://raw.githubusercontent.com/MG-RAST/AWE/master/templates/awes.cfg.template

Config file specification is available at, or use "awe-server --help"

https://github.com/MG-RAST/AWE/wiki/AWE-config-file-manual

AWE options: --recover: if this flag is set, awe-server will automatically recover the queue before last time it was shut down. --debug: set the debug log level from 0 to 3, by default debug log is not printed --dev: print simple queue statistics to stdout every 10 seconds

Check logs:

  • Log location: <path/to/awe/logs> configured in config file.
  • Log types: access.log, error.log, debug.log, event.log, perf.log

4. AWE Web Monitor

TODO: this requires update, this is partly automatic now.

4.1 Configure the web interfaces and monitor jobs with web monitor

WARNING: Soon deprecated. The default configuration will be automatically set up and does only require the port to be defined on which the AWE Monitor listens.

  1. Configure the web site path in awe.cfg for awe-server

e.g.

[Directories]
Site=/Users/wtang/gopath/src/github.com/MG-RAST/AWE/site   #where the js are
[Ports]
site-port=8080    #what port you want to use as the web interface
  1. Create a config file (config.js) under server machine $GOPATH/src/MG-RAST/AWE/site/js

you can rename config.js.tt to config.js, and edit the content of config.js:

e.g.

var RetinaConfig = {
    "awe_ip": "http://140.221.84.148:8000",
    "workflow_ip": "http://140.221.84.148:8000/awf"
}
  • 140.221.84.148:8000 is the external server API URL.
  • After above configuration, your web interface can be accessed by: http://140.221.84.148:8080/
  • You can use localhost as the ip address, but then you can only access the web interface from the local machine by http://localhost:8080

5 Shock

For installation and configuration of Shock, please refer to https://github.com/MG-RAST/Shock

Notes

To update vendorized code in AWE

cd AWE
go get -v github.com/mjibson/party
party -d vendor -c -u

User-data file for VMs

Can be used to conveniently start multiple AWE worker instance in the cloud. Requires recent Ubuntu image.

#!/bin/bash
set -e
set -x

# configuration
export AWE_SERVER="<server-address:port>" # include http://
export GROUP="docker"
export EPHEMERAL="/mnt"
# or export EPHERMERAL="/media/ephemeral/"
export DATADIR=${EPHEMERAL}/awe-client/
export WORKERNAME=""

# Detect IP and set worker name
# export WORKERNAME=`ifconfig eth0 | grep 'inet addr' | cut -d ":" -f 2 |cut -d " " -f1`

# install docker
apt-get update && sudo apt-get -y install docker.io
sleep 2

# move docker location to EPHEMERAL
# the default location for Docker to store images may not have enough space:
mkdir -p ${EPHEMERAL}/tmp/
echo 'export TMPDIR='${EPHEMERAL}'/tmp/' >> /etc/default/docker.io
echo 'export DOCKER_OPTS="-g='${EPHEMERAL}'/docker"' >> /etc/default/docker.io
/usr/sbin/service docker.io restart
sleep 4

# Create directory for awe-worker data:
mkdir -p ${DATADIR}

# Run awe-worker:
/usr/bin/docker run -d --name awe-client -v /var/run/docker.sock:/var/run/docker.sock -v ${DATADIR}:${DATADIR}  mgrast/awe /gopath/bin/awe-client --data=${DATADIR}/data --logs=${DATADIR}/logs --workpath=${DATADIR}/work  --serverurl=${AWE_SERVER} --group=${GROUP} --debuglevel=1 --auto_clean_dir=false --supported_apps=*

#Start awe-worker on reboots. This step is optional (better would be upstart or systemd unit), thus it is commented:
#echo "/usr/bin/docker run -d --name awe-client -v /var/run/docker.sock:/var/run/docker.sock -v ${DATADIR}:${DATADIR}  mgrast/awe /gopath/bin/awe-client --data=${DATADIR}/data --logs=${DATADIR}/logs --workpath=${DATADIR}/work  --serverurl=${AWE_SERVER} --name=${WORKERNAME}--group=${GROUP} --debuglevel=1 --auto_clean_dir=false --supported_apps=*" >> /etc/rc.local
Add a custom sidebar
Clone this wiki locally