Skip to content

1 Install, Configure and Run AWE

Jump to bottom Edit New page
Wolfgang Gerlach edited this page Jun 26, 2015 · 52 revisions

1. Install Docker

The recommended installation method for AWE is with Docker. Alternatively you can run the AWE binaries directly. 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:

docker build -t mgrast/awe:latest 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 .

3. Run AWE

3.1 AWE worker

This example assumes you run the AWE worker in a container. 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

Start Mongodb

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

Get AWE server configuration

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

Start AWE server

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>"
export GROUP="docker"
export EPHEMERAL="/mnt"
# or export EPHERMERAL="/media/ephemeral/"
export DATADIR=${EPHEMERAL}/awe-client/


# 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} --debug_level=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} --group=${GROUP} --debug_level=1 --auto_clean_dir=false --supported_apps=*" >> /etc/rc.local
Add a custom sidebar
Clone this wiki locally