concourse / docs

concourse documentation and website

Concourse: the continuous thing-doer.

Concourse is an automation system written in Go. It is most commonly used for CI/CD, and is built to scale to any kind of automation pipeline, from simple to complex.

Concourse is very opinionated about a few things: idempotency, immutability, declarative config, stateless workers, and reproducible builds.

The road to Concourse v10

Concourse v10 is the code name for a set of features which, when used in combination, will have a massive impact on Concourse's capabilities as a generic continuous thing-doer. These features, and how they interact, are described in detail in the Core roadmap: towards v10 and Re-inventing resource types blog posts. (These posts are slightly out of date, but they get the idea across.)

Notably, v10 will make Concourse not suck for multi-branch and/or pull-request driven workflows - examples of spatial change, where the set of things to automate grows and shrinks over time.

Because v10 is really an alias for a ton of separate features, there's a lot to keep track of - here's an overview:

Feature	RFC	Status
set_pipeline step	✔ #31	✔ v5.8.0 (experimental)
Var sources for creds	✔ #39	✔ v5.8.0 (experimental), TODO: #5813
Archiving pipelines	✔ #33	✔ v6.5.0
Instanced pipelines	✔ #34	✔ v7.0.0 (experimental)
Static across step	🚧 #29	✔ v6.5.0 (experimental)
Dynamic across step	🚧 #29	✔ v7.4.0 (experimental, not released yet)
Projects	🚧 #32	🙏 RFC needs feedback!
load_var step	✔ #27	✔ v6.0.0 (experimental)
get_var step	✔ #27	🚧 #5815 in progress!
Prototypes	✔ #37	⚠ Pending first use of protocol (any of the below)
run step	🚧 #37	⚠ Pending its own RFC, but feel free to experiment
Resource prototypes	✔ #38	🙏 #5870 looking for volunteers!
Var source prototypes		🚧 #6275 planned, may lead to RFC
Notifier prototypes	🚧 #28	⚠ RFC not ready

The Concourse team at VMware will be working on these features, however in the interest of growing a healthy community of contributors we would really appreciate any volunteers. This roadmap is very easy to parallelize, as it is comprised of many orthogonal features, so the faster we can power through it, the faster we can all benefit. We want these for our own pipelines too! 😆

If you'd like to get involved, hop in Discord or leave a comment on any of the issues linked above so we can coordinate. We're more than happy to help figure things out or pick up any work that you don't feel comfortable doing (e.g. UI, unfamiliar parts, etc.).

Thanks to everyone who has contributed so far, whether in code or in the community, and thanks to everyone for their patience while we figure out how to support such common functionality the "Concoursey way!" 🙏

Installation

Concourse is distributed as a single concourse binary, available on the Releases page.

If you want to just kick the tires, jump ahead to the Quick Start.

In addition to the concourse binary, there are a few other supported formats. Consult their GitHub repos for more information:

• Docker image
• BOSH release
• Kubernetes Helm chart

Quick Start

$ wget https://concourse-ci.org/docker-compose.yml
$ docker-compose up
Creating docs_concourse-db_1 ... done
Creating docs_concourse_1    ... done

Concourse will be running at 127.0.0.1:8080. You can log in with the username/password as test/test.

⚠️ If you are using an M1 mac: M1 macs are incompatible with the containerd runtime. After downloading the docker-compose file, change CONCOURSE_WORKER_RUNTIME: "containerd" to CONCOURSE_WORKER_RUNTIME: "houdini". This feature is experimental

Next, install fly by downloading it from the web UI and target your local Concourse as the test user:

$ fly -t ci login -c http://127.0.0.1:8080 -u test -p test
logging in to team 'main'

target saved

Configuring a Pipeline

There is no GUI for configuring Concourse. Instead, pipelines are configured as declarative YAML files:

resources:
- name: booklit
  type: git
  source: {uri: "https://github.com/vito/booklit"}

jobs:
- name: unit
  plan:
  - get: booklit
    trigger: true
  - task: test
    file: booklit/ci/test.yml

