#CalCentral
- Bundler
- Git
- JDBC Oracle driver
- JRuby 1.7.x
- PostgreSQL
- Rails 3.2.x
- Rubygems
- Rvm - Ruby version managers
- Install postgres
brew update
brew install postgresql
initdb /usr/local/var/postgres
-
For Mountain Lion & Mavericks users ONLY: Fix Postgres paths as detailed here.
-
For Mountain Lion & Mavericks users ONLY: If you can connect to Postgres via psql, but not via JDBC (you see "Connection refused" errors in the CalCentral app log), then edit /usr/local/var/postgres/pg_hba.conf and make sure you have these lines:
host all all 127.0.0.1/32 md5
host all all samehost md5
-
For Mountain Lion & Mavericks users ONLY: Install XQuartz and make sure that /opt/X11/bin is on your PATH.
-
Start postgres, add the user and create the necessary databases. (If your PostgreSQL server is managed externally, you'll probably need to create a schema that matches the database username. See CLC-893 for details.)
pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
psql postgres
create database calcentral_development;
create user calcentral_development with password 'secret';
grant all privileges on database calcentral_development to calcentral_development;
create database calcentral;
create user calcentral with password 'secret';
grant all privileges on database calcentral to calcentral;
create database calcentral_test;
create user calcentral_test with password 'secret';
grant all privileges on database calcentral_test to calcentral_test;
- Fork this repository, then:
git clone [email protected]:[your_github_acct]/calcentral.git
- Go inside the
calcentral
repository
cd calcentral
# Answer "yes" if it asks you to trust a new .rvmrc file.
- Install jruby
rvm get head
rvm install jruby-1.7.3
cd ..
cd calcentral
# Answer "yes" again if it asks you to trust a new .rvmrc file.
- (Optional for development) Make JRuby faster & enable C extensions by running this or put in your .bashrc:
export JRUBY_OPTS="-Xcext.enabled=true -J-d32 -J-client -X-C"
- WARNING: Do not switch between 32-bit and 64-bit JRuby after your gemset has been initialized (your bundle library will have serious issues). If you do need to change settings, make sure to reinitialize your gemset:
rvm gemset delete calcentral
- (set your JRUBY_OPTS)
bundle install
- Download the appropriate gems with Bundler
bundle install
- Set up a local settings directory:
mkdir ~/.calcentral_config
Default settings are loaded from your source code in config/settings.yml
and config/settings/ENVIRONMENT_NAME.yml
. For example, the configuration used when running tests with RAILS_ENV=test
is determined by the combination of config/settings/test.yml
and config/settings.yml
.
Because we don't store passwords and other sensitive data in source code, any RAILS_ENV other than test
requires overriding some default settings.
Do this by creating ENVIRONMENT.local.yml
files in your ~/.calcentral_config
directory. For example, your ~.calcentral_config/development.local.yml
file may include access tokens and URLs for a locally running Canvas server.
You can also create Ruby configuration files like "settings.local.rb" and "development.local.rb" to amend the standard config/environments/*.rb
files.
- Install JDBC driver (for Oracle connection)
- Download ojdbc6.jar
- Copy ojdbc6.jar to your project's ./lib folder```
- Initialize PostgreSQL database tables
rake db:schema:load db:seed
- Make yourself powerful
rake superuser:create UID={your numeric CalNet UID}
- Start the server
rails s
- Access your development server at localhost:3000. Do not use 127.0.0.1:3000, as you will not be able to grant access to bApps.
In order to have live updates you'll need to perform the following steps:
-
Install and run memcached
-
Add the following lines to development.local.yml
messaging:
enabled: true
cache:
store: "memcached"
- Start the server with TorqueBox
Back-end (rspec) tests live in spec/*.
To run the tests from the command line:
rspec
To run the tests faster, use spork, which is a little server that keeps the Rails app initialized while you change code and run multiple tests against it. Command line:
spork (...wait a minute for startup...)
rspec --drb spec/lib/my_spec.rb
You can even run Spork right inside IntelliJ RubyMine or IDEA.
Front-end jasmine tests live in spec/javascripts/calcentral/*.
To run the tests headless on firefox run rake jasmine:ci
.
To view results of front-end tests, run rake jasmine
in a separate terminal,
then visit localhost:8888.
Some features of CalCentral are accessible only to users with particular roles, such as "student." These features may be invisible when logged in as yourself. In particular:
- My Academics will only appear in the navigation if logged in as a student. However, the "Oski Bear" test student does not fake data loaded on dev and QA. To test My Academics, log in as user test-212385 or test-212381 (ask a developer for the passwords to these if you need them). Once logged in as a test student, append "/academics" to the URL to access My Academics (this will change when CLC-1755 is resolved).
- Make sure you have a separate production database. In psql:
create database calcentral_production;
grant all privileges on database calcentral_production to calcentral_development;
- In calcentral_config/production.local.yml, you'll need the following entries:
secret_token: "Some random 30-char string"
postgres: [credentials for your separate production db (copy/modify from development.local.yml)]
campusdb: [copy from main config/settings.yml, modify if needed]
google_proxy: and canvas_proxy: [copy from development.local.yml]
application:
serve_static_assets: true
- Populate the production db by invoking your production settings:
RAILS_ENV="production" rake db:schema:load db:seed
- Precompile the assets: (more info)
bundle exec rake assets:precompile
- Start the server in production mode
rails s -e production
-
If you're not able to connect to Google or Canvas, export the data in the oauth2 from your development db and import them into the same table in your production db.
-
After testing, remove the static assets and generated pages
bundle exec rake assets:clean
If you're getting something like the following error:
Java::JavaLang::OutOfMemoryError: Java heap space
Make sure that you're memory settings for Java are high enough.
Add the following to your JRUBY_OPTS
:
JRUBY_OPTS="-J-Xmx900m -J-XX:MaxPermSize=500m"
In production we use TorqueBox as this provides us with messaging, scheduling, caching, and daemons.
- Deploy into TorqueBox (only needs to happen once in a while)
bundle exec torquebox deploy .
- Start the server
bundle exec torquebox run -p=3000
Make sure you are on the Berkeley network or connected through preconfigured VPN for the Oracle connection. If you use VPN, use group #1 (1-Campus_VPN)
Basic authentication will enable you to log in without using CAS. This is necessary when your application can't be CAS authenticated or when you're testing mobile browsers. Note only enable this in fake mode or in development.
- Add the following setting to your
environment.yml
file (e.g.development.yml
)
developer_auth:
enabled: false
password: topsecret!
-
(re)start the server for the changes to take effect.
-
Click on the footer (Berkeley logo) when you load the page.
-
You should be seeing the Basic Auth screen. As the login you should use the UID (e.g. 61889, oski) and then password from the settings file.
To help another user debug an issue, you can "become" them on CalCentral. To assume the identity of another user, you must:
- Currently be logged in as a designated superuser
- Be accessing a machine/server which the other user has previously logged into (e.g. from localhost, you can't act as a random student, since that student has probably never logged in at your terminal)
- Have enabled act_as in settings.yml (features:)
Access the URL:
https://[hostname]/act_as?uid=123456
where 123456 is the UID of the user to emulate.
n.b.: The Act As feature will only reveal data from data sources we control, e.g. Canvas. Google data will be completely suppressed, EXCEPT for test users. The following user uids have been configured as test users.
- 11002820 - "Tammi Chang"
- 61889 - "Oski Bear"
- All IDs listed on the "Universal Calnet Test IDs" page
To become yourself again, access
https://[hostname]/stop_act_as
Logging behavior and destination can be controlled from the command line or shell scripts via env variables:
LOGGER_STDOUT=false
- Only log to the default filesLOGGER_STDOUT=true
- Log to standard output as well as the default filesLOGGER_STDOUT=only
- Only log to standard outputLOGGER_LEVEL=DEBUG
- Set logging level; acceptable values are 'FATAL', 'ERROR', 'WARN', 'INFO', and 'DEBUG'
- On Mac OS X, to get RubyMine to pick up the necessary environment variables, open a new shell, set the environment variables, and:
/Applications/RubyMine.app/Contents/MacOS/rubymine &
-
If you want to explore the Oracle database on Mac OS X, use SQL Developer
-
We support source maps for SASS in development mode. There is a great blog post explaining how to set it up and use it.
Make sure your testext.local.yml file has real connections to real external services that are fakeable (Canvas, Google, etc). Now do:
rake vcr:record
rake vcr:prettify
- vcr:record can also take a SPEC=".../my_favorite_spec.rb" to help limit the recordings.
- vcr:prettify can also take a REGEX_FILTER="my_raw_recording.json" to target a specific raw file.
You can now find the prettified files in fixtures/pretty_vcr_recordings. You can edit these files to put in tokens that will be substituted on server startup. See config/initializers/timeshift.rb for the dictionary of substitutions. Edit the debug_json property of each response, and timeshift.rb will automatically convert debug_json to the format actually used by VCR.
To view other rake task for the project: rake -T
rake spec:xml
- Runs rake spec, but pipes the output to xml using the rspec_junit_formatter gem, for JUnit compatible test result reportsrake vcr:record
- Refresh vcr recordings and reformats the fixtures with formatted JSON output. Will also parse the reponse body's string into json output for legibility.rake vcr:list
- List the available recordings captured in the fixtures.
A few rake tasks to help monitor statistics and more:
-
rake memcached:clear_stats
- Reset memcached stats from all cluster nodes -
rake memcached:empty
- Invalidate all memcached keys from all cluster nodes -
rake memcached:get_stats
- Fetch memcached stats from all cluster nodes -
Generally, if you
rake memcached:empty
( WARNING: do not run on the production cluster unless you know what you're doing), you should follow with anrake memcached:clear_stats
. -
All three task take the optional param of "hosts." So, if say you weren't running these tasks on the cluster layers themselves, or only wanted to tinker with a certain subset of clusters:
rake memcached:get_stats hosts="localhost:11212,localhost:11213,localhost:11214"
To selectively enable/disable a feature, add a property to the "features" section of settings.yml, e.g.:
features:
wizbang: false
neato: true
After server restart, these properties will appear in each users' status feed. You can now use ng:show
in Angular to wrap the feature, e.g.:
<div data-ng-show="user.profile.features.neato">
Some neato feature...
</div>
or, depending on the feature, it may make more sense to disable it in erb (so that Angular controllers are never invoked at all):
<% if Settings.features.neato %>
<%= render 'templates/widgets/notifications' %>
<% end %>
seeds.rb is intended for use only on developer machines, so they have a semi-realistic copy of production lists of superusers, links, etc. ./db/developer-seed-data.sql has the data used by rake db:seed. Occasionally we'll want to update it from production. To do that, log into a prod node and do:
pg_dump calcentral --inserts --clean -f developer-seed-data.sql -t link_categories \
-t link_categories_link_sections -t link_sections -t link_sections_links -t links \
-t links_user_roles -t user_auths -t user_roles -t user_whitelists \
-h postgres-hostname -p postgres-port-number -U calcentral
Take that file, developer-seed-data.sql, and edit it to remove the "REVOKE" and "GRANT" statements at the bottom, since those will conflict with local permissions. Copy that file into your source tree and get it merged into master.