Skip to main content
Table of contents

Get started

Get an account

Your department, agency or team must have a GOV.UK PaaS account. This account is called an organisation, or org. Sign up for an org account at https://www.cloud.service.gov.uk/signup.

Once your department, agency or team has an org account, you will need a personal account. Ask your org manager to authorise the creation of your personal account.

The GOV.UK PaaS is hosted in 2 independent regions, London and Ireland.

By default, the GOV.UK PaaS team creates new accounts in the London region unless you request otherwise during sign up.

To provide you with an account, we need to store some personal data about you. Please see our privacy notice for details.

Once you have a personal account, you can access the GOV.UK PaaS admin tool for either the London or the Ireland region (requires sign in). This tool allows you to view and manage your orgs, spaces and users without using the command line. Your level of access depends on your user role permissions.

Contact us by emailing gov-uk-paas-support@digital.cabinet-office.gov.uk if you have any questions.

Trial and paid accounts

When your department, agency or team first signs up to GOV.UK PaaS, their account can be either a paid account or a free trial account.

With a trial account, your department, agency or team can:

However, your department, agency or team has a limited quota of resources, and cannot:

To set up custom domains and run production apps, your department, agency or team must have a paid account with GOV.UK PaaS.

To upgrade your department, agency or team’s account from trial to paid, contact us by emailing gov-uk-paas-support@digital.cabinet-office.gov.uk.

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:

  1. Download and install the Cloud Foundry CLI for your platform.

  2. 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.

Sign in to Cloud Foundry

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.

  1. 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.

  2. 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 either a Google or Microsoft 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

  1. Sign into the GOV.UK PaaS admin tool for London or Ireland.

  2. Select Set up Google/Microsoft single sign-on and then select Activate Google/Microsoft single sign-on.

  3. Get a URL to generate a temporary authentication code. If your org is hosted in London, run the following in the command line:

    cf login -a api.london.cloud.service.gov.uk --sso
    

    If your org is hosted in Ireland, run:

    cf login -a api.cloud.service.gov.uk --sso
    
  4. Go to the URL and select Continue under either Google or Microsoft.

  5. On the Sign in page, enter or select your email address.

  6. Enter your password and, if applicable, the 2-step verification code to generate a temporary authentication code.

  7. 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

Failed to sign in

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.

  1. 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.

  2. 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>
    
  3. 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.

  4. 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.

Use Cloud Foundry API version 3

Version 3 allows you to push an app with no downtime without having to use a blue-green deployment tool.

Warning Version 3 of the Cloud Foundry API is still in beta.

Refer to the Cloud Foundry documentation on the limitations of API version 3 for more information.

  1. 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.

  2. 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>
    
  3. 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.

  4. Create an app:

    cf v3-create-app APPNAME
    

    APPNAME is the unique name for your app that you specified in the manifest file.

    You only need to run this command if you’re creating a new app that uses version 3 of the API.

  5. Apply your created manifest file to your app:

    cf v3-apply-manifest -f PATH_TO_MANIFEST
    
  6. Push a zero downtime version of your app:

    cf v3-zdt-push APPNAME --wait-for-deploy-complete
    

    The command line will display a message when your app has finished deploying.

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.

Refer to the Cloud Foundry documentation on rolling app deployments for more information on version 3 of the Cloud Foundry API.