Test and Deploy

Testing and Development

At the moment you must publish your app in order to test it. We will introduce a local development environment in the future as we evolve the platform.

To test your changes, you must publish your app to the admin. This will create a new version of your app that you can test. You can use a separate CatalogIQ instance within your organization to make sure that the in-development version of your app doesn't break the production environment. We advise using separate git branches per environment to avoid any unwanted changes.

Deployment

To deploy your app, you must first publish it to the Admin. This will create a new version of your app that you can use in your instance. If the app is already installed on the instance, you will see that you can update it to the latest version when you access the Apps instance settings page in admin after publishing.

Only after actually installing the latest version on your instance will the changes be visible to the end users. We recommend that you always test your changes in a separate instance before deploying them to the production one.

Deployments can be done through the REST API which is useful for automating them in CI/CD workflows as well as on your local machine.

API Tokens

To deploy your app through the API you need to generate an API token first. You can do that via Pitcher Admin.

To create a new API key in CatalogIQ Admin:

1. Log in to CatalogIQ Admin
2. Click on your user avatar in bottom left corner of the page
3. Click on "Dev settings"
4. Click on "Create new API Key"
5. Enter the name of the key, e.g. "My Local Development Deployment Key"
6. Select key expiration date
7. Click "Create"
8. Copy the key and save it some place safe

WARNING

If you suspect that your key has been compromised, revoke it immediately.

WARNING

Remember to never commit your tokens to a git repository or store them in a public place. Remember to rotate your keys regularly and never share them with anyone. In case you suspect that your key has been compromised, revoke it immediately. If you use the key in CI/CD pipelines, make sure to store it securely as a secret.

Upload the application to CatalogIQ substituting ${PITCHER_API_KEY} with the API key you created in step 4 and ${PITCHER_DOMAIN} with the domain of your CatalogIQ instance:

Uploading to Pitcher CatalogIQ Admin

  curl -X POST \
    -H "X-API-Key: ${PITCHER_API_KEY}" \
    -H "charts-Type: multipart/form-data" \
    -F "file=@app.zip" \
    https://${PITCHER_DOMAIN}.my.pitcher.com/api/v1/apps/publish/

INFO

You can also use use the REST API documentation to upload the application through a web page.

Updating the App on the instance

As mentioned before, after publishing the app, you can update the app on the instance by going to the Apps instance settings page in admin and clicking the update button.

However, it is also useful to know that you can also update the app through the REST API. This is useful for automating the deployment process in your local environment. To do this you can use the following REST API call:

  curl -X POST \
    -H "X-API-Key: ${PITCHER_API_KEY}" \
    -H "Content-Type: multipart/form-data" \
    -F "instance_ids=${PITCHER_INSTANCE_ID}" \
    https://${PITCHER_DOMAIN}.my.pitcher.com/api/v1/apps/${APP_NAME}/install/

Note that $APP_NAME is the value of the name field in the app.json manifest of the app you want to update.