Installing Concourse

Concourse for VMware Tanzu is available for installation as a BOSH release. If you haven't read the Prerequisites and Background Information page, please do so before continuing.

This guide describes a process for installing VMware Concourse as a BOSH release for CI/CD usage. If you're interested in setting up Platform Automation, navigate to the Installing VMware Concourse for Platform Automation instead.

--8<-- "docs/snippets/bosh-setup.md"

--8<-- "docs/snippets/setup-concourse-bosh-deployment-repo.md"

--8<-- "docs/snippets/download-and-upload-concourse-release.md"

BOSH and Concourse variables

Installing Concourse requires setting certain configuration variables that depend on infrastructure. In this section we'll use the bosh cloud-config command to look up our available options, and create a file to store the aforementioned configuration variables. We'll include this file in our final deployment.

Run the following command to fetch the cloud configuration details of your IaaS and put them in a cloud-config.yml file to reference later:
```
bosh \
-e BOSH-ENVIRONMENT-ALIAS \
cloud-config > cloud-config.yml
```
!!! tip The following steps describe setting variables that are necessary for deployment in a yaml file. If you'd prefer to set them on the command line when you run bosh deploy, you could pass them in at that time with the --var KEY=VALUE flag and syntax. Click here to learn more about bosh deploy.
Create a file called variables.yml file to store your Concourse- and BOSH-related environment variables. You can do this using vim or your favorite editor:
```
vim variables.yml
```
Fill in the following variables:
```
---
deployment_name: DEPLOYMENT-NAME
azs:
- AVAILABILITY-ZONES
network_name: NETWORK-NAME
web_vm_type: VM-TYPE
worker_vm_type: VM-TYPE
db_persistent_disk_type: PERSISTENT-DISK-TYPE
db_vm_type: VM-TYPE
postgres_password: POSTGRES-PASSWORD
external_url: EXTERNAL-URL

web_ip: WEB-IP
local_user:
  username: USERNAME
  password: PASSWORD
external_host: EXTERNAL-HOST
encryption_key: DB-ENCRYPTION-KEY
```
Where:
- DEPLOYMENT-NAME is the name of your choice for your Concourse deployment
- AVAILABILITY-ZONES is an array of name that corresponds to azs in your cloud-config.yml file.
- NETWORK-NAME is the name of one of the networks in cloud-config.yml
- VM-TYPE is the name of one of the VM types in your cloud-config.yml file
- PERSISTENT-DISK-TYPE is the name of one of the disk types in cloud-config.yml
- POSTGRES-PASSWORD is the password of your choice for the PostgreSQL db used by Concourse
- EXTERNAL-URL is a url associated with the web_ip property (eg, http://WEB-IP:8080)
- WEB-IP is a non-reserved IP address for your deployment (eg, 1.1.1.1). Only required if ./cluster/operations/static-web.yml is used
- local_user.username your choice of username, used to log in to Concourse. Only required if ./cluster/operations/basic-auth.yml is used
- local_user.password is your choice of password, used to log in to Concourse.. Only required if ./cluster/operations/basic-auth.yml is used
- EXTERNAL-HOST is the domain to be used on the TLS certificate. Only required if ./cluster/operations/tls-vars.yml is used
- DB-ENCRYPTION-KEY is the key used to encrypt the Concourse database. Only required if ./cluster/operations/encryption.yml is used
!!! tip "Reserved IP Ranges" In some cases, you might need to modify the reserved IP ranges of your network on Ops Manager before choosing a web_ip for Concourse. For example, the reserved IP range is: 10.0.5.1-10.0.5.10, and you wish to set web_ip as 10.0.5.8, the new reserved IP range to set on Ops Manager would be: 10.0.5.1-10.0.5.7, 10.0.5.9-10.0.5.10

!!! tip "External URL" Concourse uses an external URL to facilitate communication between workers and ATCs.
```
 When deploying for the first time, you might not know the final external URL - for example, you may later want to add a load balancer, or change your configuration as you go.

 For now, choose any available URL to get started. You can always change this value later if you run into trouble or change your mind. To do so at any time, update the value in your variable files and redeploy.
```
Save and close the variables.yml file.

Set Up a Deployment

To configure Concourse for VMware Tanzu, do the following:

Prepare the Concourse deployment manifest.

You can write your own manifest or modify a template with your unique configuration. The concourse-bosh-deployment repository that we cloned earlier has an example manifest template in the concourse.yml file located at ./cluster/concourse.yml.

  For more information about **Cluster Concourse deployment**, see the `README.md` files at [concourse-bosh-deployment](https://github.com/concourse/concourse-bosh-deployment/blob/v7.4.0/cluster/README.md) in GitHub.

Prepare a cloud-config.yml file and upload it to your BOSH Director with bosh update-cloud-config.

Deploy Concourse with `bosh deploy`

To deploy your new Concourse, use the following information:

Your edited concourse manifest (eg, ./cluster/concourse.yml),
The versions file that comes with the concourse-bosh-deployment (eg, -l versions.yml),
Your environment variables (eg, -l variables.yml),
Any required operations files for your environment or Concourse setup.

The snippet below has a basic set of operations files, but you can add whatever options your unique deployment might require.
A --vars-store flag and a filename where BOSH can store your cluster credentials (eg, --vars-store cluster-creds.yml)

!!! tip "About the cluster-creds.yml file" BOSH creates this file for you if it does not already exist. If this is the case, you still need to specify a filename for BOSH to use. In the case that you already have an existing cluster-creds.yml file, specify it here so that BOSH does not re-create it.

Keep in mind that if you specify a filename that does not exist, and BOSH re-creates this file for you, it also re-creates things such as passwords or secrets that go inside the file.

When you are ready, move to your terminal and run the following bosh deploy commands:

bosh deploy \
-e BOSH-ENVIRONMENT-ALIAS \
-d CONCOURSE-DEPLOYMENT-NAME \
./cluster/concourse.yml \
-l versions.yml \
-l variables.yml \
-o ./cluster/operations/backup-atc.yml \
-o ./cluster/operations/basic-auth.yml \
-o ./cluster/operations/static-web.yml \
-o ./cluster/operations/privileged-https.yml \
-o ./cluster/operations/tls-vars.yml \
-o ./cluster/operations/tls.yml \
-o ./cluster/operations/encryption.yml \
--vars-store cluster-creds.yml

Make sure all your file paths are correct. For more information, see Deploying in the BOSH documentation.

!!! danger "Different Concourse deployments require different environment variables and operations files. If you get an error, check the error message for clues about additional variables that need to be set. Check out the open-source Concourse documentation for additional information."

!!! success "Upon successfully running your deploy script, a success message is displayed, and Concourse has been installed." Use the external URL that you specified in your variables.yml file to target your concourse with fly and view the Concourse web UI with command fly -t NEW-TARGET-NAME login -c http://WEB-IP:8080 -u USERNAME -p PASSWORD.

BOSH and Concourse variables

Set Up a Deployment

Deploy Concourse with bosh deploy

Deploy Concourse with `bosh deploy`