Skip to content
Permalink
master
Go to file
 
 
Cannot retrieve contributors at this time
362 lines (277 sloc) 13.8 KB

Contributing to Uncontained.io

Types of contributions we’re looking for

This project is an attempt at establish and document some guiding principles and, dare we say it, best practices in the open source emerging technology space. Currently that space, as we see it, is predominantly made up of technologies that enable DevOps practices, such as ``Cloud'' (API-automated Infrastructure), CI/CD tooling, container technologies, microservices frameworks, and probably more. This project was started by a community of thought leaders from Red Hat so if it initially appears as if this site is only about Red Hat technologies, it’s not intended to be, its just impassioned people writing about what they know.

There are also many ways you can directly contribute to the guides (in descending order of need):

  • Fix editorial inconsistencies, inaccuracies, or stale content

  • Add tutorials, examples, or anecdotes that help illustrate a point

  • Revise language to be more approachable and friendly

  • Propose a new guide (here’s how)

Interested in making a contribution? Read on!

Ground rules & expectations

Before we get started, here are a few things we expect from you (and that you should expect from others):

  • Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done". Try to listen to others rather than convince them that your way is correct.

  • Uncontained.io guides are released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.

  • If you open a pull request, please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution.

  • When adding content, please consider if it is widely valuable. Please don’t add references or links to things you or your employer have created as others will do so if they appreciate it.

Getting set up for local development

Before you begin contributing, its important to get your local machine set up to run and test the site. For convenience, we provide a container image that contains all of the development tools. The simplest way to run the image is as follows:

podman run -p 3000:3000 -p 3001:3001 quay.io/redhat-cop/uncontained-local-dev

Or, if you use Docker:

docker run -p 3000:3000 -p 3001:3001 quay.io/redhat-cop/uncontained-local-dev

This will run uncontained.io from an embedded copy of the source code baked into the image.

Building and Developing the Site

Uncontained.io uses the Hugo static site generator to translate Asciidoc into an HTML site. We wrap this functionality in Gulp to streamline the build and test process. Familiarity with Gulp and Node.js is expected if you want to be able to change the functionality of the build. Our Hugo + Gulp setup is based on the victor-hugo boilerplate.

If you are only interested in developing content, however, all you need is familiarity with Writing AsciiDoc.

All you need to get set up is to clone the repository.

git clone https://github.com/redhat-cop/uncontained.io.git
cd uncontained.io/

Running the Live Preview

The live preview provides an embedded server in which you can test the site locally, and watch changes being made as you develop. You can start the server, running from your local copy of the code using the container image:

podman run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  -p 3000:3000 -p 3001:3001 quay.io/redhat-cop/uncontained-local-dev

Or, if you use Docker:

docker run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  -p 3000:3000 -p 3001:3001 quay.io/redhat-cop/uncontained-local-dev

The container also accepts extra arguments which it feeds to npm. For example, if you’d like to also include draft content like hugo server --buildDrafts --buildFuture, we’ve created a script entry in our package.json for that:

podman run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  -p 3000:3000 -p 3001:3001 quay.io/redhat-cop/uncontained-local-dev \
  run start-preview

Or, if you use Docker:

docker run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  -p 3000:3000 -p 3001:3001 quay.io/redhat-cop/uncontained-local-dev \
  run start-preview

You should be able to view the site by browsing to http://localhost:3000/.

To open Browsersync browse to http://localhost:3001/.

Building the Site

The site build will simple generate all of the site html, css, javascript, etc. This is the process we use to build and publish the site.

podman run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  quay.io/redhat-cop/uncontained-local-dev \
  run build

Or, if you use Docker:

docker run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  quay.io/redhat-cop/uncontained-local-dev \
  run build

Running the Automated Tests

In order to validate that changes you’ve made haven’t led to any unforeseen issues, you can use the container image to run our automated tests.

podman run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  quay.io/redhat-cop/uncontained-local-dev \
  test

Or, if you use Docker:

docker run -u $(id -u) \
  -v ${PWD}:/uncontained.io:Z -it \
  quay.io/redhat-cop/uncontained-local-dev \
  test
Important

Some systems may experience errors during testing like the following:

[...]
      "/uncontained.io/container-images/local-dev/root/usr/local/bin": {
      "errno": -24,
      "code": "EMFILE",
      "syscall": "scandir",
      "path": "/uncontained.io/container-images/local-dev/root/usr/local/bin"
    }
  }
}
{ AssertionError [ERR_ASSERTION]: There are some files that cannot be accessed or parsed: [object Object][object Object]
    at depcheck (/uncontained.io/gulpfile.js:237:5)
  generatedMessage: false,
  name: 'AssertionError [ERR_ASSERTION]',
  code: 'ERR_ASSERTION',
  actual: false,
  expected: true,
  operator: '==' }
npm ERR! Test failed.  See above for more details.

