The ApprenticeshipStandards.org application is currently running on Ruby 3, Rails 7, and PostgreSQL 14.
- Install Elasticsearch
- Start
elasticsearch
in the terminal, as the setup command will run some tasks to create Elasticsearch indexes. - Copy
.env.sample
to.env
and edit theONET_WEB_SERVICES_USERNAME
andONET_WEB_SERVICES_PASSWORD
variables so you can run the setup task without issue. - Run
bin/setup
. One of the After Party tasks takes several minutes to run. Once completed, it will not run on subsequentbin/setup
calls. - Kill
elasticsearch
as it will get started with thebin/dev
command below - Install mailcatcher to preview emails. See the troubleshooting section if you have installation issues.
- To access the admin pages, you must modify your
/etc/hosts
file:# Added for ApprenticeshipStandards.org 127.0.0.1 admin.example.localhost # End ApprenticeshipStandards.org additions
- Start the rails app with
bin/dev
:- The public facing application will be available at http://localhost:3000
- The admin pages will be available at http://admin.example.localhost:3000
- Email previews will be available at http://localhost:1080
If you run into an issue while installing mailcatcher, you can try installing thin with the following command:
gem install thin -v 1.5.1 -- --with-cflags="-Wno-error=implicit-function-declaration"
Then, try to install mailcatcher again:
gem install mailcatcher
You can also install mailcatcher with brew:
brew install mailcatcher
If you want to convert doc and docx documents to PDF, you can install install libreoffice with brew:
brew install --cask libreoffice
We have a Heroku pipeline set up with a staging and a production app. The staging and production remotes can be added locally as follows:
git remote add staging https://git.heroku.com/apprenticeship-standards-stag.git
git remote add production https://git.heroku.com/apprenticeship-standards-dot-o.git
The staging app will be deployed automatically any time code is merged to the
main
branch.
Once code changes have gone through QA on staging, the changes can be deployed to production on the command line:
git push production main
If you name your production remote something other than "production", then be sure to replace "production" with the name of your remote.
The deployment can also be done through the Heroku Dashboard. Promoting the staging slug does not work since the application is built with Docker.
We are currently using Elasticsearch version 8.10.3. See the Elasticsearch
documentation
for installation options. To debug any queries, set log: true
in
the config/initializers/elasticsearch.rb
client setup.
For your local Elasticsearch setup, if you get errors like:
The client is unable to verify that the server is Elasticsearch. Some functionality may not be compatible if the server is running an unsupported product.
then you will need to turn off the security features for your Elasticsearch
configuration. Edit the config/elasticsearch.yml
file in your Elasticsearch
installation to turn all the enabled
flags to false
:
xpack.security.enabled: false
xpack.security.enrollment.enabled: false
xpack.security.http.ssl:
enabled: false
keystore.path: certs/http.p12
xpack.security.transport.ssl:
enabled: false
verification_mode: certificate
keystore.path: certs/transport.p12
truststore.path: certs/transport.p12
cluster.initial_master_nodes: ["My-MacBook-Pro.local"]
http.host: 0.0.0.0
If you are using a docker image of Elasticsearch you can start it with docker run -p 9200:9200 -m 1GB -e "discovery.type=single-node" -e "xpack.security.enabled=false" docker.elastic.co/elasticsearch/elasticsearch:8.10.3
. Make sure the number at the end matches the version number for the image.
If you are working on any tasks related to Elasticsearch, then it may be helpful to set up Kibana.
To start Kibana, make sure that elasticsearch is already running, then run
kibana
in the terminal. Kibana will be available at http://localhost:5601. To
access the dev tools, click the hamburger menu icon in the nav, and go to "Dev
Tools" under the Management section.
To see all of the records in the occupation_standards
in the Kibana Dev Tools enter:
GET occupation_standards_development/_search
{
"query": {
"match_all": {}
}
}
and click the green arrow button to run the query. You should see data returned for all of the OccupationStandard records in your local database in the panel on the right.
If you need to view the names of all your indices, under the Management section go to "Stack Management". Then under the Data section, click "Index Management" to see the list of all the available indices.
If you will have access to AWS to manage the S3 buckets, view the setup documentation.
We are using standard for Ruby linting. To check the style of all Ruby files, run:
bundle exec standardrb
To automatically apply linting fixes, run:
bundle exec standardrb --fix
We are using erb_lint for ERB linting. To check the style of all
.erb
files, run:
bundle exec erblint --lint-all --autocorrect
We are using After Party to run post-deployment tasks. These tasks may include one-time necessary updates to the database. Run the tasks manually by:
bundle exec rake after_party:run
Alternatively, every time you pull the main branch, run:
bin/setup
which will update gems, run any database migrations, and run the after party post-deployment tasks.
We are using RSpec for tests. Before beginning a new feature, please run the specs and make sure the entire test suite is passing. All tests should be passing when submitting a PR. Please write specs as appropriate.
To run all specs:
bundle exec rspec spec -fd
To run an individual file:
bundle exec rspec spec/models/user_spec.rb -fd
To run an individual spec, pass the spec name or partial match:
bundle exec rspec spec/models/user_spec.rb -fd -e "valid factory"
Individual specs can also be run by specifying the line number:
bundle exec rspec spec/models/user_spec.rb:4 -fd
The -fd
flag is for "format: documentation", and will list out each spec name
as it is run. These flags can be left off for more concise output.
For system specs that require JavaScript, append js: true
to the relevant
scenario, context, or describe statement. This has the added benefit of
generating a screenshot upon failure. To force any non-JS-requiring system test
to generate a screenshot, you can also temporarily add js: true
to the spec to
help diagnose the failure. For example:
# spec/system/standards_import/new_spec.html.erb
it "shows success message", js: true do
...
end
By default we are using the headless version of Chrome to run system specs with
JavaScript, but you can run the non-headless version to watch the spec get run
in the browser. To use the non-headless version, add debug: true
to the spec:
# spec/system/standards_import/new_spec.html.erb
it "shows success message", debug: true do
...
end
Any errors when running in debug mode will also create a screenshot in the tmp
directory to help with debugging.
We use Flipper for our feature flags system.
You can turn on a feature flag by running:
Flipper.enable(:search)
and check if it's enabled with:
Flipper.enabled?(:search) # true
When writing specs, there is a helper method to use:
stub_feature_flag(:my_feature_flag, <boolean value>)
.