Platform.sh is now Upsun. Click here to learn more
Upsun User Documentation

hooks

Back to home

On this page

Try Upsun for 15 days
After that, enjoy the same game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
Activate your 15-day trial
¹Terms and conditions apply

A hooks dictionary that defines which commands run at different stages in the build and deploy process.

Optional in single-runtime and composable images.

There are three different hooks that run as part of the process of building and deploying your app. These are places where you can run custom scripts. They are: the build hook, the deploy hook, and the post_deploy hook. Only the build hook is run for worker instances, while web instances run all three.

The process is ordered as:

  1. Variables accessible at build time become available.
  2. Build flavor runs if applicable.
  3. Any dependencies are installed.
  4. The build hook is run.
  5. The file system is changed to read only, except for any mounts.
  6. The app container starts. Variables accessible at runtime and services become available.
  7. The deploy hook is run.
  8. The app container begins accepting requests.
  9. The post_deploy hook is run.
  1. Variables accessible at build time become available.
  2. The build hook is run.
  3. The file system is changed to read only, except for any mounts.
  4. The app container starts. Variables accessible at runtime and services become available.
  5. The deploy hook is run.
  6. The app container begins accepting requests.
  7. The post_deploy hook is run.

Note that if an environment changes by no code changes, only the last step is run. If you want the entire process to run, see how to manually trigger builds.

Writable directories during build Anchor to this heading

During the build hook, there are three writeable directories:

  • PLATFORM_APP_DIR: Where your code is checked out and the working directory when the build hook starts. Becomes the app that gets deployed.
  • PLATFORM_CACHE_DIR: Persists between builds, but isn’t deployed. Shared by all builds on all branches.
  • /tmp: Isn’t deployed and is wiped between each build. Note that PLATFORM_CACHE_DIR is mapped to /tmp and together they offer about 8GB of free space.

Hook failure Anchor to this heading

Each hook is executed as a single script, so they’re considered to have failed only if the final command in them fails. To cause them to fail on the first failed command, add set -e to the beginning of the hook.

If a build hook fails for any reason, the build is aborted and the deploy doesn’t happen. Note that this only works for build hooks – if other hooks fail, the app is still deployed.

Automated testing Anchor to this heading

It’s preferable that you set up and run automated tests in a dedicated CI/CD tool. Relying on Upsun hooks for such tasks can prove difficult.

During the build hook, you can halt the deployment on a test failure but the following limitations apply:

  • Access to services such as databases, Redis, Vault KMS, and even writable mounts is disabled. So any testing that relies on it is sure to fail.
  • If you haven’t made changes to your app, an existing build image is reused and the build hook isn’t run.
  • Test results are written into your app container, so they might get exposed to a third party.

During the deploy hook, you can access services but you can’t halt the deployment based on a test failure. Note that there are other downsides:

  • Your app container is read-only during the deploy hook, so if your tests need to write reports and other information, you need to create a file mount for them.
  • Your app can only be deployed once the deploy hook has been completed. Therefore, running automated testing via the deploy hook generates slower deployments.
  • Your environment isn’t available externally during the deploy hook. Unit and integration testing might work without the environment being available, but you can’t typically perform end-to-end testing until after the environment is up and available.