DC/OS website

Environment	URL	Build Status
Production	https://dcos.io
Development	https://dev.dcos.io

Issue tracking is moving to the DCOS JIRA (Project: SITE). Issues on GitHub will be disabled soon.

Table of contents:

• Contribution Workflow
• Testing your updates locally
• Updating the documentation
• Managing redirects
• Promoting site to live
• Link checking
• Technology

Contribution Workflow

1. Create a repo fork in GitHub

2. Clone the dcos/dcos-website repo

3. Add repo fork as remote repo:

   git remote add fork https://github.com/<github-user>/dcos-website
   git fetch fork
   

4. Checkout the develop branch:

   git checkout develop
   

5. Create a new feature branch:

   git checkout -b feature/<feature-name>
   

6. Make local changes.

7. Test your changes locally.

8. Add and commit changes:

   git add -p .
   git commit
   

9. Rebase repo fork to include recent dcos/dcos-website:develop changes. Rebasing a repo (instead of merging) will keep your fork commit history clean and move all your changes to the top of the commit log.

   git fetch origin
   git pull --rebase origin develop
   

   Tip: May require resolving conflicts.

10. Push changes to repo fork feature branch:

    git push -u fork feature/<feature-name>
    

11. Create a pull request from the repo fork feature branch to dcos/dcos-website:develop.

Once changes are accepted and merged to the develop branch, CI will push the updates to https://dev.dcos.io/.

Testing your updates locally

1. Update the dcos-docs submodule:

   git submodule update --init --recursive
   

2. Build a local version of the doc site. The DC/OS website can be built locally using Node or run in an Nginx Docker container.

• Using Easy Mode

  1. Install Docker Toolkit

  2. Run dev server

     make
     

  3. Go to running server

• Using Node

  1. Install Node

  2. Install dependencies:

     npm install
     

  3. Launch local dev server:

     npm start
     

     (opens dev server in browser)

  4. Verify changes on localhost server (updates automatically when files are changed).

• Using an Nginx Docker image

  1. Install Docker Toolkit

  2. Configure your shell:

     eval $(/usr/local/bin/docker-machine env default)
     

  3. Build the website server Docker image:

     ci/docker-build-image.sh
     

  4. Run the website server in Docker:

     SERVER_CID="$(ci/docker-run.sh)"
     

  5. By default, the server runs on port 80. You can find the server IP by running

     docker-machine ip default
     

  6. Stop the website server:

     docker rm -f "${SERVER_CID}"
     

Updating the documentation

Prerequisite:

• You must have administrator privileges for the https://github.com/dcos/dcos-website repo.

• The dcos-docs submodule: must be updated.

  git submodule update --init --recursive
  

1. Check out the develop branch.

   $ git checkout develop

2. Pull the latest content from the develop branch.

   $ git pull

3. Create a branch off of develop for your changes. For example:

   $ git checkout -b bump-docs/11-3-16

4. Run the bump-docs script:

   scripts/bump_docs.sh

5. Commit and push your branch to dcos-website. For example:

   $ git push origin bump-docs/11-3-16

   Tip: git status will not show local changes.

6. Submit a PR to merge your branch to develop.

   

   You should see something like this:

   Important:

   • An automated link checker is run on all merges and PRs to dcos-website. This will take about 10 minutes. You can check the results here. Broken links will not block merging, but should be reviewed.
   • When this PR is merged, the staging server is built: https://dev.dcos.io/docs/.

7. After the changes have been previewed and accepted on https://dev.dcos.io/, go on to Promoting site to live.

Promoting site to live

To promote the dev site to live, rebase develop to master:

$ git checkout develop
$ git pull
$ git submodule update --init --recursive
$ ci/promote.sh

Continuous integration will handle deploying updates (ci/deploy.sh), updating redirects (ci/update-redirects.sh), and updating the S3 website config (ci/update-website-conifg.sh).

Tip: If you receive this error Found unstaged changes - Exiting, run the submodule update command:

$ git submodule update --init --recursive

Managing redirects

There are two types of redirects, stored in two different files:

• Page Redirects: https://github.com/dcos/dcos-website/redirect-files
• Prefix Redirects: https://github.com/dcos/dcos-website/redirect-prefixes

That both use following format:

/from/ /to/

Both types of redirects are processed and used in the S3, npm/gulp, and docker/nginx environments.

The "current" version of DC/OS that corresponds to /docs/latest/ is managed in the redirect-prefixes file.

Versioning

• To create a new version picker dropdown item, modify layouts/docs.jade and gulpfile.js.

• When a new version GAs, modify the redirect-prefixes file. For example, this denotes that 1.8 is the default version:

  /docs/latest/ /docs/1.8/
  

Link checking

Validating links requires building and running a local site. You can run a local site as a standalone process or alternatively as a part of a docs build.

1. Build the website server Docker image:

   ci/docker-build-image.sh
   

2. Start the website server in Docker and remember the container ID:

   SERVER_CID="$(PORT=3000 ci/docker-run.sh)"
   

3. Run link validation in Docker:

   ci/docker-validate-links.sh
   

4. Stop the website server

   docker rm -f "${SERVER_CID}"
   

Technology

Built using Metalsmith.

License and Authors

Copyright 2017 Mesosphere, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this repository except in compliance with the License.

The contents of this repository are solely licensed under the terms described in the LICENSE file included in this repository.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Authors are listed in AUTHORS.md file.