Deployment

Exercises 11.10-11.12. (Fly.io)

If you rather want to use other hosting options, there is an alternative set of exercises for Render.

11.10 Deploying your application to Fly.io

Setup your application in Fly.io hosting service like the one we did in part 3.

In contrast to part 3, in this part we do not deploy the code to Fly.io ourselves (with the command flyctl deploy), we let the GitHub Actions workflow do that for us.

Before going to the automated deployment, we shall ensure in this exercise that the app can be deployed manually.

So, create a new app in Fly.io. After that generate a Fly.io API token with the command

flyctl auth token

You'll need the token soon for your deployment workflow so save it somewhere (but do not commit that to GitHub)!

As said, before setting up the deployment pipeline in the next exercise we will now ensure that a manual deployment with the command flyctl deploy works.

A couple of changes are needed.

The configuration file fly.toml should be modified to include the following:

[env]
  PORT = "3000" # add this where PORT matches the internal_port below

[processes]
  app = "node app.js" # add this

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0
  processes = ["app"]

In processes we define the command that starts the application. Without this change Fly.io just starts the React dev server and that causes it to shut down since the app itself does not start up. We will also set up the PORT to be passed to the app as an environment variable.

We also need to alter the file .dockerignore a bit, the next line should be removed:

dist

If the line is not removed, the product build of the frontend does not get downloaded to the Fly.io server.

Deployment should now work if the production build exists in the local machine, that is, the command npm build is run.

Before moving to the next exercise, make sure that the manual deployment with the command flyctl deploy works!

11.11 Automatic deployments

Extend the workflow with a step to deploy your application to Fly.io by following the advice given here.

Note that the GitHub Action should create the production build (with npm run build) before the deployment step!

You need the authorization token that you just created for the deployment. The proper way to pass it's value to GitHub Actions is to use Repository secrets:

Now the workflow can access the token value as follows:

${{secrets.FLY_API_TOKEN}}

If all goes well, your workflow log should look a bit like this:

Remember that it is always essential to keep an eye on what is happening in server logs when playing around with product deployments, so use flyctl logs early and use it often. No, use it all the time!

11.12 Health check

Each deployment in Fly.io creates a release. Releases can be checked from the command line:

$ flyctl releases
VERSION	STATUS  	DESCRIPTION	USER           	DATE
v18    	complete	Release    	mluukkai@iki.fi	16h56m ago
v17    	complete	Release    	mluukkai@iki.fi	17h3m ago
v16    	complete	Release    	mluukkai@iki.fi	21h22m ago
v15    	complete	Release    	mluukkai@iki.fi	21h25m ago
v14    	complete	Release    	mluukkai@iki.fi	21h34m ago

It is essential to ensure that a deployment ends up in a succeeding release, where the app is in healthy functional state. Fortunately, Fly.io has several configuration options that take care of the application health check.

If we change the app as follows, it fails to start:

app.listen(PORT, () => {
  this_causes_error
  // eslint-disable-next-line no-console
  console.log(`server started on port ${PORT}`)
})

In this case, the deployment fails:

$ flyctl releases
VERSION	STATUS  	DESCRIPTION	USER           	DATE
v19    	failed  	Release    	mluukkai@iki.fi	3m52s ago
v18    	complete	Release    	mluukkai@iki.fi	16h56m ago
v17    	complete	Release    	mluukkai@iki.fi	17h3m ago
v16    	complete	Release    	mluukkai@iki.fi	21h22m ago
v15    	complete	Release    	mluukkai@iki.fi	21h25m ago
v14    	complete	Release    	mluukkai@iki.fi	21h34m ago

The app however stays up and running, Fly.io does not replace the functioning version (v18) with the broken one (v19).

Let us consider the following change

// start app in a wrong port
app.listen(PORT + 1, () => {
  // eslint-disable-next-line no-console
  console.log(`server started on port ${PORT}`)
})

Now the app starts but it is connected to the wrong port, so the service will not be functional. Fly.io thinks this is a successful deployment, so it deploys the app in a broken state.

One possibility to prevent broken deployments is to use an HTTP-level check defined in section http_service.http_checks. This type of check can be used to ensure that the app for real is in a functional state.

Add a simple endpoint for doing an application health check to the backend. You may e.g. copy this code:

