├── _config_18f_pages.yml ├── assets └── css │ └── styles.scss ├── .gitignore ├── .travis.yml ├── Gemfile ├── _deploy └── etc │ ├── logrotate.d │ └── 18f-pages-server │ └── nginx │ └── vhosts │ └── pages.conf ├── fabfile.py ├── .jshintrc ├── _scripts └── all_pages.rb ├── pages-config.json ├── CONTRIBUTING.md ├── go ├── LICENSE.md ├── _config.yml ├── index.html ├── Gemfile.lock ├── .about.yml └── README.md /_config_18f_pages.yml: -------------------------------------------------------------------------------- 1 | baseurl: 2 | asset_root: /guides-template 3 | -------------------------------------------------------------------------------- /assets/css/styles.scss: -------------------------------------------------------------------------------- 1 | --- 2 | --- 3 | 4 | @import "guides_style_18f"; 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_store 2 | .*.swp 3 | *.pyc 4 | _site/ 5 | .sass-cache 6 | node_modules/ 7 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: ruby 2 | sudo: false 3 | script: ./go build 4 | rvm: 5 | - 2.2.3 6 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | gem 'jekyll' 4 | gem 'go_script' 5 | 6 | group :jekyll_plugins do 7 | gem 'guides_style_18f' 8 | end 9 | -------------------------------------------------------------------------------- /_deploy/etc/logrotate.d/18f-pages-server: -------------------------------------------------------------------------------- 1 | # Note that copytruncate isn't a perfect solution, but it'll suffice for the 2 | # 18f-pages-server. For more information: 3 | # https://github.com/foreverjs/forever/issues/106#issuecomment-116933382 4 | /var/log/18f-pages-server/pages.log { 5 | rotate 12 6 | monthly 7 | compress 8 | missingok 9 | notifempty 10 | copytruncate 11 | } 12 | -------------------------------------------------------------------------------- /fabfile.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env python2.7 2 | 3 | import fabric.api 4 | 5 | fabric.api.env.use_ssh_config = True 6 | fabric.api.env.hosts = ['18f-pages'] 7 | CMD = "pages/pages.js" 8 | 9 | def start(): 10 | fabric.api.run("forever start -l $HOME/pages.log -a %s" % CMD) 11 | 12 | def stop(): 13 | fabric.api.run("forever stop %s" % CMD) 14 | 15 | def restart(): 16 | fabric.api.run("forever restart %s" % CMD) 17 | -------------------------------------------------------------------------------- /.jshintrc: -------------------------------------------------------------------------------- 1 | { 2 | "asi": false, 3 | "bitwise": true, 4 | "browser": true, 5 | "camelcase": true, 6 | "curly": true, 7 | "forin": true, 8 | "immed": true, 9 | "latedef": "nofunc", 10 | "maxlen": 80, 11 | "newcap": true, 12 | "noarg": true, 13 | "noempty": true, 14 | "nonew": true, 15 | "predef": [ 16 | "$", 17 | "jQuery", 18 | 19 | "jasmine", 20 | "beforeEach", 21 | "describe", 22 | "it", 23 | 24 | "angular", 25 | "inject", 26 | "module", 27 | 28 | "Promise" 29 | ], 30 | "quotmark": true, 31 | "trailing": true, 32 | "undef": true, 33 | "unused": true 34 | } 35 | -------------------------------------------------------------------------------- /_scripts/all_pages.rb: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env ruby 2 | 3 | require 'octokit' 4 | 5 | TOKEN_PATH = File.join(ENV['HOME'], '.github_token') 6 | 7 | unless File.exist? TOKEN_PATH 8 | $stderr.puts "No GitHub token found at #{TOKEN_PATH}" 9 | exit 1 10 | end 11 | 12 | access_token = File.read TOKEN_PATH 13 | Octokit.auto_paginate = true 14 | client = Octokit::Client.new access_token: access_token 15 | repos = client.org_repos('18F').collect { |repo| repo.full_name } 16 | 17 | pages_repos = repos.select do |name| 18 | client.branches(name).any? { |b| b.name == '18f-pages' } 19 | end.sort 20 | 21 | pages_repos.each { |repo| puts repo } 22 | -------------------------------------------------------------------------------- /pages-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "port": 5000, 3 | "home": "/home/ubuntu", 4 | "git": "/usr/bin/git", 5 | "bundler": "/usr/local/rbenv/shims/bundle", 6 | "jekyll": "/usr/local/rbenv/shims/jekyll", 7 | "rsync": "/usr/bin/rsync", 8 | "rsyncOpts": [ 9 | "-vaxp", "--delete", "--ignore-errors", "--exclude=.[A-Za-z0-9]*" 10 | ], 11 | "payloadLimit": 1048576, 12 | "githubOrg": "18F", 13 | "pagesConfig": "_config_18f_pages.yml", 14 | "assetRoot": "/guides-template", 15 | "fileLockWaitTime": 30000, 16 | "fileLockPollTime": 1000, 17 | "builders": [ 18 | { 19 | "branch": "18f-pages", 20 | "repositoryDir": "pages-repos", 21 | "generatedSiteDir": "pages-generated", 22 | "internalSiteDir": "pages-internal" 23 | }, 24 | { 25 | "branch": "18f-pages-staging", 26 | "repositoryDir": "pages-repos-staging", 27 | "generatedSiteDir": "pages-staging" 28 | } 29 | ] 30 | } 31 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Welcome! 2 | 3 | We're so glad you're thinking about contributing to an 18F open source project! If you're unsure or afraid of anything, just ask or submit the issue or pull request anyways. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contribution, and don't want a wall of rules to get in the way of that. 4 | 5 | Before contributing, we encourage you to read our CONTRIBUTING policy (you are here), our LICENSE, and our README, all of which should be in this repository. If you have any questions, or want to read more about our underlying policies, you can consult the 18F Open Source Policy GitHub repository at https://github.com/18f/open-source-policy, or just shoot us an email/official government letterhead note to [18f@gsa.gov](mailto:18f@gsa.gov). 6 | 7 | ## Public domain 8 | 9 | This project is in the public domain within the United States, and 10 | copyright and related rights in the work worldwide are waived through 11 | the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/). 12 | 13 | All contributions to this project will be released under the CC0 14 | dedication. By submitting a pull request, you are agreeing to comply 15 | with this waiver of copyright interest. 16 | -------------------------------------------------------------------------------- /go: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env ruby 2 | 3 | require 'English' 4 | 5 | Dir.chdir File.dirname(__FILE__) 6 | 7 | def try_command_and_restart(command) 8 | exit $CHILD_STATUS.exitstatus unless system command 9 | exec({ 'RUBYOPT' => nil }, RbConfig.ruby, *[$PROGRAM_NAME].concat(ARGV)) 10 | end 11 | 12 | begin 13 | require 'bundler/setup' if File.exist? 'Gemfile' 14 | rescue LoadError 15 | try_command_and_restart 'gem install bundler' 16 | rescue SystemExit 17 | try_command_and_restart 'bundle install' 18 | end 19 | 20 | begin 21 | require 'go_script' 22 | rescue LoadError 23 | try_command_and_restart 'gem install go_script' unless File.exist? 'Gemfile' 24 | abort "Please add \"gem 'go_script'\" to your Gemfile" 25 | end 26 | 27 | require 'guides_style_18f' 28 | 29 | extend GoScript 30 | check_ruby_version '2.2.3' 31 | 32 | command_group :dev, 'Development commands' 33 | 34 | def_command :init, 'Set up the development environment' do 35 | update_node_modules 36 | end 37 | 38 | def_command :update_theme, 'Update the guides_style_18f gem' do 39 | GuidesStyle18F.update_theme 40 | end 41 | 42 | def_command :update_gems, 'Update Ruby gems' do |gems| 43 | update_gems gems 44 | end 45 | 46 | def_command :serve, 'Serve the site at localhost:4000' do |args| 47 | serve_jekyll args 48 | end 49 | 50 | def_command :build, 'Build the site' do |args| 51 | build_jekyll args 52 | end 53 | 54 | execute_command ARGV 55 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | As a work of the United States Government, this project is in the 2 | public domain within the United States. 3 | 4 | Additionally, we waive copyright and related rights in the work 5 | worldwide through the CC0 1.0 Universal public domain dedication. 6 | 7 | ## CC0 1.0 Universal Summary 8 | 9 | This is a human-readable summary of the [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode). 10 | 11 | ### No Copyright 12 | 13 | The person who associated a work with this deed has dedicated the work to 14 | the public domain by waiving all of his or her rights to the work worldwide 15 | under copyright law, including all related and neighboring rights, to the 16 | extent allowed by law. 17 | 18 | You can copy, modify, distribute and perform the work, even for commercial 19 | purposes, all without asking permission. 20 | 21 | ### Other Information 22 | 23 | In no way are the patent or trademark rights of any person affected by CC0, 24 | nor are the rights that other persons may have in the work or in how the 25 | work is used, such as publicity or privacy rights. 26 | 27 | Unless expressly stated otherwise, the person who associated a work with 28 | this deed makes no warranties about the work, and disclaims liability for 29 | all uses of the work, to the fullest extent permitted by applicable law. 30 | When using or citing the work, you should not imply endorsement by the 31 | author or the affirmer. 32 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | markdown: redcarpet 2 | name: 18F Pages 3 | exclude: 4 | - Gemfile 5 | - Gemfile.lock 6 | - CONTRIBUTING.md 7 | - README.md 8 | - LICENSE.md 9 | - hookshot.js 10 | - fabfile.py 11 | - fabfile.pyc 12 | - gulpfile.js 13 | - node_modules 14 | - package.json 15 | - vendor 16 | 17 | navigation: 18 | - text: Introduction 19 | url: 20 | internal: true 21 | children: 22 | - text: 18F/pages GitHub Repository 23 | url: https://github.com/18F/pages/ 24 | internal: false 25 | - text: 18f-pages-server 26 | url: https://www.npmjs.com/package/18f-pages-server 27 | internal: false 28 | children: 29 | - text: 18F/pages-server GitHub Repository 30 | url: https://github.com/18F/pages-server/ 31 | internal: false 32 | - text: 18F Guides 33 | url: guides 34 | internal: true 35 | children: 36 | - text: 18F/guides GitHub Repository 37 | url: https://github.com/18F/guides/ 38 | internal: false 39 | - text: Guides Template 40 | url: guides-template 41 | internal: true 42 | children: 43 | - text: 18F/guides-template GitHub Repository 44 | url: https://github.com/18F/guides-template/ 45 | internal: false 46 | 47 | google_analytics_ua: UA-48605964-19 48 | 49 | repos: 50 | - name: 18F Pages 51 | description: 18F Pages GitHub repository 52 | url: https://github.com/18F/pages 53 | 54 | defaults: 55 | - 56 | scope: 57 | path: "" 58 | values: 59 | layout: "guides_style_18f_default" 60 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | --- 2 | sites: 3 | - title: API Program 4 | url: /api-program 5 | - title: Midas 6 | url: /midas 7 | - title: FBOpen Docs 8 | url: /fbopen 9 | --- 10 |

