tsigie / analytics.usa.gov Goto Github PK

A project to publish website analytics for the US federal government.

For a detailed description of how the site works, read 18F's blog post on analytics.usa.gov.

Other organizations who have reused this project for their analytics dashboard:

This blog post details their implementations and lessons learned.

You need Docker and docker-compose.

To build and run the app with docker-compose, run docker-compose up -d then you can access the app from http://localhost:4000, as the local filesystem is mounted on top of the docker container you can edit the files as you are developing locally.

To see the jekyll logs, run:

docker-compose logs -f

Ths app uses Jekyll to build the site, and Sass, Bourbon, and Neat for CSS.

Install them all:

bundle install

analytics-reporter is the code that powers the analytics dashboard. Please clone the analytics-reporter next to a local copy of this github repository.

0. Ensure that data is being collected for a specific agency's Google Analytics ID. Visit 18F's analytics-reporter for more information. Save the url path for the data collection path.
1. Create a new html file in the _agencies directory. The name of the file will be the url path.

touch _agencies/agencyx.html

0. Create a new html file in the _data_pages directory. Use the same name you used in step 2. This will be the data download page for this agency

touch _data_pages/agencyx.html

0. Set the required data for for the new files. (Both files need this data.) example:

---
name: Agency X # Name of the page
slug: agencyx # Same as the name of the html files. Used to generate data page links.
layout: default # type of layout used. available layouts are in `_layouts`
---

0. Agency page: Below the data you just entered, include the page content you want. The _agencies page will use the charts.html partial and the _data_pages pages will use the data_download.html partial. example:

{% include charts.html %}

Run Jekyll with development settings:

make dev

(This runs bundle exec jekyll serve --watch --config=_config.yml,_development.yml.)

The development settings assume data is available at /fakedata. You can change this in _development.yml.

If also working off of local data, e.g. using analytics-reporter, you will need to make the data available over HTTP and through CORS.

Various tools can do this. This project recommends using the Node module serve:

npm install -g serve

Generate data to a directory:

analytics --output [dir]

Then run serve from the output directory:

serve --cors

The data will be available at http://localhost:3000 over CORS, with no path prefix. For example, device data will be at http://localhost:3000/devices.json.

To deploy to analytics.usa.gov after building the site with the details in _config.yml:

make deploy_production

To deploy to analytics-staging.app.cloud.gov after building the site with the details in _config.yml and _staging.yml:

make deploy_staging

NOTE: 18F does not use Docker in production!

If you are using Docker in production and you want to deploy just the static pages, you can build an nginx container with the static files built in, running the following command:

make docker-build-production PROD_IMAGE=yourvendor/your-image-name PROD_TAG=production

The resulting image will be an nginx server image that you can safely push and deploy to your server.

The image accepts an environment variable to specify the S3 URL that data at /data/* is served from:

docker run -p 8080:80 -e S3_BUCKET_URL=https://s3-us-gov-west-1.amazonaws.com/your-s3-bucket/data yourvendor/your-image-name:production

This repo has git tags. The tag for Docker images built for this repo relate to these git tags. In the examples below, <version refers to the tag value of the current commit. When building a new version, be sure to increment the git tag appropriately.

When building images there are 2 images to build: <version> and <version>-production.

To build the images:

docker build -f ./Dockerfile -t 18fgsa/analytics.usa.gov:<version> .
docker build -f ./Dockerfile.production -t 18fgsa/analytics.usa.gov:<version>-production .

To push the images:

docker push 18fgsa/analytics.usa.gov:<version>
docker push 18fgsa/analytics.usa.gov:<version>-production

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.