Eucalyptus Management Console
The Eucalyptus Management Console is a web-based interface to a local Eucalyptus cloud and/or AWS services.
AWS Services supported
- EC2
- Auto Scaling
- CloudWatch
- S3
- IAM
Issue Tracking
For bug reports, improvement request and general project planning, we use Jira: https://eucalyptus.atlassian.net/
To obtain the latest development source code for the eucalyptus management console, visit https://github.com/eucalyptus/eucaconsole. Pull requests are welcome and appreciated. By submitting code to the eucalyptus management console, you agree that code will be licensed under the 2-clause BSD license. A copy of this license is included in the COPYING file that accompanies the source code.
Development environment setup
Prerequisites
Prior to installing Pyramid and its dependencies, you may need to install the following libraries...
- openssl (required by M2Crypto)
- libxml2, libxslt (required by lxml)
- gcc, python development headers, swig (required to install Python libraries)
Ubuntu:
apt-get install openssl build-essential python-dev swig memcached libmemcached-dev libxml2-dev libxslt-dev
Fedora:
dnf install openssl-devel python-devel swig memcached libmemcached-devel libxml2-devel libxslt-devel; dnf groupinstall 'Development tools'
OS X:
Install homebrew, then run
brew install libevent openssl swig libmagic memcached libmemcached libxml2 libxslt
Pyramid Setup
Run python setup.py develop to set up the development environment. This only needs to be run once or when the "requires" package versions in setup.py are modified.
Note: It is strongly recommended to set up the development environment in a virtualenv.
If setup.py fails with an M2Crypto error and you're on a yum-based system (Fedora, CentOS, RHEL), download the M2Crypto package at https://pypi.python.org/pypi/M2Crypto and install via fedora_setup.sh install
Sass/Compass Setup
The CSS files are pre-processed using Sass, so you'll need to set up a Sass-to-CSS watcher to output CSS.
To set up Compass as the file watcher...
sudo gem install compass cd eucaconsole/static compass watch .
Once you have installed compass, there's a handy shortcut to enable the watcher. From the repo root...
make watch
Note that as of Foundation 5.5, Sass 3.4 and Compass 1.0 or later are required. Older versions will not work. To install the proper versions of Sass and Compass, run the following commands at the root of this repo...
sudo gem install bundler bundle install
See http://bundler.io/bundle_install.html for more info about Bundler and using a Gemfile
Running the management console
To run the server, you will need to specify the path to the config file (console.ini). Copy the default ini file to the application root. At the repo root...
cp conf/console.default.ini ./console.ini
The default settings assume an HTTPS/SSL environment. To disable HTTPS/SSL, set session.secure to false in console.ini
session.secure = false
The session keys are written to a file specified in console.ini. You may need to change the session.keyini setting if you don't have write access to the default location, or you may comment out the following line to have the session keys generated at the repo root.
session.keyini = /etc/eucaconsole/session-keys.ini
Run the server with
./launcher.sh
launcher.sh is provided as an alias for pserve console.ini --reload
Compilation Issues on OS X
On OS X (Yosemite and El Capitan), you may encounter issues installing M2Crypto
There is a known bug in the M2Crypto bindings and swig versions greater than 3.0.4. Using Homebrew you may install swig 3.0.4...
brew uninstall swig brew install homebrew/versions/swig304 python setup.py develop ./launcher.sh
If there are issues with M2Crypto locating the OpenSSL libraries (which could happen after an XCode update), reinstall the XCode Command Line Tools via xcode-select --install
Running the server in development/debug mode
The launcher.sh script runs the application with gunicorn and eventlet, closely matching the production deployment setup.
To have Pyramid automatically detect modifications to templates and views,
- Change the reload_templates setting to true in console.ini: pyramid.reload_templates = true
- Run the server with the --reload flag: pserve console.ini --reload
The --reload flag instructs Pyramid to automatically watch for changes in the view callables.
Note: Waitress may work better than gunicorn with the --reload flag. To install Waitress, run pip install -e .[dev] (this will also install the Pyramid Debug Toolbar).
To switch from gunicorn to Waitress for development, change the server:main section in your console.ini to this:
[server:main] use = egg:waitress#main host = 0.0.0.0 port = 8888
The Pyramid Debug Toolbar can be enabled by adding pyramid_debugtoolbar to the app:main section of console.ini
[app:main] # ... pyramid.includes = pyramid_beaker pyramid_chameleon pyramid_debugtoolbar pyramid_layout
You may also find it useful to set the logging level to DEBUG in the console.ini config file...
[logger_root] # ... handlers = logfile, screen_debug
The management console assumes an SSL setup. To disable SSL for development purposes, set session.secure = false in the config file (console.ini)
Running the server in production mode
A production deployment assumes an SSL setup, requiring nginx. To configure nginx...
- Copy the nginx.conf file at conf/nginx.conf to your system's nginx.conf location
- Location is usually /etc/nginx/nginx.conf on Linux and /usr/local/etc/nginx/nginx.conf on OS X
- Configure SSL (specify paths to certificate and key files)
- Visit the site via an HTTPS url (e.g. https://localhost)
Running the tests
The unit tests are based on Python's standard unittest library.
To run all tests, run the following at the repo root:
python setup.py test
To run the tests with nose and report test coverage:
python setup.py nosetests --with-coverage
Note that you will need to pip install nose, coverage, nose-cov to use nose with coverage
To run a single test (this is not obvious with nose integrated with setup.py):
python setup.py nosetests --tests tests.somepkg.somemodule
Configuring i18n
The translation strings are marked in templates and in python scripts as decribed at http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/i18n.html#i18n-chapter
The translations require Babel and lingua, which can be install via pip install -e .[i18n]
To generate the translation files, run 'make translations' at the repo root.
To contribute translations, follow the instructions at https://github.com/eucalyptus/eucaconsole/wiki/Contributing-Translations
Technology Stack
Primary Components
- Pyramid
- Boto
- Zurb Foundation
- AngularJS
Secondary Components
- Beaker and pyramid_beaker (server-side cache/sessions)
- Chameleon (server-side templates)
- pyramid_layout (layout/themes for Pyramid)
- Waitress or gunicorn (WSGI server)
- WTForms (server-side forms and validation)
Guitester - selenium testing framework for eucaconsole
- Location: tests/selenium/guiops
- Requirements: python selenium module, an instance of selenium webdriver
- Setup and intro: https://github.com/eucalyptus/eucaconsole/wiki/Guitester
- Contributing: https://github.com/eucalyptus/eucaconsole/wiki/Contributing-to-Guitester
Grunt - JavaScript Task Manager
Grunt Setup
- At home directory ./eucaconsole
- Install npm if missing:
yum install -y npm
- Run
npm install
to install npm packages listed in the file package.json
npm install -g grunt-cli
to allow grunt cli to run
Grunt Task File
Gruntfile.js
Grunt Commands
- Default:
grunt
- Bowercopy:
grunt bowercopy
- Karma:
grunt karma
- Karma(Single run):
grunt karma:ci
Bower - JavaScript Package Manager
Bower Setup
- See Grunt Setup above
Bower Configuration File
- List the versions of the JS packages
bower.json
- ex.
"dependencies": { "angular": "1.2.26", "angular-sanitize": "1.2.26", "angular-mocks": "1.2.26", "jquery": "2.0.3", "jasmine": "2.0.3", "jasmine-jquery": "2.0.5" }
Bowercopy Configuration File
- List the destination for the files to be copied after running bower
Gruntfile.js
- ex.
bowercopy: { angular: { options: { destPrefix: 'eucaconsole/static/js/thirdparty/angular' }, files: { 'angular.min.js': 'angular/angular.min.js', 'angular-sanitize.min.js': 'angular-sanitize/angular-sanitize.min.js', 'angular-mocks.js': 'angular-mocks/angular-mocks.js' } },
Run Bowercopy
- Runs bower to download the JS packages and move the files in place
grunt bowercopy
Jasmine & Karma - JavaScript Unittest & test runner
Jasmine & Karma Setup
- See Grunt Setup above
Karma Configuration File
karma.conf.js
- ex.
files: [ 'templates/panels/*.pt', 'static/js/thirdparty/modernizr/custom.modernizr.js', 'static/js/thirdparty/jquery/jquery.min.js', 'static/js/thirdparty/angular/angular.min.js', 'static/js/thirdparty/angular/angular-sanitize.min.js', 'static/js/thirdparty/angular/angular-mocks.js', 'static/js/thirdparty/jquery/jquery.generateFile.js', 'static/js/widgets/notify.js', 'static/js/pages/eucaconsole_utils.js', 'static/js/thirdparty/jquery/chosen.jquery.min.js', 'static/js/thirdparty/jasmine/jasmine-jquery.js', 'static/js/pages/custom_filters.js', 'static/js/widgets/tag_editor.js', 'static/js/widgets/securitygroup_rules.js', 'static/js/pages/keypair.js', 'static/js/jasmine-spec/SpecHelper.js', 'static/js/jasmine-spec/spec_security_group_rules.js', 'static/js/jasmine-spec/spec_keypair.js', 'static/js/jasmine-spec/spec_tag_editor.js' ],
Jasmine Spec File Location
./eucaconsole/static/js/jasmine-spec/
Run Karma
grunt karma
Run Karma (Single Run)
grunt karma:ci
See the wiki page https://github.com/eucalyptus/eucaconsole/wiki/JavaScript-UnitTest-Submit-Guideline for more details.