Requirements: Docker (Docker Desktop for macOS and Windows or Docker Compose for Linux), Python 3 with the invoke package installed globally, and git.
We recommend that you install Invoke using pipx, but any Python package manager should work (pip, poetry, etc).
docker run hello-world.invoke --versionshould return 0.22.1 or higher.
Run the following terminal commands to get started:
git clone https://github.com/mozilla/foundation.mozilla.org.gitcd foundation.mozilla.orginv new-env
You're done 🎉
This task creates a .env that is in charge of managing your environment variables while running Docker. The installation will take a few minutes: you need to download images from the Docker Hub, install JS and Python dependencies, create fake data, migrate your database, etc.
When it's done, run docker-compose up, wait until the static files to be built, and go to 0.0.0.0:8000. You should have a local working version of the foundation site with fake data. When you want to stop, do ^C to shut down your containers.
To log into the admin site, a superuser will have been created with username admin with password admin.
To catch up on new dependencies, migrations, etc. after initial setup, you can use the inv catch-up command. To get a full new environment with a new database, run inv new-env again.
Use inv -l to get a list of all the available invoke commands.
More information on how to work with Docker and how to manage Python dependencies are available in the local development part of the documentation.
When relevant, we encourage you to write tests. You can run the tests using inv test, or you can run the Node and Python testing suites separately:
- Run Node tests:
inv test-node - Run Python tests:
inv test-python
If inv test-node shows linting errors for either JS/JSX or CSS/SCSS, you can run the inv npm "run fix" command to make the linting utilities automatically fix (or at least try to fix) any errors they knows how to fix. This will almost always be the only step required to ensure the linting phase of testing passes.
In addition to the code tests there are also visual regression tests, located in the ./cypress/integration directory. You can run these tests locally by installing cypress using npm i [email protected], after which the command npm run cypress will run these tests locally. However, note that these tests are currently intended for screenshot comparisons across branches, and so will not yield any meaningful results when run for a single branch.
Accessibility tests are not part of the standard tests covered by inv test. You can run them locally by running npm install and npm run cypress:install once, after which the following command will run the a11y testing:
npm run cypress:a11y
Note that when tests fail, the ./cypress/screenshots directory will contain one screenshot for each failed test.
The fake data generator can generate a site structure for the Mozilla Festival that can be served under it's own domain, or in the case of review apps on Heroku, where we're limited to a single domain, as a sub-directory of the main foundation site, at {review_app_host}/mozilla-festival.
In order to access the Mozilla Festival site locally on a different domain than the main Foundation site, you'll need to edit your hosts file (/etc/hosts on *nix systems, C:\Windows\System32\Drivers\etc\hosts on Windows) to allow you to access the site at mozfest.localhost:8000. To enable this, add the following line to your hosts file: 127.0.0.1 mozfest.localhost
As this is REST API and CMS built on top of Django, there are some "gotcha!"s to keep in mind due to the high level of magic in the Django code base (where things will happen automatically without the code explicitly telling you).
The DEBUG flag does all sorts of magical things, to the point where testing with debugging turned on effectively runs a completely different setup compared to testing with debugging turned off. When debugging is on, the following things happen:
- Django bypasses the
ALLOWED_HOSTrestrictions, which again can lead to400 Bad Requesterrors inDEBUG=Falsesetting. - Rather than HTTP error pages, Django will generate stack traces pages that expose pretty much all environment variables except any that match certain substrings such as
KEY,PASS, etc. for obvious security reasons. - ...there are probably more gotchas just for
DEBUGso if you find any please add them to this list.
Translations of UI strings (from the Django and React apps) are stored in the fomo-l10n repository. Translations are happening in Pontoon, in multiple projects: Foundation website, *Privacy Not Included and Mozilla Festival.
The latest source strings are regularly exposed to Pontoon by a Localization PM using the following process:
- Clone the
fomo-l10nrepository locally. - Set the
LOCAL_PATH_TO_L10N_REPOvariable in your.envfile. Use the absolute path to your copy of thefomo-l10nrepository and include the trailing slash. E.g.LOCAL_PATH_TO_L10N_REPO=/Users/username/Documents/GitHub/fomo-l10n/
- Make sure your local repositories of
fomo-l10nandfoundation.mozilla.orgare matching the latest revision from main. - Run
inv docker-makemessagesfrom yourfoundation.mozilla.orgrepository. - Files should have been updated in your
fomo-l10nrepository. You can now create a pull-request.
Latest translations are uploaded to S3. To get them, run:
curl -o translations.tar https://foundation-site-translations.s3.amazonaws.com/translations.tartar -C network-api -xvf translations.tar
You don't need to run compilemessages and it works for both pipenv or docker workflows.
The translations_github_commit_[...] file from the archive is only used for debug purposes on Heroku. It can be safely deleted if needed.
We love contributors, but the team maintaining this project is small and not structured to significantly support new and inexperienced contributors. If there's an unassigned issue that catches your eye, feel free to open a PR for it, but keep in mind our support will be limited. We usually don't have the capacity to walk you through the process of spinning up the project, opening a PR or describing what the solution to the issue could be.