This means you need to increase the open files limit in the container. This can be done by passing --ulimit nofiles=$(ulimit -n) to the podman run command. The ulimit value in the container cannot be any higher than the user’s open file limit (ulimit -n). A value of at least 10000 is recommended.

See this article for more details on increasing open file limits in containers.

Deploying to OpenShift (testing only)

The Uncontained.io Jenkins pipeline can be deployed and used purely for testing purposes. Our pipeline can be deployed to any OpenShift cluster, and is automated using OpenShift Applier. The following commands can be used to install Applier, log in to your OpenShift cluster, and deploy the pipeline.

ansible-galaxy install -r requirements.yml -p galaxy
oc login ...
ansible-playbook -i .applier/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml

This will result in the creation of a pipeline and deployment environments across several project:

  • uncontained is where the Jenkins Pipeline will be deployed to.

  • uncontained-dev will be used as the Development environment, where smoke tests are run.

  • uncontained-test and uncontained-stage are both promotion environments

If you need to customize the deployment (e.g. for testing a Pull Request), the Applier inventory supports a number of parameters to customize the deployment. The following command is an example of configuring the pipeline to build from an alternative fork and branch. For other possible parameters, see all.yml.

ansible-playbook -i .applier/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml -e source_repo=https://github.com/etsauer/uncontained.io.git -e source_ref=feature-123

Deploying to OpenShift (production process)

Uncontained.io is built and hosted on OpenShift, and deployed using OpenShift Applier

Run the following to pull in applier:

ansible-galaxy install -r requirements.yml -p galaxy

Log into your Prod OpenShift cluster, and run the following command.

$ oc login <prod cluster> ...
$ ansible-playbook -i .applier-prod/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml

One of the things that was created by ansible is a ServiceAccount that will be used for promoting your app from Dev to Prod. We’ll need to extract its credentials so that our pipeline can use that account.

$ TOKEN=$(oc serviceaccounts get-token promoter -n field-guides-prod)

We need to create the the prod-api-credentials param file so our pipeline will be able to verify a successful deployment to production.

$ echo "TOKEN=${TOKEN}
API_URL=<API_URL>
REGISTRY_URL=<REGISTRY URL>
SECRET_NAME=other-cluster-credentials" > .openshift/params/prod-cluster-credentials

Now, deploy your pipeline and dev environment to your development cluster:

oc login <dev cluster>
ansible-playbook -i .applier/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml -e filter_tags=staging,prod

Contributing Content

If you’d like to contribute, start by searching through the GitHub issues and pull requests to see whether someone else has raised a similar idea or question.

If you don’t see your idea listed, and you think it fits into the goals of this guide, do one of the following: * If your contribution is minor, such as a typo fix, open a pull request. * If your contribution is major, such as a new article or category, start by opening an issue first. That way, other people can weigh in on the discussion before you do any work.

Contributing a new article

See our guide on contributing new content.

Migrating Content from OpenShift-Playbooks

This site is the evolution of the OpenShift Playbooks site.

Migrating content from there to here is fairly straightforward, but involves some work.

  1. A migration script can be used to translate documents from the openshift-playbooks repo.

    Usage: ./migrate-doc.sh [path/playbook-doc] [path/uncontained-doc]

    Example: ./migrate-doc.sh continuous_delivery/external-jenkins-integration.adoc articles/external-jenkins-integration.adoc

  2. Next, start the test site using the container image or native hugo.

  3. Navigate to the content you migrated and ensure that:

    • all content renders correctly

    • there are no broken links (we recommend using a link checker like this one for Firefox or this one for Chrome)

    • if the guide or article links to other guides, or articles, we suggest you migrate those as well.

  4. Examine front matter. Ensure title is reader friendly, and that the date represents the date written, not the date migrated.

Helping us with Site Styling, User Experience, etc.

The styling for the site is contained within a Hugo Theme. The source code for the theme is located in this repo at ./site/themes/uncontained.io.

Specifically, the code for our HTML Layouts can be found in ./site/themes/uncontained.io/layouts/. The CSS code can be found in ./site/themes/uncontained.io/src/scss.

See Building and Developing the site for instructions on how to perform local testing of changes.

Style guide

This site is written in asciidoc format and is built using Asciidoctor. If you’re writing content, see the style guide to help your prose match the rest of the Guides.

Contribution review process

This repo is currently maintained by @jaredburck, @etsauer, and @sabre1041, who have commit access. They will likely review your contribution. If you haven’t heard from anyone in 10 days, feel free to bump the thread or @-mention a maintainer or @redhat-cop/cant-contain-this to review your contribution.

Community

Discussions about uncontained.io takes place within this repository’s Issues and Pull Requests sections and Trello’s Cant-Contain-This board. Red Hatter’s can also find us on RocketChat’s #cant-contain-this channel. Anybody is welcome to join these conversations. There is also a mailing list for regular updates.

Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation.

You can’t perform that action at this time.