IMPORTANT: Checkout this branch to a folder named teachcomputing with git clone [email protected]:NCCE/teachcomputing.org.git teachcomputing (one or two scripts right now expect the docker project name to be teachcomputing, so for now this is the easiest approach)
- Homebrew
- Docker (incl. Docker Compose, which already part of Docker for Mac and Docker Toolbox) > v4.0 (with support for
docker compose) - Python 2.7 (not 3.x yet)
This script builds the docker image, sets up environment variables and adds a nicer local hostname:
sh ./scripts/setup.sh
In order for OAuth to work with STEM you will need to make sure you have an id and secret set. You get these from here.
If you want to skip the OAuth flow you can set BYPASS_OAUTH to true in your .env file. This will log you in as [email protected].
By default the development environment expects to be able to communicate with Stem's staging Dynamics API which is used to populate the course list, and user enrolments etc. You'll need to add staging credentials to .env (find in lastpass: TC Achiever creds):
# STAGING
ACHIEVER_V2_PASSWORD=...
ACHIEVER_V2_USERNAME=...
ACHIEVER_V2_ENDPOINT=...
If your IP address is whitelisted, set PROXY_URL='' in .env. If not, you will need to ensure you have a proxy setup that tunnels to a whitelisted IP. You can do this here
There are two commands yarn start-tunnel and yarn stop-tunnel that are wrappers to manage the proxy locally, yarn start (below) utilises this to create the tunnel when the stack is brought up. It is important to have this setup for testing, however please see the 'Offline Dynamics' section below for how to run this offline.
Start the stack (this automatically creates the ssh tunnel and waits until the stack is ready to use):
yarn start
The app is then available at: http://teachcomputing.rpfdev.com
Stop the stack (this also gracefully closes the tunnel):
yarn stop
Sidekiq is used to process background jobs. You can view the admin UI for this by visiting /admin/sidekiq and using GSuite account to authenticate.
To develop offline, removing the need for the proxy and a third party API, you can set the following environment variables in your .env:
ACHIEVER_USE_LOCAL_TEMPLATES=true
ACHIEVER_LOCAL_TEMPLATE_PATH='spec/support/achiever/local_templates'
Data already exists in the path defined above, but it can be moved if you prefer.
This is useful if you want to create your own test data, for example by changing the data in the coursesforcurrentdelegatebyprogramme.json and linking the stem_achiever_contact_no to your local user and updating the COURSETEMPLATENO, you could generate enrolments in order to test course bookings (without this the test data needs to exist in Stem's API).
A task has been created to refresh this data from the api, run this with:
yarn run exec rake achiever:refresh_local_templates
The database is automatically setup the first time the container is run, and a migration is performed on each subsequent run.
yarn run reset-db
To perform migrations manually (without restarting the container) run:
yarn run web rails db:migrate
#### Seeding the database
To seed manually run:
yarn run web rails db:seed
The bundle has now been moved to a separate volume and once the initial build has taken place the bundle directory is mapped to a volume and persisted.
To install/update a new gem, first update the Gemfile and run
yarn run web bundle install
Components etc. can be rendered using the local/review/staging app urls:
Uses rspec
yarn test
To use guard to watch the tests:
yarn run exec guard
Sitemaps are generated via sitemap:refresh, which is managed by a scheduled task on Heroku. They can be found in the public directory.
Used for linting ERB / HTML files
Run with yarn run exec erblint --lint-all
https://github.com/Shopify/erb-lint
Used for detecting 'code smell' in your app.
Run with yarn run exec reek
Used for static code analysis to check for potential security flaws.
https://brakemanscanner.org/docs/quickstart/
We are ignoring some of the warnings using the method described in the Brakeman docs We are using the default location for the ignore file, etc.
Run brakeman -I config/brakeman.ignore . in the project root and follow the onscreen prompts, outlined in the above doc, to use the tool and check the output for warnings, etc.
ruby-debug-ide is enabled and waiting for connections by default on port 1234. There is a launch.json in the repo and if you're using vscode it should be as easy as going to the 'Run' view, selecting 'Rails Debug' and clicking the green Run button. It's important to note that if you attempt to restart or stop the debug process, this will effectively kill the container, and a docker compose up -d will be necessary to continue - however this is rarely necessary in general use since you'll be debugging individual requests.
Calling yarn run rspec-debug <path to spec> will start an rspec debug session, this session will wait for a connection on 127.0.0.1:1235. Add any breakpoints required, then for VSCode there is a launch configuration in launch.json called 'RSpec Debug', starting this will glom onto the previously started debug session.
If you prefer to use byebug you'll first need to attach to the container which can be done with the command: docker attach teachcomputingorg_web_1 (the container name can be checked with docker compose ps, but mostly it'll be the one here), then add your breakpoint and trigger your request. Again ending the session by quitting byebug or hitting ctrl+c will kill the container, so you'll need to run docker compose up -d again.
Set OAUTH_DEBUG=true in your .env file for more useful OAUTH logging.
erd.pdf will be generated automatically whenever new migrations are run.
To generate erd.pdf manually:
docker-compose run web bundle exec erd
yarn startwill timeout if it fails to reach the site after a period of time, it will then output the docker logs so you can see the most recent output.- If you can access the site at
localhost:3000but not atteachcomputing.rpfdev.com, the nginx instance used by dev-nginx may have gone down, just rundev-nginx restartto bring it up again.
Turbolinks was disabled because it stopped a bunch of critical page reporting and also download data from being captured. Avoid turning it back on. Without turbolinks, this will break; the browser will complain that Turbolinks is missing:
redirect_to @foo, notice: 'Foo was successfully created.'Resolve by removing notice: 'Foo was successfully created.'