Tutorial

Deploying apps to IBM Code Engine from GitHub or local sources

A step-by-step IBM Code Engine deployment guide

By

Aishwarya Raj

IBM Cloud Code Engine is a fully managed, serverless platform designed to run containerized workloads with minimal delay and automatic scaling. Built on open-source technologies like Kubernetes and Knative, it offers developers extensive container tooling and workload portability.

By following the steps in this tutorial, you can deploy your application on Code Engine, for both initial and subsequent deployments.

This guide walks you through deploying a sample application using IBM Cloud Code Engine, detailing the required steps from forking the repository to completing the deployment process. It also covers how to re-deploy changes to the application and how to manage your application effectively.

Prerequisites

  • A GitHub account and a general understanding of GitHub
  • IBM Cloud account

    To complete this tutorial, you’ll need an IBM Cloud Pay-As-You-Go account. If you’re using a Lite account, you can upgrade by visiting your account settings. In the Account Upgrade section, choose Add credit card to switch to a Pay-As-You-Go account or select Upgrade for a Subscription account. For additional details, refer to upgrading your account.

In this tutorial, we will deploy a sample application from this GitHub repo: https://github.com/aish-raj/SampleApplication.git. You will need to fork this repo to create your own version of the repository.

Deployment tasks

This tutorial covers these tasks:

  1. Deploying from a GitHub repository
  2. Re-deploying changes to an application

Deploying from a GitHub repository

Deploying an application from a GitHub repository to IBM Cloud Code Engine is a straightforward process that involves configuring your source code to build and run as a containerized application. By following these steps, you can quickly set up and deploy your application directly from your repository, leveraging the automation and scalability provided by Code Engine. Here's how to get started:

  1. Open the Code Engine console.
  2. Click Start Creating to start the deployment process.
  3. Choose Application and enter a name for your application.
  4. Select Build container image from source code.

    • Enter the HTTPS URL of the GitHub repository of the app that you want to deploy. For the sample application, it would be https://github.com/your_github_username/SampleApplication.git.
    • Enter the SSH URL of the GitHub repository. For the sample application, it would be git@github.ibm.com:your_github_username/SampleApplication.git
  5. Add an SSH deploy key in the sample app GitHub repository.

    • Generate a new SSH key by running on your terminal:

       ssh-keygen -t ed25519 -C "your_email@example.com"
      
    • If this is the first time you are deploying this application, you must add the SSH key to ssh-agent:

       eval "$(ssh-agent -s)"
       touch ~/.ssh/config
      
    • Configure ~/.ssh/config:

       Host github.com
         AddKeysToAgent yes
         UseKeychain yes
         IdentityFile ~/.ssh/id_ed25519
      
    • If this is the first time you are deploying this application, you must add the SSH private key to ssh-agent:

       ssh-add --apple-use-keychain ~/.ssh/id_ed25519
      
    • Copy the SSH public key to the clipboard:

       pbcopy < ~/.ssh/id_ed25519.pub
      

      On Linux, use xclip or xsel (for example, xclip -sel clip < ~/.ssh/id_ed25519.pub), and on Windows, use clip in Command Prompt (for example, type ~/.ssh/id_ed25519.pub | clip).

  6. Add the deploy key in the GitHub repository.

    • Go to Settings > Security in your GitHub repository.
    • Under Deploy keys, click Add key, give it a title (for example, "Deploy Key"), and paste the copied key.

      Add Deploy keys

    • Optionally, save the private key to a file:

       cat ~/.ssh/id_ed25519 >> pvtkey.txt
      
  7. Specify the Code Engine build details. Back in Code Engine console, under Specify build details, set up Code Repo Access.

    • Click Create SSH Secret, name it (for example, secretnew), and insert the private key value from pvtkey.txt (you can check the path of this file in a terminal) or paste the private key value.
    • Set Branch name as main or the name of your branch, Context directory as / or foldername. (The Dockerfile should be present in this context directory.)
    • Choose SSH secret created (in our example, secretnew is the name of the SSH secret).

      Screen capture showing build details

    • Choose Build Strategy as Dockerfile.
    • Set Timeout as 10 minutes or 20 minutes depending on the size of your files.
    • Configure Build resources as needed. The size of the build defines how CPU cores, memory, and disk space are assigned to the build. A smaller build is less expensive, but typically also slower due to the lower number of CPU cores.
    • Configure access to the registry. Choose private.us.icr.io from the Registry server drop-down list.

      Registry server

      • Create a registry secret with IBM API Key credentials in the IBM Cloud console under Access (IAM) . Ensure the secret is created in the same region as your container registry. In the Code Engine console, locate the Field Registry Secret dropdown, click the arrow, select Create registry secret , and follow the prompts.For detailed instructions, see the IBM Code Engine documentation on creating registry secrets.
  8. Click Create to start the deployment process. Code Engine will validate your settings, fetch the source code from your GitHub repository, and build a container image using the specified registry secret. This process may take a few minutes, during which the platform compiles, packages, and prepares your application for deployment.

    Create

  9. After your application is created, on the Image start options tab, make sure the Listening port matches the Dockerfile’s port or your application's port (for example, 8080).

    Image start options

    The Optional Settings and Resource and Scaling sections are located on the left-hand side of the Code Engine application setup page, as shown in the screenshot below.

    Config

    Optional Settings is at the bottom of the page, allowing you to configure additional options such as environment variables, startup commands, and other customization details. The Resource and Scaling section is also visible in the same navigation pane, where you can define the compute resources (CPU, memory) and scaling parameters (minimum and maximum instances) for your application. These sections provide the flexibility to fine-tune your application before deployment.

    • Add Environment variables needed in Optional Settings Section.
    • Under the Resource and Scaling section, define the amount of CPU and memory resources for each instance. Also, add Ephemeral Storage based on the selected CPU and memory. For RAG applications, ensure you select larger storage (32 GB or 48 GB) due to the size of the embedding models.
    • Specify the range within which Code Engine should automatically scale the number of running instances. Choose 1 for both(Maximun Number of Instances and Minimum number of Instances).
  10. Wait for deployment to complete. Access your application by clicking Test application and then click on Application URL

    TestApplication

