Thanks for checking out the uncontained.io guides! We’re excited to hear and learn from you. Your experiences will benefit others who read and use these guides.
We’ve put together the following guidelines to help you figure out where you can best be helpful.
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!
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.
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.
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/
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/.
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
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 See this article for more details on increasing open file limits in containers. |
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.ymlThis will result in the creation of a pipeline and deployment environments across several project:
-
uncontainedis where the Jenkins Pipeline will be deployed to. -
uncontained-devwill be used as the Development environment, where smoke tests are run. -
uncontained-testanduncontained-stageare 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-123Uncontained.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
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.
See our guide on contributing new content.
This site is the evolution of the OpenShift Playbooks site.
Migrating content from there to here is fairly straightforward, but involves some work.
-
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 -
Next, start the test site using the container image or native hugo.
-
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.
-
-
Examine front matter. Ensure
titleis reader friendly, and that thedaterepresents the date written, not the date migrated.
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.
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.
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.
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.