Vote.gov

This repository contains the files and infrastructure to run the vote.gov website.

Section	Description
	CI status for staging ( click badge to see all staging builds )
	CI status for production ( click badge to see all production builds )
Installation	Installing the project locally.
Development	Development workflow using `gulp`.
Deployment	Automated & Manual deployment information using `cloud.gov`.
Contributing	Contributing to the project.
Wiki	`18F/vote-gov` wiki.

Installation

The development for the vote.gov site has the following dependencies

Hugo, a static-site generator written in Go.
Gulp, an automation tool for asset-pipelines.
NodeJS
Ruby

This documentation assumes that you have Ruby and NodeJS installed on your machine. Instructions for installing node, and npm, [can be found here] node-install.

Installing Hugo

In order to serve the vote.gov site locally, you will need to install the hugo command-line tool. This can be installed easily via Homebrew on Mac OS X with the following command in your Terminal.

brew update && \
brew install hugo

You can also download the latest release and checkout the quick start guide for further instructions.

Installing Gulp

In order to build the assets for the vote.gov site, you will need to install the gulp command-line tool.

npm install --global gulp-cli

Installing SCSS-Lint

The Sass file linter uses the Ruby gem scss_lint. This gem must be installed on your machine in order to run any tasks that depend on the scss-lint binary.

gem install scss_lint

Development

Once gulp is installed globally, navigate to this directory in your Terminal and tell npm to bring in the asset-pipeline's dependencies.

npm install

Once that is complete, run gulp in your Terminal to get a list of tasks.

$ gulp

  Using gulpfile ~/Developer/vote-gov/gulpfile.js
  Starting 'default'...
  v1.0.0 vote-gov
   ______  ______  _____       __   ________  ______  ______
  /\  ___\/\  ___\/\  __-.    /\ \ / /\  __ \/\__  _\/\  ___\
  \ \  __\\ \  __\\ \ \/\ \   \ \ \'/\ \ \/\ \/_/\ \/\ \  __\
   \ \_\   \ \_\   \ \____-    \ \__| \ \_____\ \ \_\ \ \_____\
    \/_/    \/_/    \/____/     \/_/   \/_____/  \/_/  \/_____/

  Available tasks

  ...

To start the local webserver for the English site and have gulp and hugo watch for changes:

npm start

The website is now available at http://localhost:1313/.

To start the local webserver for the Spanish site and have gulp and hugo watch for changes:

NODE_LANG=spanish npm start

The website is now available at http://localhost:1313/es/.

Descriptions for optional `gulp [ flags ]` task prefixes

These flags are 100% optional and can be omitted from any tasks that are affected by them.

no-test This flag disables linters and tests for all assets.
production This flag enables minification and compression of all assets in prep for a production environment.

Deployment

The microsite is deployed on [cloud.gov] cg-homepage. To read the cloud.gov documentation, [click here] cg-docs. The documentation below makes the following assumptions.

Assuming you have the cf binary installed on your machine and within your $PATH.
- [Please read Setting up the command line] cg-docs-cli-install for more information.
Assuming that you have a cloud.gov account.
- [Please read Setting up your account] cg-docs-cg-account for more information.

Automated deployment

This project uses [CircleCI] cci-homepage for continuous deployment. Our current process deploys our staging branch and our master branch to their own [staging] vote-staging and [production] vote-production URLs.

Manual deployment

Using the cf command-line tool, you can run a manual deployment to either staging or production by targeting the corresponding organization / space and as long as you have access to cf push the target. More information on deploying to cloud.gov can be found [here] cg-deploy-hw and [here] cg-deploy-ss.

Manual deployments are not necessary as all deployments should go through CircleCI.

To check which space you're targeting using the cf command-line tool, type the following in your terminal.

cf target

Building the `vote.gov` site locally

The vote.gov site is built using the npm run build command. This command looks for an environment variable containing the site's base-URL. This URL must be assigned to the SITE_BASEURL variable before running npm run build and must be set to the proper value depending on the space you're targeting.

Type the following in your terminal to build the English site for the staging space:

npm run build

Type the following in your terminal to build the English site for the production space:

NODE_ENV=production npm run build

Type the following in your terminal to build the Spanish site for the staging space:

# NOTE: Building the Spanish version of the site is currently experimental
NODE_LANG=spanish npm run build

Type the following in your terminal to build the Spanish site for the production space:

# NOTE: Building the Spanish version of the site is currently experimental
NODE_LANG=spanish NODE_ENV=production npm run build

Pushing to a target

Once you've built the vote.gov English site locally by running the above command, you can push your changes up to the targeted space.

Type the following in your terminal to deploy to the staging space:

# NODE: Deploying the Spanish version of the site is experimental
cf push -f manifest-staging.yml

Type the following in your terminal to deploy to the production space:

# NODE: Deploying the Spanish version of the site is experimental
cf push

Public domain

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.

arantxarecio/vote-gov