Get started

Have an account

Your department, agency or team must have a GOV.UK PaaS account. This account is called an organisation, or org.

We are no longer able to provide trial accounts because the platform is being decomissioned. You can read the blog post announcement.

Set up the Cloud Foundry command line

GOV.UK PaaS is hosted on Cloud Foundry [external link]. You must use the Cloud Foundry command line interface (CLI) to manage your apps hosted on the GOV.UK PaaS. To set it up:

Download and install the Cloud Foundry CLI version 8 for your platform.
To check that it is installed correctly, run cf -v in the command line.

If it has installed correctly, you will receive the cf version X.X.X… confirmation message.

Depending on your network configuration, you might need to set an HTTP_PROXY environment variable for the CLI to connect. Contact your network administrator for your configuration settings.

Refer to the Cloud Foundry documentation on using the Cloud Foundry CLI with a proxy server for more information.

If you previously installed Cloud Foundry CLI version 7, you should upgrade to Cloud Foundry CLI version 8

You can sign in to Cloud Foundry using either your GOV.UK PaaS account information or the single sign-on function.

Use your GOV.UK PaaS account

The default method to sign in to Cloud Foundry is to use your GOV.UK PaaS account information.

If your org is hosted in London, run the following in the command line:
```
cf login -a api.london.cloud.service.gov.uk -u USERNAME
```
If your org is hosted in Ireland, run:
```
cf login -a api.cloud.service.gov.uk -u USERNAME
```
USERNAME is your personal GOV.UK PaaS account email address.
Enter your GOV.UK PaaS account password.

When you have signed in, run cf in the command line to see all available commands.

Use single sign-on

You can sign in to Cloud Foundry using the single sign-on function.

Using single sign-on makes managing your security, joining and leaving processes simpler by reducing the number of passwords or accounts you have to manage.

You must have a Google email address to use single sign-on. The email address must be the same as the one you use to sign into your GOV.UK PaaS account.

Enable single sign-on

Sign into the GOV.UK PaaS admin tool for the London region or the Ireland region.
Select Set up Google single sign-on and then select Activate Google single sign-on.
Get a URL to generate a temporary authentication code. If your org is hosted in the London region, run the following in the command line:
```
cf login -a api.london.cloud.service.gov.uk --sso
```
If your org is hosted in the Ireland region, run:
```
cf login -a api.cloud.service.gov.uk --sso
```
Go to the URL and select Continue under either Google.
On the Sign in page, enter or select your email address.
Enter your password and, if applicable, the 2-step verification code to generate a temporary authentication code.
Copy the generated temporary authentication code into the command line.

When you have signed in, you will see code similar to the following:

API endpoint:   https://api.london.cloud.service.gov.uk (API version: 2.136.0)
User:           john.smith@digital.cabinet-office.gov.uk
Org:            hmrc-prod
Space:          sandbox

If you make too many failed sign in attempts within a short amount of time, Cloud Foundry locks your account. While your account is locked, you cannot sign in.

Wait 5 minutes for the account lock to expire before trying to sign into Cloud Foundry again.

Make sure that no automated services, such as Jenkins, are trying to sign into Cloud Foundry using your account when your account is locked.

Deploy a test static HTML page

You can practice deploying an app by deploying a test static HTML page.

To deploy an app, you must select a target. This is a combination of an organisation and a space.

All orgs have a sandbox space for you to use when learning about the PaaS. When deploying a test static HTML page, you should target this sandbox space by running:
```
cf target -o ORGNAME -s sandbox
```
where ORGNAME is your org and sandbox is the name of the sandbox space.

If you deploy an app using the same name and target as an existing app, the original will be replaced. If you are not sure about where to deploy your app, consult the rest of your team or speak to the PaaS team by emailing gov-uk-paas-support@digital.cabinet-office.gov.uk.

In an empty directory, create an index.html file containing the following markup:.

<html>
  <head>
    <title>Static Site</title>
  </head>
  <body>
    <p>Welcome to the static site!</p>
  </body>
</html>

Create a manifest.yml file in the same directory as the index.html file. The manifest file tells Cloud Foundry what to do with your app.
```
---
applications:
- name: APPNAME
  memory: 64M
  buildpacks:
  - staticfile_buildpack
```
where APPNAME is the unique name for your app. You can run cf apps to see apps which already exist.

The memory line tells the PaaS how much memory to allocate to the app.

A buildpack provides app framework and runtime support. For example, if your app was written in Ruby, you would use the ruby_buildpack. In this example, we use the staticfile_buildpack for the static HTML page.
In the directory where you created the files, run cf push APPNAME to push the static HTML page to the GOV.UK PaaS.

If you do not specify the app name in cf push, the name specified in the manifest file is used.

The static HTML page is now available at your app domain.

For a production app, you should follow the documentation on deploying an app to production.

Deploying with zero downtime

Cloud Foundry supports deploying applications with zero downtime by performing rolling deploys.

Warning Rolling deploys with Cloud Foundry CLI version 6 are unsupported on GOV.UK PaaS.

To deploy an app, you must select a target. This is a combination of an organisation and a space.

All orgs have a sandbox space for you to use when learning about the PaaS. When deploying a test static HTML page, you should target this sandbox space by running:
```
cf target -o ORGNAME -s sandbox
```
where ORGNAME is your org and sandbox is the name of the sandbox space.

If you deploy an app using the same name and target as an existing app, the original will be replaced. If you are not sure about where to deploy your app, consult the rest of your team or speak to the PaaS team by emailing gov-uk-paas-support@digital.cabinet-office.gov.uk.

In an empty directory, create an index.html file containing the following markup:

<html>
  <head>
    <title>Static Site</title>
  </head>
  <body>
    <p>Welcome to the static site!</p>
  </body>
</html>

Create a manifest.yml file in the same directory as the index.html file. The manifest file tells Cloud Foundry what to do with your app.
```
---
applications:
- name: APPNAME
  memory: 64M
  instances: 3
  buildpacks:
  - staticfile_buildpack
```
where APPNAME is the unique name for your app. You can run cf apps to see apps which already exist.

The memory line tells the PaaS how much memory to allocate to the app.

The instances line tells PaaS how many instances of the app to run.

A buildpack provides app framework and runtime support. For example, if your app was written in Ruby, you would use the ruby_buildpack. In this example, we use the staticfile_buildpack for the static HTML page.
Perform a rolling deployment of your app:
```
cf push APPNAME --strategy rolling
```
The command line will display a message when your app has finished deploying.

Cloud Foundry will deploy 3 new instances of your application to handle new requests, allow connections to drain from the existing instances, and then retire them.