Looking for the CalCentral web application? That code is maintained by Student Information Systems at https://github.com/sis-berkeley-edu/calcentral.
- Administrator privileges
- Bundler
- Git
- JDBC Oracle driver
- Java 8 SDK
- JRuby (version per .ruby-version)
- Node.js (version per .nvmrc)
- PostgreSQL
- Rubygems 2.7.10
- RVM - Ruby version managers
- xvfb - xvfb headless browser, included for Macs with XQuartz
-
Install Java 8 JDK (8u172): http://www.oracle.com/technetwork/java/javase/downloads/index.html
-
Install Postgres:
Note: To install Postgres, you must first install Homebrew.
Install Homebrew with the following command:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Run the following command in Terminal after installation:
brew --version
Then run the following:
brew update brew install postgresql
-
For Mountain Lion & Mavericks users ONLY: Fix Postgres paths.
-
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 users 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' createdb; grant all privileges on database calcentral_development to calcentral_development; alter database calcentral_development owner to calcentral_development; create database calcentral; create user calcentral with password 'secret' createdb; grant all privileges on database calcentral to calcentral; alter database calcentral owner to calcentral; create database calcentral_test; create user calcentral_test with password 'secret' createdb; grant all privileges on database calcentral_test to calcentral_test; alter database calcentral_test owner to calcentral_test; create database edodb_test; grant all privileges on database edodb_test to calcentral_test; alter database edodb_test owner to calcentral_test; \q
Note: At this point, exit out of Postgres. To do this, type "\q" and then press ENTER.
-
Fork this repository, then:
with ssh (note)
git clone [email protected]:[your GitHub Account]/calcentral.git # e.g. git clone [email protected]:christianv/calcentral.git
or via https - (note)
git clone https://github.com/[your Github Account]/calcentral.git # e.g. git clone https://github.com/christianv/calcentral.git
-
Go inside the
calcentral
repository:cd calcentral # Answer "yes" if it asks you to trust a new .rvmrc file.
-
Install JRuby (see .ruby-version for required version):
Note: To install JRuby, you must first install rvm.
rvm get head rvm install jruby-[put-version-here] cd .. cd calcentral # Answer "yes" again if it asks you to trust a new .rvmrc file. rvm list # Make sure that everything looks fine # If it mentions "broken", you'll need to reinstall
-
Make JRuby faster for local development by running this or put in your .bashrc:
export JRUBY_OPTS="--dev"
-
Configure Default JRuby and Gemset
cd ~ rvm use --default # This may output 'Unknown ruby string...', which can be ignored. rvm gemset use global
-
Download and install xvfb. On a Mac, you get xvfb by installing XQuartz.
-
Download the appropriate gems with Bundler:
Important: Make sure you have the JRuby-upgraded CalCentral codebase in your calcentral directory before running
bundle install
.rvm rubygems 2.7.10 --force gem --version # Should output '2.7.10' gem uninstall bundler --force -x gem install bundler --version="1.17.3" bundle install
-
Set up a local settings directory:
mkdir ~/.calcentral_config
Default settings are loaded from your source code in
config/settings.yml
andconfig/settings/ENVIRONMENT_NAME.yml
. For example, the configuration used when running tests withRAILS_ENV=test
is determined by the combination ofconfig/settings/test.yml
andconfig/settings.yml
. Because we don't store passwords and other sensitive data in source code, any RAILS_ENV other thantest
requires overriding some default settings. Do this by creatingENVIRONMENT.local.yml
files in your~/.calcentral_config
directory.development.local configs
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 standardconfig/environments/*.rb
files.Your
development.local
config must have:vue: localhost_base_url: 'http://localhost:8080'
-
Install JDBC driver (for Oracle connection)
- Download ojdbc7_g.jar
- Note: You do not have to open the file.
- Rename the file to
ojdbc7.jar
- Copy
ojdbc7.jar
to~/.rvm/rubies/jruby-9.2.13.0/lib/
-
Initialize PostgreSQL database tables:
bundle exec rake environment db:schema:load db:seed
-
Make yourself powerful:
bundle exec rake superuser:create UID=[your numeric CalNet UID] # e.g. rake superuser:create UID=61889
-
Install the front-end tools:
brew install node npm install nvm use
-
Start the front-end development server
# starts development server npm run serve-vue
Your browser will automatically load the Junction front-end on localhost:8080.
-
Start the server:
rails s
Access Rails server at localhost:3000.
Back-end (rspec) tests live in spec/*
.
To run the tests from the command line:
rspec
Front-end linting can be done by running the following commands:
npm run lint-vue
This will check for any potential JavaScript issues and whether you formatted the code correctly.
-
Make sure you have a separate production database:
psql postgres 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: '...' 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 front-end assets
npm run build-vue
-
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.
Make sure you are on the Berkeley network or connected through preconfigured VPN for the Oracle connection.
If you use a VPN, use group 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: true 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 a UID (e.g.
61889
for oski) and then the 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)
Access the URL:
https://[hostname]/act_as?uid=123456
where 123456 is the UID of the user to emulate.
Note: 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.
Proxies running in fake mode use WebMock to substitute fixture data for connections to external services (Canvas, Google, etc). This fake data lives in fixtures/json
and fixtures/xml
.
Fixture files can represent time information by tokens that are substituted with appropriately shifted values when fixture data is loaded. See config/initializers/timeshift.rb
for the dictionary of substitutions.
To view other rake tasks for the project: rake -T
Dev, QA, and Production CalCentral environments use memcached as a cache store in place of the default ActiveSupport cache store.
To set this up locally, perform the following steps:
-
Install and run memcached.
-
Add the following lines to development.local.yml:
cache:
store: "memcached"
A few rake tasks to help monitor statistics and more:
-
rake memcached:clear
- Invalidate all memcached keys and reset memcached stats from all cluster nodes. -
rake memcached:get_stats
- Fetch memcached stats from all cluster nodes. Per-slab stats may point out specific types of data which are being overcached or undercached, or indicate a need to reconfigure memcached. -
rake memcached:dump_slab slab=NUMBER
- Shows which cached items are currently stored in the "slab" with the given ID. The list won't include the keys of expired or evicted items. -
WARNING: do not run
rake memcached:clear
on the production cluster unless you know what you're doing! -
All
memcached
tasks take the optional param ofhosts
. 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
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 -O -x --inserts --clean -f developer-seed-data.sql -t oec_course_codes \
-h postgres-hostname -p postgres-port-number -U calcentral
Copy the file into your source tree and get it merged into master.