We have built two endpoints in FastAPI:

  • A GET endpoint to display "Hello World".

    Get

  • A POST endpoint that accepts a name in the payload and returns "Hello {name}".

    Post

Re-deploy code changes

Updating your application to reflect recent code changes is simple with IBM Cloud Code Engine. Once you’ve pushed your updated code to your GitHub repository, you can trigger a rebuild and redeploy the updated application.

Follow these steps to ensure the latest changes are built and deployed successfully:

  1. Go to the Code Engine console and locate your application.
  2. If you have any changes to deploy (once your code is pushed to GitHub), trigger a rebuild by selecting Rebuild. Click Rerun Build > Edit Build Details. Specify all your build details as needed, and then click Run Build and Deploy.

    Rebuild

    If you need to change environment variables or other configuration, no need to re-build, only re-deploy.

  3. After re-deployment is complete, verify your changes by accessing the application URL.

Deploying your application from local code to IBM Cloud Code Engine

Deploying directly from your local codebase to IBM Cloud Code Engine allows efficient container image management and streamlined deployment.

To install the IBM cloud CLI on your MacOS machine:

brew install ibm-cloud-cli

Alternatively, you can download the macOS installer from the IBM Cloud CLI download page and follow the instructions.

Optionally, you can use Podman as a drop-in replacement for Docker. (You must have Podman Desktop installed on your machine.) To do this, you can set up an alias, which will allow you to use docker commands, but they will be directed to Podman instead. To set up an alias, follow these steps:

  1. Open your terminal.
  2. Add the following alias to your ~/.bashrc file:

     echo "alias docker=podman" >> ~/.bashrc
    
  3. Apply the changes by sourcing the .bashrc file:

     source ~/.bashrc
    