Introduction

11 |

18F Pages is 18F's serving host and publishing platform for Jekyll-based websites.

12 | 13 |

Read sites made with 18F Pages

14 | 15 |

18F Guides

16 | 17 |

Our collection of best practices guides.

18 | 19 |

18F Slides

20 | 21 |

Host slide decks like this example from the 18F Slides repo on GitHub.

22 | 23 |

Other 18F Pages sites

24 | 25 |

Other sites published here include:

26 | 27 | 30 | 31 |

How 18F Pages works

32 | 33 |

The 18f-pages-server npm is the publishing mechanism for this website. See also the 18F Pages readme. The server may be reused by other organizations, as it is completely configurable.

34 | 35 |

How to create and update 18F Guides

36 | 37 |

To make a new guide, see guides-template for how to clone the template. This also contains a tutorial for how to set up a new guide and modify existing guides.

38 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | specs: 3 | blankslate (2.1.2.4) 4 | celluloid (0.16.0) 5 | timers (~> 4.0.0) 6 | classifier-reborn (2.0.3) 7 | fast-stemmer (~> 1.0) 8 | coffee-script (2.4.1) 9 | coffee-script-source 10 | execjs 11 | coffee-script-source (1.9.1.1) 12 | colorator (0.1) 13 | execjs (2.5.2) 14 | fast-stemmer (1.0.2) 15 | ffi (1.9.8) 16 | go_script (0.1.4) 17 | bundler (~> 1.10) 18 | safe_yaml (~> 1.0) 19 | guides_style_18f (0.1.3) 20 | jekyll (~> 2.5) 21 | rouge (~> 1.9) 22 | sass (~> 3.4) 23 | hitimes (1.2.2) 24 | jekyll (2.5.3) 25 | classifier-reborn (~> 2.0) 26 | colorator (~> 0.1) 27 | jekyll-coffeescript (~> 1.0) 28 | jekyll-gist (~> 1.0) 29 | jekyll-paginate (~> 1.0) 30 | jekyll-sass-converter (~> 1.0) 31 | jekyll-watch (~> 1.1) 32 | kramdown (~> 1.3) 33 | liquid (~> 2.6.1) 34 | mercenary (~> 0.3.3) 35 | pygments.rb (~> 0.6.0) 36 | redcarpet (~> 3.1) 37 | safe_yaml (~> 1.0) 38 | toml (~> 0.1.0) 39 | jekyll-coffeescript (1.0.1) 40 | coffee-script (~> 2.2) 41 | jekyll-gist (1.2.1) 42 | jekyll-paginate (1.1.0) 43 | jekyll-sass-converter (1.3.0) 44 | sass (~> 3.2) 45 | jekyll-watch (1.2.1) 46 | listen (~> 2.7) 47 | kramdown (1.7.0) 48 | liquid (2.6.2) 49 | listen (2.10.0) 50 | celluloid (~> 0.16.0) 51 | rb-fsevent (>= 0.9.3) 52 | rb-inotify (>= 0.9) 53 | mercenary (0.3.5) 54 | parslet (1.5.0) 55 | blankslate (~> 2.0) 56 | posix-spawn (0.3.11) 57 | pygments.rb (0.6.3) 58 | posix-spawn (~> 0.3.6) 59 | yajl-ruby (~> 1.2.0) 60 | rb-fsevent (0.9.4) 61 | rb-inotify (0.9.5) 62 | ffi (>= 0.5.0) 63 | redcarpet (3.2.3) 64 | rouge (1.10.1) 65 | safe_yaml (1.0.4) 66 | sass (3.4.13) 67 | timers (4.0.1) 68 | hitimes 69 | toml (0.1.2) 70 | parslet (~> 1.5.0) 71 | yajl-ruby (1.2.1) 72 | 73 | PLATFORMS 74 | ruby 75 | 76 | DEPENDENCIES 77 | go_script 78 | guides_style_18f 79 | jekyll 80 | 81 | BUNDLED WITH 82 | 1.10.6 83 | -------------------------------------------------------------------------------- /_deploy/etc/nginx/vhosts/pages.conf: -------------------------------------------------------------------------------- 1 | ## 2 | # Pages vhost 3 | # /etc/nginx/vhosts/pages.conf 4 | ## 5 | 6 | # HTTP server 7 | server { 8 | listen 80; 9 | server_name pages.18f.gov; 10 | return 301 https://$host$request_uri; 11 | } 12 | 13 | server { 14 | listen 127.0.0.1:8081; 15 | server_name playbook.cio.gov; 16 | port_in_redirect off; 17 | 18 | location /designstandards { 19 | root /home/ubuntu/pages-generated; 20 | index index.html; 21 | default_type text/html; 22 | } 23 | } 24 | 25 | # HTTPS server (with SPDY enabled) 26 | server { 27 | listen 443 ssl spdy; 28 | server_name pages.18f.gov; 29 | include ssl/star.18f.gov.conf; 30 | include new_relic/status.conf; 31 | 32 | location "~^/content-style-guide/(?.*)$" { 33 | return 301 https://$host/content-guide/$remaining_uri; 34 | } 35 | 36 | location /designstandards { 37 | proxy_pass http://127.0.0.1:8081/designstandards; 38 | proxy_http_version 1.1; 39 | proxy_redirect off; 40 | proxy_set_header Host playbook.cio.gov; 41 | proxy_set_header X-Real-IP $remote_addr; 42 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 43 | proxy_set_header X-Forwarded-Proto https; 44 | proxy_max_temp_file_size 0; 45 | 46 | proxy_connect_timeout 10; 47 | proxy_send_timeout 30; 48 | proxy_read_timeout 30; 49 | } 50 | 51 | location / { 52 | root /home/ubuntu/pages-generated; 53 | index index.html; 54 | default_type text/html; 55 | } 56 | 57 | location /deploy { 58 | proxy_pass http://localhost:5000/; 59 | proxy_http_version 1.1; 60 | proxy_redirect off; 61 | 62 | proxy_set_header Host $host; 63 | proxy_set_header X-Real-IP $remote_addr; 64 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 65 | proxy_set_header X-Forwarded-Proto https; 66 | proxy_max_temp_file_size 0; 67 | 68 | proxy_connect_timeout 10; 69 | proxy_send_timeout 30; 70 | proxy_read_timeout 30; 71 | } 72 | } 73 | 74 | server { 75 | listen 443 ssl spdy; 76 | server_name pages-staging.18f.gov; 77 | include ssl/star.18f.gov.conf; 78 | include new_relic/status.conf; 79 | 80 | include vhosts/auth-locations.conf; 81 | } 82 | 83 | server { 84 | listen 127.0.0.1:8080; 85 | server_name pages-staging.18f.gov; 86 | port_in_redirect off; 87 | 88 | location / { 89 | root /home/ubuntu/pages-staging; 90 | index index.html; 91 | default_type text/html; 92 | } 93 | } 94 | -------------------------------------------------------------------------------- /.about.yml: -------------------------------------------------------------------------------- 1 | --- 2 | # .about.yml project metadata 3 | # 4 | # Short name that acts as the project identifier (required) 5 | name: pages 6 | 7 | # Full proper name of the project (required) 8 | full_name: Pages 9 | 10 | # The type of content in the repo 11 | # values: app, docs, policy 12 | type: docs 13 | 14 | # Describes whether a project team, working group/guild, etc. owns the repo (required) 15 | # values: guild, working-group, project 16 | owner_type: project 17 | 18 | # Name of the main project repo if this is a sub-repo; name of the working group/guild repo if this is a working group/guild subproject 19 | parent: wg-documentation 20 | 21 | # Maturity stage of the project (required) 22 | # values: discovery, alpha, beta, live 23 | stage: live 24 | 25 | # Whether or not the project is actively maintained (required) 26 | # values: active, deprecated 27 | status: active 28 | 29 | # Description of the project 30 | description: Publishing platform for 18F sites a la GitHub Pages 31 | 32 | # Should be 'true' if the project has a continuous build (required) 33 | # values: true, false 34 | testable: false 35 | 36 | # Team members contributing to the project (required) 37 | # Items: 38 | # - github: GitHub user name 39 | # id: Internal team identifier/user name 40 | # role: Team member's role; leads should be designated as 'lead' 41 | team: 42 | - github: mbland 43 | role: lead 44 | - github: arowla 45 | 46 | # Partners for whom the project is developed 47 | #partners: 48 | #- 49 | 50 | # Brief descriptions of significant project developments 51 | #milestones: 52 | #- 53 | 54 | # Technologies used to build the project 55 | stack: 56 | - Ruby 57 | - Jekyll 58 | - Node.js 59 | 60 | # Brief description of the project's outcomes 61 | #impact: 62 | 63 | # Services used to supply project status information 64 | # Items: 65 | # - name: Name of the service 66 | # category: Type of the service 67 | # url: URL for detailed information 68 | # badge: URL for the status badge 69 | #services: 70 | #- 71 | 72 | # Licenses that apply to the project and/or its components (required) 73 | # Items by property name pattern: 74 | # .*: 75 | # name: Name of the license from the Software Package Data Exchange (SPDX): https://spdx.org/licenses/ 76 | # url: URL for the text of the license 77 | licenses: 78 | pages: 79 | name: CC0 80 | url: https://github.com/18F/team_api/blob/master/LICENSE.md 81 | 82 | # Blogs or websites associated with project development 83 | #blog: 84 | #- 85 | 86 | # Links to project artifacts 87 | # Items: 88 | # - url: URL for the link 89 | # text: Anchor text for the link 90 | links: 91 | - url: https://pages.18f.gov/ 92 | text: 18F Pages homepage 93 | - url: https://www.npmjs.com/package/18f-pages-server 94 | text: 18f-pages-server npm 95 | 96 | # Email addresses of points-of-contact 97 | contact: 98 | - url: mailto:michael.bland@acm.org 99 | text: Mike Bland 100 | - url: https://github.com/18F/pages/issues 101 | text: 18F/pages issues 102 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 18F Pages 2 | 3 | [18F Pages](https://pages.18f.gov/) is the serving host and publishing 4 | platform that [18F](https://18f.gsa.gov/) uses to prototype and publish many 5 | of its [Jekyll](http://jekyllrb.com/)-based and other statically-generated web 6 | sites. It works very similarly to [GitHub pages](https://pages.github.com/). 7 | 8 | This repo contains the Jekyll source for the https://pages.18f.gov/ home page 9 | itself. 10 | 11 | The 18F Pages publishing server is available as the [`18f-pages-server` 12 | npm](https://www.npmjs.com/package/18f-pages-server), the code for which 13 | resides in the [18F/pages-server 14 | repository](https://github.com/18F/pages-server/). Complete details on the 15 | publishing mechanism and server installation, configuration, and 16 | administration are available in the README posted on both of those pages. 17 | 18 | ## Reusability 19 | 20 | The server may be reused by other organizations, as it is completely 21 | configurable via the [`pages-config.json`](#pages-config) file. You may 22 | imagine replacing all instances of "18F" in the instructions that follow with 23 | your own organization's handle. 24 | 25 | ## Publishing to `pages.18f.gov` 26 | 27 | Published sites will appear as `https://pages.18f.gov/REPO-NAME`, where 28 | `REPO-NAME` is the name of the site's repository without the organization 29 | prefix. 30 | 31 | For example, `18F/guides-template` will publish to 32 | https://pages.18f.gov/guides-template/. 33 | 34 | The status of the most recent build attempt will be visible at 35 | `https://pages.18f.gov/REPO-NAME/build.log`. 36 | 37 | ### When to use this technique 38 | 39 | The one condition test: "Is this site going to be for public (non-18F) consumption? If yes, use pages.18F.gov." 40 | 41 | ### Adding a new site 42 | 43 | See the [18F Guides Template](https://pages.18f.gov/guides-template/) for 44 | step-by-step instructions on how to develop a site for 18F Pages and configure 45 | its GitHub repository for publishing. 46 | 47 | Alternatively, if you're an 18F team member who's already comfortable with 48 | Jekyll and GitHub, the short version is: 49 | 50 | - Create the `18f-pages` publishing branch. If you already have a `gh-pages` 51 | branch, you can do this on the command line via: 52 | ```sh 53 | $ git checkout -b 18f-pages gh-pages 54 | $ git push origin 18f-pages 55 | ``` 56 | or by clicking on the **Branch:** button on your repository's GitHub page, 57 | selecting `gh-pages`, clicking the button again, and entering `18f-pages` in 58 | the _Find or create a branch..._ box. 59 | - If your repo is primarily an 18F Pages site (as opposed to a project site 60 | with an `18f-pages` branch for documentation), you may optionally set the 61 | default branch on GitHub to `18f-pages`. 62 | - [Make sure all internal links are prefixed with `{{ site.baseurl 63 | }}`](https://github.com/18F/pages-server/blob/master/README.md#prefixing-jekyll-links-with--sitebaseurl-). 64 | This is essential for proper publishing to `https://pages.18f.gov/REPO-NAME`, 65 | though your local site will continue to serve correctly from 66 | http://localhost:4000/. 67 | - Push a change to the `18f-pages` branch to publish your site. The site will 68 | not appear when the branch is created, only after it is updated. 69 | 70 | For further information, read 71 | [the "Publishing" section of the 18F/guides-server 72 | README](https://github.com/18F/pages-server/blob/master/README.md#publishing) 73 | for a thorough explanation of the entire publishing mechanism. 74 | 75 | ### Staging area 76 | 77 | Any changes pushed to a `18f-pages-staging` branch will appear on 78 | `https://pages-staging.18f.gov`, which requires authenticated access. 79 | 80 | ## Administering `https://pages.18f.gov/` and `https://pages-staging.18f.gov/` 81 | 82 | ### 18F GitHub organization webhook 83 | 84 | There is a webhook configured for the 18F GitHub organization that will send 85 | push notifications from every 18F GitHub repository to 86 | `https://pages.18f.gov/deploy`. This enables every update to an `18f-pages` or 87 | `18f-pages-staging` branch in every 18F GitHub repository to automatically 88 | publish to `https://pages.18f.gov/` or `https://pages-staging.18f.gov/`, 89 | respectively. 90 | 91 | Individual 18F repositories _do not_ need to set up their own publishing 92 | webhooks, and any existing publishing webhooks should be removed. 93 | 94 | ### Getting access to `pages.18f.gov` 95 | 96 | **Note:** `pages.18f.gov` and `pages-staging.18f.gov` are the same machine. 97 | Both sites are served using the same `18f-pages-server` instance. 98 | 99 | - Get SSH access to `pages.18f.gov` via #devops. 100 | - For convenience, add the following stanza to `$HOME/.ssh/config`, replacing 101 | `$HOME` with the full path to your home directory: 102 | ``` 103 | Host 18f-pages 104 | Hostname pages.18f.gov 105 | User ubuntu 106 | IdentityFile $HOME/.ssh/id_rsa 107 | IdentitiesOnly yes 108 | ``` 109 | 110 | In the sections that follow, each set of command line instructions presumes 111 | that you have logged into `pages.18f.gov`. Alternatively, you may execute each 112 | command from your local machine by adding `ssh 18f-pages` as a prefix. 113 | 114 | ### Cloning the 18F/pages repository and installing the server 115 | 116 | Should `18f-pages-server` ever need to be re-installed, or installed on a new 117 | instance, log into the host via `ssh 18f-pages` and follow the 118 | [`18f-pages-server` installation instructions](https://github.com/18F/pages-server/blob/master/README.md#installation). 119 | 120 | Once the server is installed, clone the 18F/pages repository and run the server using [Forever](https://www.npmjs.com/package/forever): 121 | 122 | ```sh 123 | $ git clone git@github.com:18F/pages.git /home/ubuntu/pages 124 | $ forever start -l /var/log/18f-pages-server/pages.log -a /usr/local/bin/18f-pages /home/ubuntu/pages/pages-config.json 125 | ``` 126 | 127 | ### Upgrading the server 128 | 129 | Run the following command to upgrade `18f-pages-server` npm, and then follow 130 | the [instructions to restart the server](#restart): 131 | 132 | ```sh 133 | $ sudo npm upgrade -g 18f-pages-server 134 | ``` 135 | 136 | You should see output similar to the following upon success: 137 | 138 | ```sh 139 | /usr/local/bin/18f-pages -> /usr/local/lib/node_modules/18f-pages-server/bin/18f-pages 140 | 18f-pages-server@0.0.3 /usr/local/lib/node_modules/18f-pages-server 141 | ├── file-locked-operation@0.0.1 (lockfile@1.0.1) 142 | └── hookshot@0.1.0 (commander@2.3.0, lockfile@1.0.1, body-parser@1.8.4, 143 | express@4.9.8) 144 | ``` 145 | 146 | ### Updating the configuration 147 | 148 | The [`pages-config.json` configuration file from this 149 | repository](./pages-config.json) is the configuration for the 150 | `18f-pages-server`. The schema is fully-documented in [the "Generate and 151 | configure `pages-config.json` section of the `18f-pages-server` 152 | README](https://github.com/18F/pages-server/blob/master/README.md#pages-config). 153 | 154 | After changes to this file have been pushed or merged into the `18f-pages` 155 | branch on GitHub, run the following to pull the configuration updates onto 156 | `pages.18f.gov` then follow the [instructions to restart the server](#restart): 157 | 158 | ```sh 159 | $ cd /home/ubuntu/pages && git pull 160 | ``` 161 | 162 | _Note: When running from your local machine using the `ssh 18f-pages` 163 | prefix, this command must be surrounded by quotation marks._ 164 | 165 | ### Restarting the server 166 | 167 | To restart the server: 168 | 169 | ```sh 170 | $ forever restart /usr/local/bin/18f-pages 171 | ``` 172 | 173 | To validate that the update succeeded, print the last lines of the log file, 174 | which should look similar to the following: 175 | 176 | ```sh 177 | $ tail -n 2 /var/log/18f-pages-server/pages.log 178 | 18f-pages-server v0.0.3 179 | 18F pages: listening on port 5000 180 | ``` 181 | 182 | ### Setting up the `https://pages.18f.gov/` home page 183 | 184 | `pages-generated/index.html` is a symlink to 185 | `pages-generated/pages/index.html`, as explained in the 186 | ["Create a symlink to the `index.html` of the generated homepage" section of 187 | the 18F/pages-server 188 | README](https://github.com/18F/pages-server/blob/master/README.md#homepage-symlink). 189 | 190 | ### System configuration files 191 | 192 | Updating these files in the repository _does not_ update them on the server. 193 | Currently, server configurations should be updated directly, verified, then 194 | updated within the repository to maintain parity. 195 | 196 | #### logrotate.d 197 | 198 | The `/etc/logrotate.d/18f-pages-server` file controls the log rotation 199 | mechanism, `logrotate(8)`. This file is checked into this repository as 200 | [`_deploy/etc/logrotate.d/18f-pages-server`](./_deploy/etc/logrotate.d/18f-pages-server). 201 | 202 | #### Nginx 203 | 204 | The [Nginx](http://nginx.org/) configuration for both `https://pages.18f.gov/` 205 | and `https://pages-staging.18f.gov` is in the `/etc/nginx/vhosts/pages.conf` 206 | file, checked into this repository as 207 | [`_deploy/etc/nginx/vhosts/pages.conf`](./_deploy/etc/nginx/vhosts/pages.conf). 208 | 209 | This file is imported into `/etc/nginx/nginx.conf` and includes other files 210 | containing configuration directives for SSL, New Relic, and authentication. 211 | The paths to these other files are relative to `/etc/nginx`. These other files 212 | can be seen in the [`18F/hub nginx configuration 213 | directory`](https://github.com/18F/hub/tree/master/deploy/etc/nginx), as they 214 | are served from the same Nginx instance as `hub.18f.gov`. 215 | 216 | ## Contributing 217 | 218 | 1. Fork the repo (or just clone it if you're an 18F team member) 219 | 2. Create your feature branch (`git checkout -b my-new-feature`) 220 | 3. Commit your changes (`git commit -am 'Add some feature'`) 221 | 4. Push to the branch (`git push origin my-new-feature`) 222 | 5. Create a new Pull Request 223 | 224 | Feel free to [file an issue](https://github.com/18F/pages/issues) or to ping 225 | [@mbland](https://github.com/mbland) with any questions you may have, 226 | especially if the current documentation should've addressed your needs, but 227 | didn't. 228 | 229 | ## Public domain 230 | 231 | This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md): 232 | 233 | > This project is in the public domain within the United States, and copyright 234 | > and related rights in the work worldwide are waived through the [CC0 1.0 235 | > Universal public domain 236 | > dedication](https://creativecommons.org/publicdomain/zero/1.0/). 237 | > 238 | > All contributions to this project will be released under the CC0 dedication. 239 | > By submitting a pull request, you are agreeing to comply with this waiver of 240 | > copyright interest. 241 | --------------------------------------------------------------------------------