Running in a Virtual Environment¶
First, follow the standalone installation instructions to create your virtual environment, install required dependencies, and run the setup scripts.
You will generally have three tabs (or windows) open in your terminal, which will be used for:
- Git operations.
Perform Git operations and general development in the repository,
git checkout master.
- Elasticsearch. Run an Elasticsearch (ES) instance. See instructions below.
- Django server. Start and stop the web server.
Server is started with
./runserver.sh, but see more details below.
What follows are the specific steps for each of these tabs.
1. Git operations¶
From this tab you can do Git operations, such as checking out our master branch:
git checkout master
Updating all dependencies¶
Each time you fetch from the upstream repository (this repo), run
This setup script will remove and reinstall the project dependencies
You may also run
if you only want to re-build the backend or front-end, respectively.
NODE_ENV environment variable can be set in your
.env file to either
production, which will affect how the build is made and what
gulp tasks are available. To install dependencies of one environment
or the other run
./frontend.sh (dependencies and devDependencies)
./frontend.sh production (dependencies but not devDependencies).
2. Run Elasticsearch (optional)¶
Elasticsearch is needed for certain pieces of this project but is not a requirement for basic functionality.
If Elasticsearch is installed via Homebrew, you can see instructions for running manually or as a background service using:
brew info elasticsearch
Typically to run Elasticsearch as a background service you can run:
brew services start elasticsearch
3. Launch Site¶
First, move into the
cfgov-refresh project directory
and ready your environment:
# Use the cfgov-refresh virtualenv. workon cfgov-refresh # cd into this directory (if you aren't already there) cd cfgov-refresh
From the project root, start the Django server:
If prompted to migrate database changes,
stop the server with
c and run these commands:
python cfgov/manage.py migrate ./initial-data.sh ./runserver.sh
To view the site browse to: http://localhost:8000
Using a different port
If you want to run the server at a port other than 8000 use
python cfgov/manage.py runserver <port number>
Specify an alternate port number, e.g.
To view the Wagtail admin login,
browse to http://localhost:8000/admin and login with username
admin (created in
initial-data.sh above; note that this
password will expire after 60 days).
Using HTTPS locally
To access a local server using HTTPS use
You'll need to ignore any browser certificate errors.
Available Gulp Tasks¶
There are a number of important gulp tasks,
which will build the project and test it, respectively.
Tasks are invoked via an
yarn run command so that the local gulp-cli can be used.
yarn run gulp -- --tasks command you can view all available tasks.
The important ones are listed below:
yarn run gulp build # Concatenate, optimize, and copy source files to the production /dist/ directory. yarn run gulp clean # Remove the contents of the production /dist/ directory. yarn run gulp lint # Lint the scripts and build files. yarn run gulp docs # Generate JSDocs from the scripts. yarn run gulp test # Run linting, unit and acceptance tests (see below). yarn run gulp test:unit # Run only unit tests on source code. yarn run gulp test:acceptance # Run only acceptance (in-browser) tests on production code. yarn run gulp audit # Run code quality audits.
Reinstalling the virtual environment¶
To remove an existing virtual environment for a reinstall of cfgov-refresh, first deactivate the virtual environment if it is active:
Then remove the existing virtual environment:
After this, you may follow the installation instructions again.