app.get('/health', (req, res) => {
  res.send('ok')
})

Configure then an HTTP check that ensures the health of the deployments based on the HTTP request to the defined health check endpoint.

You also need to set the deployment strategy (in the file fly.toml) of the app to be canary. These strategies ensure that only an app with a healthy state gets deployed.

Ensure that GitHub Actions notices if a deployment breaks your application:

You may simulate this e.g. as follows:

app.get('/health', (req, res) => {
  // eslint-disable-next-line no-constant-condition
  if (true) throw('error...  ')
  res.send('ok')
})

Exercises 11.10-11.12. (Render)

If you rather want to use other hosting options, there is an alternative set of exercises for Fly.io.

11.10 Deploying your application to Render

Set up your application in Render. The setup is now not quite as straightforward as in part 3. You have to carefully think about what should go to these settings:

If you need to run several commands in the build or start command, you may use a simple shell script for that.

Create eg. a file build_step.sh with the following content:

#!/bin/bash

echo "Build script"

# add the commands here

Give it execution permissions (Google or see e.g. this to find out how) and ensure that you can run it from the command line:

$ ./build_step.sh
Build script

Other option is to use a Pre deploy command, with that you may run one additional command before the deployment starts.

You also need to open the Advanced settings and turn the auto-deploy off since we want to control the deployment in the GitHub Actions:

Ensure now that you get the app up and running. Use the Manual deploy.

Most likely things will fail at the start, so remember to keep the Logs open all the time.

11.11 Automatic deployments

Next step is to automate the deployment. There are two options, a ready-made custom action or the use of the Render deploy hook.

Deployment with custom action

Go to GitHub Actions marketplace and search for action for our purposes. You might search with render deploy. There are several actions to choose from. You can pick any. Quite often the best choice is the one with the most stars. It is also a good idea to look if the action is actively maintained (time of the last release) and does it have many open issues or pull requests.

Warning: for some reason, the most starred option render-action was very unreliable when the part was updated (16th Jan 2024), so better avoid that. If you end up with too much problems, the deploy hook might be a better option!

Set up the action to your workflow and ensure that every commit that passes all the checks results in a new deployment. Note that you need Render API key and the app service id for the deployment. See here how the API key is generated. You can get the service id from the URL of the Render dashboard of your app. The end of the URL (starting with srv-) is the id:

https://dashboard.render.com/web/srv-randomcharachtershere

Deployment with deploy hook

Alternative, and perhaps a more reliable option is to use Render Deploy Hook which is a private URL to trigger the deployment. You can get it from your app settings:

DON'T USE the plain URL in your pipeline. Instead create GitHub secrets for your key and service id: Then you can use them like this:

- name: Trigger deployment
  run: curl https://api.render.com/deploy/srv-${{ secrets.RENDER_SERVICE_ID }}?key=${{ secrets.RENDER_API_KEY }}

The deployment takes some time. See the events tab of the Render dashboard to see when the new deployment is ready:

11.12 Health check

All tests pass and the new version of the app gets automatically deployed to Render so everything seems to be in order. But does the app really work? Besides the checks done in the deployment pipeline, it is extremely beneficial to have also some "application level" health checks ensuring that the app for real is in a functional state.

The zero downtime deploys in Render should ensure that your app stays functional all the time! For some reason, this property did not always work as promised when this part was updated (16th Jan 2024). The reason might be the use of a free account.

Add a simple endpoint for doing an application health check to the backend. You may e.g. copy this code:

app.get('/health', (req, res) => {
  res.send('ok')
})

Commit the code and push it to GitHub. Ensure that you can access the health check endpoint of your app.

Configure now a Health Check Path to your app. The configuration is done in the settings tab of the Render dashboard.

Make a change in your code, push it to GitHub, and ensure that the deployment succeeds.

Note that you can see the log of deployment by clicking the most recent deployment in the events tab.

When you are set up with the health check, simulate a broken deployment by changing the code as follows:

app.get('/health', (req, res) => {
  // eslint-disable-next-line no-constant-condition
  if (true) throw('error...  ')
  res.send('ok')
})

Push the code to GitHub and ensure that a broken version does not get deployed and the previous version of the app keeps running.

Before moving on, fix your deployment and ensure that the application works again as intended.