Any time you run a docker command, it will be routed to Podman instead.

Now, let's move on to building and deploying your application.

  1. Create an API key from Access IAM in your IBM Cloud account.

    To create an API key, navigate to Manage > Access (IAM) > API Keys. Generate a new API key and save it.

  2. Log in to IBM Cloud from the CLI.

     ibmcloud login -apikey "your_api_key"
    
  3. Verify that you have the required IBM Cloud CLI Plugins.

     ibmcloud plugin list
    

    Then, install any of the missing plugins.

     ibmcloud plugin install code-engine
     ibmcloud plugin install container-registry
    
  4. Set your resource group and region for deployment.

    First, log in to IBM Container Registry:

     ibmcloud cr login
    

    Then, run the following command to set your resource group:

     ibmcloud target -g <resource_group>
    

    For example, to target the default resource group, run this command: ibmcloud target -g Default.

    Finally, set the region for your deployment.

     ibmcloud cr region-set
    

    When prompted, select the number (1-10) corresponding to your desired region.

    Select

  5. List all the projects and select the desired project name.

     ibmcloud ce project list
    
     ibmcloud ce project select -n  projectname
    
  6. Build and run the Docker image locally.

    The --arch arm64 flag is used because macOS (especially with Apple Silicon chips) uses ARM architecture. When building the image, it's important to account for this difference to ensure compatibility with IBM Cloud Code Engine's architecture.

     podman build  --arch arm64 -t imagename .
    

    Then, run a container to verify it.

     podman run -d --name container -p 8080:8080 imagename
    
  7. Tag the Docker image for IBM Cloud Container Registry.

     podman tag imagename us.icr.io/<your_namespace>/<reponame>
    

    For example, podman tag imagename private.us.icr.io/namespace/imagename

  8. Push the image to IBM Cloud Container Registry

     podman push us.icr.io/<your_namespace>/<reponame>
    
  9. Verify the image is in IBM Cloud Container Registry by visiting IBM Container Registry.

  10. Complete these additional deployment steps for Code Engine.

    Open the Code Engine Console. Under Applications, select Create Application. Choose Use an existing container image, specify the IBM Cloud Container Registry image, and configure the deployment settings (such as port and scaling, as mentioned above in Configuration Section).

    Following these steps will result in a successful deployment of your local application on IBM Code Engine, which is now live and manageable from the Code Engine dashboard.

Managing Container Registry storage by setting recurring policies

To prevent storage issues in your IBM Cloud Container Registry, it's a best practice to configure a recurring policy to retain only the most recent images in each repository. This ensures efficient use of storage by automatically cleaning up older, unused images.

By using a recurring policy, you realize these benefits:

  • Storage Optimization: Ensures that only the most recent images are retained, saving storage space.
  • Automatic Cleanup: Removes older, unused images from your registry without manual intervention, helping maintain a clean and manageable environment.

To set a recurring policy:

  1. Go to the IBM Cloud Container Registry Settings.
  2. In the Settings page, select the Namespace that you want to configure the recurring policy for.
  3. Under the Policy Type section, choose Retain only the most recent images in each repository.
  4. Click Set Recurring Policy to enable automatic cleanup of old images.

    ConatinerRegistry settings

You can customize the retention period based on your project's needs. It's recommended that you test this recurring policy in a staging environment before applying it in production to make sure that it aligns with your image management strategy.

Summary and next steps

In this tutorial, you learned how to deploy an application using IBM Code Engine, from the initial setup to handling updates and redeployments. The steps covered included configuring your GitHub repository, creating a registry secret, and managing build and deployment settings. Additionally, you explored how to trigger rebuilds to deploy code changes efficiently, ensuring your application stays up-to-date. By mastering these processes, you can confidently deploy and manage applications on Code Engine with ease.

For more learning, visit the IBMCode Engine documentation for Code Engine docs, troubleshooting, and an FAQ.