This is the source code for teach.mozilla.org.
For a summary of the most recent changes to the project, please
see CHANGELOG.md
. It's awesome.
This software consists of two major parts:
- A static site generator that creates a number of
index.html
files in various directories which can be viewed in any browser, including ones that don't support JavaScript. - Client-side JavaScript code that progressively enhances the user experience based on browser capabilities.
It should be noted that, based on the product roadmap, the static site generator may eventually evolve into becoming a dynamic server.
To get a local version of the site running, you'll need to have git and node installed on your local machine.
For best results, use node version 0.12.7 (as of November 2015). Verify your node version using:
node --version
If you need to install node, or switch to a different version of node, Node Version Manager (nvm) is a helpful tool. Instructions for installing nvm vary by environment. See notes below for Mac, Linux (Ubuntu, Debian, Raspbian) and Windows variations:
First, make sure your system has a c++ compiler, such as XCode.
Then use the nvm install script to install nvm. Once this completes, install node 0.12.7 using:
nvm install v0.12.7
Now you are ready to clone and build this repo locally using the Clone, Build and Develop steps below.
To use nvm for installing and managing different versions of node, first install prerequisite libraries using:
sudo apt-get update
sudo apt-get install build-essential libssl-dev
Then use the nvm install script to install nvm. Once this completes, install node 0.12.7 using:
nvm install v0.12.7
Now you are ready to clone and build this repo locally using the Clone, Build and Develop steps below.
This project is normally deployed on linux based servers or containers. If you are trying to build on Windows or older Mac OS versions, you may save time and headaches if you use a virtual development environment running a stable current linux distribution. If you are not able to create a local linux based development environment, here are some free or very low cost options:
- Raspberry Pi: low cost linux development environment (this project runs quite well on a Pi2 Model B)
- Koding.com: free linux based virtual machine and development environment 'in the cloud'. All you need is a browser.
In order to contribute to this project, you'll need to create your own fork of it and make pull-requests against our master branch.
Clone from your own fork or from the original:
git clone [email protected]:mozilla/teach.mozilla.org.git
cd teach.mozilla.org
To start developing, all you need to do is run the following in the teach.mozilla.org
directory you just created:
npm install
npm start
This will start a webserver for you at http://localhost:8008
, and run a watch
process so that your front-end assets will be regenerated as you make changes.
Because this project uses a variety of tools that transform the original source code before delivering it to the browser, it is critical for source maps to work properly in order to ensure a pleasant developer experience.
However, due to the unfortunate realities of software development, there isn't a "one size fits all" solution to this. Please be sure to read the Environment Variables section below and configure your environment as needed to ensure that you're seeing useful line numbers for whatever part of the codebase you need to change.
JS
lib/
: Non-react modules, as well as entry-point modules likemain.jsx
androutes.jsx
components/
: Re-usable react components that can be used throughout the sitepages/
: React "page" components, i.e. top-level pages required bylib/router
mixins/
: React mixins
Less
less/
: This is where you should add styles.common.less
is the entry-point.
Other
test/
: For js tests, manual testsimg/
: For imagesdist/
: Generated site assets goes here. This folder is gitignored, do not edit files here.
Fully testing the code is accomplished by running npm test
,
which exercises a number of different aspects of the
codebase described below.
This generates a full static site and ensures that no React warnings are raised.
Individually running only the smoke test can be accomplished
via npm run smoketest
.
Unit tests are spread across two different testing environments.
Both environments use the mocha test runner and should for assertions.
These tests generally exercise the code of the static site generator
and are located in the test
directory.
Each test file should end with .test.js
and will be automatically
discovered by the test runner.
Individually running only the node unit tests can be accomplished
via node_modules/.bin/mocha test/*.test.js
. For more options,
see the documentation for mocha (1).
These tests exercise the code that runs in the user's browser. They're
located in the test/browser
directory.
Each test file should end with .test.js
or .test.jsx
and will be
automatically discovered by the test runner.
Individually running only the browser unit tests can be accomplished
by first running npm start
and then visiting http://localhost:8008/test/
in your browser.
For detailed information about manual testing, see the
Manual Testing section of CONTRIBUTING.md
.
Run npm run build
to generate a static site in dist/
that
doesn't require any client-side JavaScript. This static
site also uses history.pushState
for navigation if the browser
supports it.
For reference, a recent static build of the site can be found at teach.mofostaging.net.
The static site can also be deployed to S3 via npm run s3
, but
this requires setting at least a few environment variables. See
the Environment Variables section below for more details.
The following environment variables can be used to modify how the software works.
Name | Description |
---|---|
NODE_ENV |
set this to production to automatically minify code and remove various development-only affordances. |
SHOW_DEV_RIBBON |
set this to on to show the "dev version" ribbon even when NODE_ENV is set to production. This can be used on staging sites. |
WEBPACK_DEVTOOL |
determines the setting for the devtool Webpack option. In development, it defaults to eval , while in production it defaults to source-map . For more details on the trade-offs between different options, see our conversation on sourcemaps. |
LESS_AUTOPREFIXER |
set this to off to disable the LESS autoprefixer and enable useful CSS source maps, which is a workaround for #413. |
AWS_ACCESS_KEY |
is the Amazon Web Services access key used when uploading to s3 via npm run s3 . |
AWS_SECRET_KEY |
is the Amazon Web Services secret key used when uploading to s3 via npm run s3 . |
AWS_BUCKET |
is the S3 bucket to upload to when using npm run s3 . It defaults to teach.mofostaging.net . |
AWS_REGION |
is the S3 region to upload to when using npm run s3 . It defaults to us-east-1 . |
ORIGIN |
is the domain name of which the site is hosted. This is used in situations where absolute URLs are required, such as generating a sitemap.xml file. |
MAPBOX_ACCESS_TOKEN |
is the Mapbox access token to use for embedded maps in the website. Optional. |
MAPBOX_MAP_ID |
is the Mapbox map ID to use for embedded maps in the website. Optional. |
TEACH_API_URL |
is the origin of the Teach API server. Defaults to https://teach-api.herokuapp.com . |
GA_ACCOUNT |
is the property ID of the Google Analytics account. E.g. UA-123... . It defaults to the property ID for the Teach site. Set it to DISABLED to disable Google Analytics entirely. |
GA_DEBUG |
When set to 'on' will output verbose info to the console about what data is being sent to Google Analytics. |
PLEDGE_MAILINGLIST_URL |
is the pledge signup form URL generated by BSD. If undefined, mailinglist signup is simulated for development purposes. |
PLEDGE_MAILINGLIST_PRIVACY_NAME |
is the name attribute of the privacy policy checkbox on the pledge signup form generated by BSD. |
PORT |
is the port to serve the experimental lightweight dynamic server on. Defaults to 8008. |
OPTIMIZELY_ID |
Optimizely Project ID (not a secret) e.g. '206878104' |
OPTIMIZELY_ACTIVE |
If set to 'yes' (String) the project will include Optimizely snippet in the page load |
MAKE_METADATA_URL |
The template source url to load users' Makes metadata. Username should be included in the URL as a variable. e.g., https://{username}.makes.org/makes.json |
First, create a .env
file in the root of your project:
export GA_ACCOUNT='xxxxxxx'
export TEACH_API_URL='xxxxxxx'
Then run source .env
before running npm start
.
Note: If you're on Windows, this won't work, and you'll likely
want to create a batch file that uses
setx.exe
.
The site can also be served through a lightweight server which dynamically generates requested HTML files. This feature is currently experimental. For more information on the rationale behind it, see #585.
To run the server in development mode, use npm run app
. The
server-side page rendering code will be dynamically updated as
relevant files are changed.
For production deployment, you will need to:
-
Set
NODE_ENV=production
and other relevant environment variables and then re-runnpm install
. This will build all static assets that won't change during production. -
Run
node app.js
.
The server is also designed to be easily deployable on Heroku.