Switching App Domains

Page last updated:

This topic describes how to change the domain of an existing Pivotal Platform installation.

To change the domain of an existing Pivotal Platform installation:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the Pivotal Application Service (PAS) tile.

  3. Select Domains to see the current Apps domain for your PAS deployment.

    The page header says 'Domains'. Below this header is the text 'For help configuring these fields, see Configure Domains in Configuring PAS in the Pivotal documentation,' with 'Configure Domain' in blue letters to denote a clickable link. Below this text are two fields labeled 'System domain' and 'Apps domain', with red asterisks to denote that they are required fields. The 'System domain' field contains the text 'yoursystem.yourdomain.com'. The 'Apps domain' field contains the text 'yourapps.yourdomain.com'. At the bottom of the image is a rectangular blue button labeled 'Save'.

  4. In the terminal, run:

    cf login -a API-ENDPOINT
    

    Where API-ENDPOINT is the API endpoint for your PAS instance.

    The cf CLI prompts you for your Pivotal Platform username and password, as well as the org and space you want to access. If you do not know your API endpoint, see Identifying the API Endpoint for Your PAS Instance.

  5. To view the domains in the space, run:

    cf domains
    

    The command returns output similar to the following example:

    $ cf domains
    Getting domains in org your-org as admin...

    name status yourapps.yourdomain.com shared

    If you have more than one shared domain, ensure that the domain you want to change is at the top of the list before you apply the new domain to your PAS tile configuration. You can delete and re-create the other shared domains as necessary to push the domain you want to change to the top of the list. If you do this, make sure to re-map the routes for each domain. For more information, see Configuring Routes and Domains.

  6. To confirm that your apps are assigned to the domain you plan to change, run:

    cf routes
    

    The command returns output similar to the following example:

    $ cf routes
    Getting routes as admin ...

    space host domain apps your-space yourapp yourapps.yourdomain.com yourapp

  7. To create the new domain you want to use, run:

    cf create-shared-domain NEW-DOMAIN
    

    Where NEW-DOMAIN is the name you give the new domain.

    The command returns output similar to the following example:

    $ cf create-shared-domain newapps.yourdomain.com

    Creating shared domain newapps.yourdomain.com as admin... OK

  8. To map the new domain to your app, run:

    cf map-route APP-NAME NEW-DOMAIN -n HOST-NAME
    

    Where:

    • APP-NAME is the name of the app you want to map to the new domain.
    • NEW-DOMAIN is the domain to which you want to map your app.
    • HOST-NAME is the hostname of the URL for the route you are mapping.

      The command returns output similar to the following example:

      $ cf map-route yourapp newapps.yourdomain.com -n yourapp

      Creating route yourapp.newapps.yourdomain.com for org your-org / space your-space as admin... OK Adding route yourapp.newapps.yourdomain.com to app yourapp in org your-org / space your-space as admin... OK

      In this example, both the APP-NAME and HOST-NAME arguments are yourapp, since this is both the name of the app to which you are mapping a route and the intended hostname for the URL.

  9. Repeat the previous step for each app in this space. Afterward, check Apps Manager to confirm that the route URL has updated correctly for each app:

  10. Repeat the above steps for each space in your Pivotal Platform installation except for the System org, beginning with logging into the org and space and ending with confirming the URL update.

    Note: Ordinarily the System org contains only Pivotal Platform apps that perform utility functions for your installation. Pivotal does not recommend pushing apps to this org. However, if you have pushed apps to the System org, you must also repeat the above steps for these apps.

  11. Once you have confirmed that every app in every space has been mapped to the new domain, delete the old domain by running:

    cf delete-shared-domain OLD-DOMAIN
    

    Where OLD-DOMAIN is the old domain to delete.

    The command returns output similar to the following example:

    $ cf delete-shared-domain yourapps.yourdomain.com
    Deleting domain yourapps.yourdomain.com as admin...

    This domain is shared across all orgs. Deleting it will remove all associated routes, and will make any app with this domain unreachable. Are you sure you want to delete the domain yourapps.yourdomain.com?

    When prompted, type yes to confirm that you want to delete the domain.

  12. In the Domains pane of the PAS tile, enter the new domain in the Apps domain field. This configures PAS to use the new domain.

    The page header says 'Domains'. Below this header is the text 'For help configuring these fields, see Configure Domains in Configuring PAS in the Pivotal documentation,' with 'Configure Domain' in blue letters to denote a clickable link. Below this text are two fields labeled 'System domain' and 'Apps domain', with red asterisks to denote that they are required fields. The 'System domain' field contains the text 'yoursystem.yourdomain.com'. The 'Apps domain' field contains the text 'newapps.yourdomain.com'. At the bottom of the image is a rectangular blue button labeled 'Save'.

  13. Return to the Ops Manager Installation Dashboard.

  14. Click Review Pending Changes.

  15. Click Apply Changes. Apps that you push after your update finishes use this new domain.