Most operations are done via the accompanying fly CLI. If you've got Concourse installed, try saving the above example as booklit.yml, target your Concourse instance, and then run:

fly -t ci set-pipeline -p booklit -c booklit.yml

These pipeline files are self-contained, maximizing portability from one Concourse instance to the next.

Learn More

• The Official Site for documentation, reference material, and example pipelines (which no longer live in this repository).
• The Concourse Tutorial by Stark & Wayne is great for a guided introduction to all the core concepts.
• See Concourse in action with our production pipelines
• Hang around in the GitHub discussions or in Discord.
• See what we're working on on the project board.

Contributing

Our user base is basically everyone that develops software (and wants it to work).

It's a lot of work, and we need your help! If you're interested, check out our contributing docs.

docs's Issues

Search drop down does not disappear when clicking on a result in the current page

Steps to reproduce

1. Go on any page (e.g. https://concourse-ci.org/tasks.html)
2. Search for something that's part of the page (e.g. inputs if using Tasks page)
3. Click on the result from the drop down

Expected result

It scrolls to the correct spot and the drop down disappears

Actual result

Additional details

Chrome 72.0

Restructure the Concourse docs

The way that our docs are currently structured, it can be hard for some of our users to use. It is not very straightforward or easy to find where certain docs are. One example of a suggestion, all the actual docs or the place that many people would go straight to is in the "Reference" section, but it might be confusing since "Reference" sections can mean citations in webpages. Another suggestion was to bring back the one-page docs in order for faster lookup through CTRL-F.

These two points are just a couple of places that we can start at for restructuring and improving our docs. Currently, our docs is one of the main pain points of many of our users and we should try to make it as easy and extensive as possible.

This will probably be a long running issue, I'm just opening this to keep track of ideas and work that I will do to improve our docs.

Documentation versioning

Feature request

It would be nice to have docs for different concourse versions, like a dropdown list box where the documentation for a specific concourse version can be selected.

This would make it easier to check if certain features are available for that version. Take resource_types params as an example, it was added only in v3.7.0 and it is not available for older versions.

Concourse link broken from http://docs.pivotal.io/

Concourse link broken, https://concourse.ci/introduction.html

fly pause-resource incorrect redirect

The link (from here): https://concourse-ci.org/managing-resources.html#fly-pause-resource
goes to check-resource instead of going to a page for fly pause-resource

Components run into each other on reasonable desktop browser size on download page

At half-width on the large Mac, (1195px width browser) the release notes page has components that run into each other. Decreasing the browser a bit more snaps into the next responsive threshold.

AWS Secrets Manager's environment name mismatch

I'm using concourse-ci version 5.0.0

I found the environment variable of AWS_REGION, which describe inhttps://concourse-ci.org/aws-asm-credential-manager.html, didn't work.

Some clue here:
concourse/concourse@5d30023
After try-n-error, I found that changing env setting from "AWS_REGION" to "CONCOURSE_AWS_SECRETSMANAGER_REGION" solve my problem.
I guess AWS SSM credential manager have the same problem, and this might apply to them, too.
So, I report the issue here and hope the document can be updated if the fix was verified.

Regards.

Document registration of team-specific workers

Hey,

I couldn't find a good reference in our docs to give around the possibility and consequences of using team-specific workers.

It seems to me that it'd be useful to note:

• how it affects scheduling (e.g. concourse/concourse#1865 (comment)), and
• the behavior of check containers in the presence of such specialized containers (there's a bit around complications here https://concourse-ci.org/global-resources.html#complications-with-reusing-containers , but it'd be nice to see that clearly when wondering about providing a team worker or not).

Wdyt?

Thanks

Add Google Analytics tagging to Search Bar

Currently, we don't have GA tagging in place to view what users are searching for within concourse-ci.org. Given the structure of our internal search, we will need to add some level of event tagging in order to see what users are searching for.

Create a Community Guides section

I think we have enough links that we consistently link out that we should collect them into a single place. For example, I've already done this in the Pivotal Concourse for PCF documentation: https://docs.pivotal.io/p-concourse/guides.html

In addition to the guides listed there, we can add:

• Concourse Badges http://engineering.pivotal.io/post/concourse-badges/ and related issue concourse/concourse#2086
• https://www.digitalocean.com/community/tutorials/how-to-install-concourse-ci-on-ubuntu-16-04
• https://www.digitalocean.com/community/tutorial_series/setting-up-and-using-concourse-ci-on-ubuntu-16-04
• https://www.digitalocean.com/community/tutorials/how-to-set-up-continuous-integration-pipelines-with-concourse-ci-on-ubuntu-16-04
• https://www.digitalocean.com/community/tutorials/ci-cd-tools-comparison-jenkins-gitlab-ci-buildbot-drone-and-concourse
• https://www.digitalocean.com/community/tutorials/how-to-secure-concourse-ci-with-ssl-using-nginx-on-ubuntu-16-04

Search functionality buries my intuitive first result for "Vault"

I wanted to reference the Vault docs, so searched "vault", only to see "Using Vault" as the 15th result after the 14 Vault config flags, thus pushing it below the fold on my screen. My intuition tells me that "Using Vault" is a more likely desired page than the flags (especially since all the flag results are inside the "Using Vault" section, which I didn't know would be the case until I clicked on them).

A proposed change would be to prioritize "larger" headers over "smaller" headers. I also noticed that the underlining for "Using Vault" in the search didn't underline the "u" in "Vault" and instead underlined the "u" in "Using", so maybe there's some low-hanging fruit where the letter is getting eagerly consumed and results in a poor match?

(p.s. Using Concourse 4.1 and lovin' it. Thanks for all the hard work getting 4.x out!)

Vague chaining jobs example

The "Chaining jobs" example here:

docs/lit/reference/pipelines.lit

Lines 94 to 119 in 51ff49f

	\codeblock{yaml}{{{
	---
	resources:
	- name: booklit
	type: git
	source:
	uri: https://github.com/vito/booklit
	branch: master
	jobs:
	- name: unit
	plan:
	- get: booklit
	trigger: true
	- task: unit
	file: booklit/ci/test.yml
	- name: build
	plan:
	- get: booklit
	passed: [unit]
	trigger: true
	- task: unit
	file: booklit/ci/build.yml
	}}}
	}

...is slightly vague in that it references a unit 4 different times. It isn't immediately clear what the unit in the build passed: stage refers to - it ultimately refers to the job name but it would be easier if these had different names for clarity.

Document the new Bitbucket Auth

edtan did some work to get Bitbucket auth working a while back and we should probably write some docs on how to configure Bitbucket as an auth provider

Sidebar Subsection Heirarchy

Currently the left sidebar displays one primary menu persistently, but can also display submenus. These submenus have the same style as the primary menu, so their style does not make it clear that they are hierarchically different than the primary menu. See my comment below for a walkthrough of how the sidebar renders in different situations.

Recommendations

I understand that I don't fully understand the reasoning behind Booklit's rendering of parent and children menus, so I am going to make two separate recommendations, one that would be a larger change (and I am not sure is possible) and a second one that is a smaller change (but I am confident is possible and would still be an improvement).

Option 1 (preferred)

• Remove the blue highlight that shows the current page. The underline and darker text color is enough of a marker to show the current page.
• Nest child nodes within parent nodes to avoid repetition of titles and to show hierarchy. Nesting and indenting children may seem like a bad solution given that sidebar width is a limited resource, but the current use of numbering is effectively functioning as an indent since it increases by two additional characters with each successive child (see figure A below).
• Decrease the opacity to 50% of the text for all parent nodes (in order to bring the current menu into highlight).
• Change the color of the line that comes down from the triangle point when a menu is open (color: #D6D6D6).
• Remove the numbering from, preferably all, but at least the 3rd and 4th level child nodes (no need for "5.6.2.1").

Option 2

• Remove the numbering from (at least) the 3rd and 4th level child nodes (no need for "5.6.2.1").
• If you decide to keep the numbers, then change their color to be lighter than the titles themselves (font-color: #D6D6D6).
• Remove the blue highlight that shows the current page. The underline and darker text color is enough of a marker to show the current page.
• Remove the line that comes down from the triangle point when a menu is open.
• Decrease the opacity to 50% of the text for all parent nodes (in order to bring the current menu into highlight).

Figure A

Showing that the numbering system is effectively an indent for child menus:

Confusion if we are looking at the tutorial or documentation.

I was looking at how to reach the tutorial from the concourse site. Looking at the image snapshot above I thought I was in the tutorial, but I was looking at the documentation.

I will leave how you want to change the UI to the people who know more. Also, it could make sense to add a sentence or two as well on the homepage about the where to find the tutorial even if you fix the links.

Search functionality considers each letter as a token instead of the word

I'm trying to search for information about spaces on the website.

It seems that each character is considered a token for the search criteria, instead of the whole word. I would expect to find zero results if there are no mentions of 'space' or a page that talks about spaces.

Concourse site should handle 404s in a nicer way

The current site is powered by booklit; its useful in converting booklit markdown into html pages. However, since all it does is generate html files, it doesn't have some of the nice functions like 404 redirects!

In the instance of a 404, we should send the user to a 404 page letting them know the page no longer exists, instead of a nasty nginx error

Document how to pass data between steps in a job

I would expect to see how to pass data between steps in a job here:
https://concourse-ci.org/jobs.html
and/or
https://concourse-ci.org/steps.html

But both are silent on this important detail. We should document that the way to pass data between steps is file-based. Each job is run in a dedicated directory where get resources and task outputs are stored, that later steps can access data written by earlier steps, in sub directories named after the name of the get resource or task output. Does that sound about right? I will try to create a PR for this later if nobody beats me to it.

Unknown command quickstart

When running:
$> wget https://concourse-ci.org/docker-compose.yml
$> docker-compose up

Receiving the errror:

concourse_1 | Unknown command `quickstart'. Please specify one command of: land-worker, retire-worker, web or worker

It appears that: command: quickstart is not a valid command for the docker-compose file.

Concourse from quick start does not work as expected

Following the quick start tutorial I'm getting the following errors after pulling the images is completed:

concourse-db_1  | 2018-09-23 20:20:01.602 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
concourse-db_1  | 2018-09-23 20:20:01.602 UTC [1] LOG:  listening on IPv6 address "::", port 5432
concourse-db_1  | 2018-09-23 20:20:01.669 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
concourse-db_1  | 2018-09-23 20:20:01.793 UTC [62] LOG:  database system was shut down at 2018-09-23 20:20:01 UTC
concourse-db_1  | 2018-09-23 20:20:01.832 UTC [1] LOG:  database system is ready to accept connections
concourse_1     | {"timestamp":"1537734003.144883156","source":"atc","message":"atc.db.failed-to-open-db-retrying","log_level":2,"data":{"error":"dial tcp 172.20.0.2:5432: connect: no route to host","session":"3"}}
concourse_1     | {"timestamp":"1537734009.174848795","source":"atc","message":"atc.db.failed-to-open-db-retrying","log_level":2,"data":{"error":"dial tcp 172.20.0.2:5432: connect: no route to host","session":"3"}}

I had it running around 2 months ago I think. I'm confused why concourse is trying to connect on 172.20.0.2.
I tried removing the images and pulling the again with no luck.

Missing Caching and Retention Documentation

I'd love to learn more about how resources and task images are cached. These documents are currently empty.

https://concourse-ci.org/caching-and-retention.html

No documentation for Kubernetes credential manager

Just found out that there's a Kubernetes creds plugin, which is completely undocumented. Might help to add a bit about this.

Google Analytics loaded via web.archive.org (?)

Hi, I noticed today the Concourse website is loading the Google Analytics JS not from Google, but rather web.archive.org (and an 18 month old version at that).

This isn't a pattern that I've seen before... Is it deliberate?

Looks like the change that introduced this is 7bd3123#diff-a5f78e1b30834c93b8395568d2022764.

Do a better job explaining the value proposition of Concourse and how it differentiates itself

Do a better job explaining the value proposition of Concourse and how it differentiates itself. This is related to the conversation thread here concourse/concourse#1927

In the old site we had an explicit "Concourse Vs" section where we spent a bunch of time and paragraphs describing ourselves against another system

In the new site (and new approach), we removed that section completely because:

1. We wanted to stop describing ourselves relative to other systems
2. We wanted to do a better job describe why Concourse is great as a standalone CI/CD system

Our first approach was to simply list the key wins of Concourse on the homepage. This doesn't seem to be enough and we should add more content around those points. Maybe start with expanding on each of the key points:

• Configuration as Code: why is this great and why is it preferable over other ways to configure pipelines
• Visualization: why is it so important to have a nice visualization? How does that help teams with their CI/CD? Are there any other interesting benefits to bring up
• Reproducibility: What makes Concourse so good at having reproducible builds.
• Local iteration: fly hijack is a really powerful tool, we might want to spend more time diving into that
• Integrations: Lots to talk about here. There's a world beyond just the git resource that we can really dig into

Maybe we could also benefit from a Use Cases section as well?

Including Community Resources on our website

We've actually got a bunch of community resources out there that folks don't know about; and I think it could use some advertising. I think it makes sense to load them into https://concourse-ci.org/community.html

Here's my initial list of resources:

Concourse up https://github.com/EngineerBetter/concourse-up
Concourse Forumla https://github.com/marco-m/concourse-ci-formula
BUCC https://github.com/starkandwayne/bucc
Concourse Summary https://github.com/dgodd/concourse-summary
Concourse Helm Chart https://github.com/kubernetes/charts/tree/master/stable/concourse

Document how to provide lists via environment variables

Writing this on behalf of @wendorf

Feature Request

What challenge are you facing?

I wanted to provide a list of local users via environment variable, but didn't know how. My intuition, to use commas to separate, was correct, but I only learned that after embarrassingly asking in the forums and being told my guess was right. :)

A Modest Proposal

The CLI --help (which, as far as I know, is the only place that documents that environment variables can be used?) has a section describing how to specify lists in environment variables. It'd be extra nice if it explained how to include commas in the values without splitting. (e.g. if my org name happened to be comma,fans).

Release Note tweaks for Concourse 5.0.0 before release

docs/lit/release-notes/v5.0.0.lit

Line 4 in 7d0d2e9

\note{feature,breaking}{

• Finish adding in remaining features from https://project.concourse-ci.org/release/concourse, specifically the Fewest Build Container placement strategy

• Regarding the breaking change for --allow-all-users is there anything we need to mention for pre-upgrade? does the upgrade take care of this for you? What is the expected behavior? if you had it its removed so if you didn't have auth on it you need to ask an admin to attach something to it?

• same question around the removal of direct worker registration. What does that upgrade path look like. Do we automatically flip direct into forwarded?

Document LDAP Configuration Properties

#147 brings the addition of some LDAP auth options on set-team

We should modify https://concourse-ci.org/install.html#auth-config to include LDAP parameters which can be found in the source code, the web binary property descriptions or on the bosh.io docs https://bosh.io/jobs/atc?source=github.com/concourse/concourse-bosh-release&version=4.2.2#p%3dldap_auth

Content strategy rework

Note: this issue is being made a little late. All work here is done on the humble branch, and this issue is tracking what's left to do.

Needed for MVP

General

• Skim around and watch for anything that seems "jarring" - look for things that were moved around quickly without being finessed into its new context (if needed).
• Look for code blocks whose content overflows into the margin (too long)
• Need a reference to Security and mailing list
• Link to the blog!
• Still need a "get started in 5 minutes" flow.

Front Page

• Show current pipeline UI, not beta
• Better blurb; "It's ..." feels weak for being in such a prominent place. What else can we say here? Maybe nothing? Maybe a link to the About page?

"About"

• "How can I help?" section may feel a bit out of place.

"Downloads"

• Needs design for the release notes (i.e. fix/feature/breaking)
• Replace with single "Download" page optimizing for quick access to binaries for latest release (link to separate page for older releases?)

"Install"

Majorly rethink focus here and maybe subsume into single "Download/Install" page. Focus on binary, link to GitHub repos for more targeted methods (i.e. concourse-deployment for BOSH, concourse-docker for Docker), something for Kubernetes.

• Get rid of BOSH section; just link to concourse-deployment repo somewhere prominent.
  • We don't want to teach people BOSH. may be better to just focus on people that are already familiar with it and can just take the deployment repo and run with it. current approach scares some people as they assume they have to learn BOSH.
• Get rid of the Docker section; delegate to concourse-docker repo.
• Get rid of "Single VM" section; use Docker as the single-command getting-started (NOTE: this depends on concourse/concourse#2069).
• To replace "single VM" quick start, implement vmware-archive/bin#40
• Tag versions of concourse-deployment and have releases link to the appropriate tag

Not needed for MVP

"Builds"

• Any other useful stuff to put here?
• Fix broken asides

"Pipelines"

• Describe what pipeline-y things happen to configured resources and jobs.

"Jobs"

• Describe their scheduling in more detail.

"Resources"

• Describe their lifecycle, when they're checked, etc.

"Administration"

• intro? This is currently just a list of fly commands.

"Metrics"

• Refresh; it's very out of date and still refers to Riemann

"Worker Pools"

• Remove; don't think it's very useful and it's very BOSH oriented.

"Web UI"

• pipeline web-ui breakdown
• dashboard

"Contributing"

• ways to contribute
• getting started with docs
• getting started with code contribution
• Concourse CLA

"Community Mentions"

• some way to showcase who's using Concourse

Rename Tutorials to Tutorials & Tools and add in `OfCourse` from resources

Rename Tutorials to Tutorials & Tools and add in OfCourse from resources. This is a followup to the PR #137 where I promised to make this change

I liked the older UI more

The previous UI for the site was extremely easy to search and pleasing to the eye.

Please consider incorporating it back.

Document how vault approle is used

If someone knowledgeable could fill in any gaps, I'd like to create a PR to address my own concerns with the documentation.

Without reading source code, it's difficult to tell how concourse uses the vault approle because the approle is somewhat complex and the concourse documentation is currently lacking some context. In particular we can help steer a vault admin creating an approle for concourse.

I believe these are the approle parameters which may factor in:

• secret_id_num_uses
• secret_id_ttl
• token_num_uses
• token_ttl
• token_max_ttl
• period

source: https://www.vaultproject.io/api/auth/approle/index.html#secret_id_num_uses

From what I gather (please let me know if this is wrong):

When the ATC starts with --vault-auth-backend approle it does not have a, or load a previous, vault token. So for this reason the approle secret id is always required and should never expire. So secret_id_ttl and secret_id_num_uses should be set as null (empty string).

The ATC will then use the approle id and secret id to create a token, and will try to refresh that token after CONCOURSE_VAULT_AUTH_BACKEND_MAX_TTL. But it will never try to get a different token while the ATC process is running. Because the ATC process might run for 1 second or 5 years, you might as well treat this token as a lifetime periodic token. And so you should set period accordingly - something on the order of hours or days might give concourse time to renew its token despite faults/failures. Therefore you can set token_ttl and token_max_ttl as empty strings.

Changes to Sidebar Navigation

The left sidebar is both the primary way to navigate the docs as well as the primary organizational schema for the docs. In order to divide the Concourse docs up more clearly into goal-driven categories, we propose the following:

The list could change from this current state:

to this new state:

Docs

1. About
2. Setup & Operation
3. Concepts
4. Tutorials
5. Reference
6. Contribute
7. Community
8. Trademarks

in which the Download and Install sections would now be subsections of Setup & Operations, the Docs section would be renamed Reference, and the Architecture section would be renamed Concepts.

To dos:

• Rename title of sidebar from Concourse to Docs
• Create new section called Setup & Operation
• Create six sections under Setup & Operation: Download, Install, Getting Started, Operations, Team Management, and Administration (the last three are currently 4.8-4.10 under Docs and the "Getting Started" section can be copied from the home page)
• Rename Architecture to Concepts and move to third position
• Add empty sections within Concepts to explain what is a task, job, a resource, etc
• Create new section called Tutorials
• Link that section out directly to Stark and Wayne or, if thats not possible, write a short explanation of why we are linking out, and then link out in the body of the page.
• Rename Docs to Reference and move to fifth position
• Create a new empty page to be the Docs landing page (separate from the Concourse home page)

Download Page

The current download page requires me to scroll down in order to see the latest version and associated release notes (on a 1080p screen), I feel the current logos and sections for the download links (Linux/Mac OS X etc) are way too big and take up a lot of space.

I have no idea if it's possible but maybe the logos could be reduced a little bit in size and maybe have the layout with two columns for the download links?
Another option (again no idea if possible) would be to have two tabs in the download section, one with download links and another one with release notes.

Quick Start / Tutorial on homepage broken

Right now, the quick start box on the home page offers a docker-compose setup, and then invites the reader to follow the examples in the https://concoursetutorial.com tutorial.

Following the instructions, the tutorials do not work due to authentication issues with the web site. (Fly appears to work fine.)

The problem appears to be that the docker-compose.yml off the home page pulls the latest docker image, which appears to have authentication issues, whereas the tutorial is pinned to 3.4.1 and working.

To avoid confusion, the box should probably be renamed Tutorial or "Tutorial Quick Start" or similar, and use the docker-compose.yml from the tutorial Git repo. Essentially, the instructions from
https://concoursetutorial.com/#getting-started should be copied or referenced.

It might also be worthwhile pointing out the Quick Start section from https://concourse-ci.org/install.html#quickstart. This quick start however is much more complicated that then tutorial setup, and I'd recommend concentrating on having the working tutorial be featured prominently on the home page. The quality of the tutorial is a major asset to the project, from my very fresh experience.

"Docs" section is unreachable

Hi. This link leads to a 404: https://concourse-ci.org/docs.html

Not sure where that link should lead. Let me know where it should lead please and I will send a pull request straight away. ;)

typo

eiher => either
in https://concourse-ci.org/database-schema.html#resource_types-table

Further extend Vault docs (and other cred mgrs) to demonstrate credential usage

see #99

The 'new look' (not sure since when?) looks awful on wider screen

Everything is smashed together in the left-side of the screen. This is kind of ugly and impractical. The navigation menu on the left, for example could easily use some extra space (so it doesn't have to wrap as much and is easier to read and less ugly). And also the content on the right feels like it is bit narrower than is pleasant to read. So when you have the extra space, why not use it?

See image, it speaks for itself:

Website should redirect to HTTPS

By default we seem to serve HTTP. Eg: http://concourse.ci/metrics.html

We should always redirect to HTTPS.

Documenting the upcoming RBAC feature

With the upcoming release of RBAC, we need to update the site where relevant on how to configure roles on users. Here's a rough list of concepts we need to cover

General Notes

• Breakdown of the roles and their descriptions
  • Admin
  • Owner
  • Member
  • Viewer
• Members of main with role owner are admins
• All declared users in main team on start are automatically `admins

Creating Teams

• Default role of adding users/groups to teams is to be owner
• Specify roles through -c
• Role configuration syntax

Maintenance

• Viewing Team/Role membership

Fly intercept rendering overlap

Hi !
As you can see on the image below, fly intercept documentation rendering overlaps. I've tried on firefox (v55) and on chronium (v64).

Docs Landing Page

Currently the docs landing page functions more as a table of contents, detailing the titles of all the subsections of content. Inspired by Rust's documentation landing page (https://www.rust-lang.org/en-US/documentation.html), we would like to add short descriptions of each section of docs to the landing page in order to help with wayfinding and scannability. The idea is shown below with dummy copy:

• Create eight sections corresponding to new sidebar

• Write draft copy for eight sections

• Get team feedback on section copy

• Add links to individual subsections within copy

Concourse's live pipeline link missing?

Could you provide a link to concourse's live pipeline somewhere? I'm having trouble finding it. Or was it omitted because it's no longer available or not public?

Incomplete and Wrong: Concourse GitHub Auth Install Instructions

I took quite a while to figure out that this section from the GitHub Auth does not work:

"First you need to create an OAuth application on GitHub.

The callback URL will be the external URL of your Concourse server with /sky/issuer/callback appended. For example, Concourse's own CI server's callback URL would be https://ci.concourse-ci.org/sky/issuer/callback."

I do not know when /sky/issuer/callback was correct. However, for me it did not work at all. What actually has to be appended is /auth/github/callback. In addition, it would be nice to mentioned that https://ci.concourse-ci.org/auth/github/callback has to be inserted into the Authorization callback URL field in GitHub. An example screenshot can be found here: concourse/concourse#780 (comment)

Without the /auth/github/callback/ I received the Redirect URI mismatch error from GitHub.

Furthermore, the Configuring the client section is incomplete, because you also have to specify the --external-url <hostname> parameter or if you use the Helm chart set concourse.externalURL: "<hostname>" in your values.yaml to your hostname. The hostname has to be in the form http(s)://<your-domain>.<tld>:<port>/. For example: https://ci.concourse-ci.org:8080/.

Concourse site should allow basic redirects

With the handover to the new site, we made some changes to the names of specific pages and the layout of information. Since Concourse is a 3+ year old project there are a lot of links floating around; it would be nice if we can somehow re-route the old URLs to the new URLs.

An easy example of this is the Downloads page concourse/concourse#2159
Another could be smartly re-directing fly command URLs to the new URLs

The "search" feature of concourse-ci.org needs some love (e.g. zero results for "pinning")

Concourse 5 replaced "resource pausing" with "resource pinning". This is a fundamental aspect of Concourse, but searching for "pin" or "pinning" in the search bar on the top right of the website gives 0 results, although actually there is some text in the release notes in the https://concourse-ci.org/download.html page.

Not finding "pinning" is just an example; I remember other cases where I was looking for a Concourse concept in the search bar and had to fall back to various google search incantations to find it.

This is unfortunate because this means that also if the documentation of a feature/concept exists, it is actually invisible to somebody who doesn't already know it well.

"Aside" blockquote and content looked haphazard and made me confused

The Problem
The "aside" on this page that describes how to target powershell for intercepting a job on a Windows worker was confusing to me because it is sorting floating off on its own. I wasn't sure how I should understand this information in relation to the main body.

Questions that arose in my mind were, is this section just misplaced? Should it be in the main body or is it intentionally separate? What part of the body is it intended to comment on?

A Modest Proposal
Perhaps the aside class can be a bit wider, or have a bit more separation from the body? Or maybe give it a light background color?

Its showing up like this in chrome:

Maybe it could be like this?

Open to suggestions.

Hello world small improvement

IMHO it might be easier to follow (not that it is that hard :P) if a small description about login was added something like login > selecting *main* team > clicking login as there is no password prior to refreshing the page as stated at

docs/lit/using-concourse/hello-world.lit

Line 55 in 60c4c72

If you refresh the \link{main page}{http://192.168.100.4:8080}, you should

specially because the UI, when logged out, shows the default message:

no pipelines configured
first, download the CLI tools:
then, use fly set-pipeline to set up your new pipeline

which could lead into thinking that the previous set pipeline fly -t lite set-pipeline -p hello-world -c hello.yml command had failed.

Concourse 5.0 Docs todo

Here's a short list of Concourse 5.0 Documentation TODOs pre-release:

• Release Notes
• RBAC
  • Installing
  • set-team
  • RBAC Matrix
• Global Resource
  • Concepts
  • BOSH.io docs
• Container Placement Strategy
• Task Params / Vars
• Resource Pinning
  • Fly
  • Pause version Removal