About cookies on this site Our websites require some cookies to function properly (required). In addition, other cookies may be used with your consent to analyze site usage, improve the user experience and for advertising. For more information, please review your options. By visiting our website, you agree to our processing of information as described in IBM’sprivacy statement. To provide a smooth navigation, your cookie preferences will be shared across the IBM web domains listed here.
Tutorial
Deploying apps to IBM Code Engine from GitHub or local sources
A step-by-step IBM Code Engine deployment guide
On this page
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
-
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:
- Deploying from a GitHub repository
- 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:
- Open the Code Engine console.
- Click Start Creating to start the deployment process.
- Choose Application and enter a name for your application.
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
- Enter the HTTPS URL of the GitHub repository of the app that you want to deploy. For the sample application, it would be
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
orxsel
(for example,xclip -sel clip < ~/.ssh/id_ed25519.pub
), and on Windows, useclip
in Command Prompt (for example,type ~/.ssh/id_ed25519.pub | clip
).
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.
Optionally, save the private key to a file:
cat ~/.ssh/id_ed25519 >> pvtkey.txt
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 frompvtkey.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/
orfoldername
. (The Dockerfile should be present in this context directory.) Choose SSH secret created (in our example,
secretnew
is the name of the SSH secret).
- 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.- 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.
- Click Create SSH Secret, name it (for example,
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.
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).
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.
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).
Wait for deployment to complete. Access your application by clicking Test application and then click on Application URL
We have built two endpoints in FastAPI:
A GET endpoint to display "Hello World".
A POST endpoint that accepts a
name
in the payload and returns "Hello {name}".
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:
- Go to the Code Engine console and locate your application.
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.
If you need to change environment variables or other configuration, no need to re-build, only re-deploy.
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:
- Open your terminal.
Add the following alias to your
~/.bashrc
file:echo "alias docker=podman" >> ~/.bashrc
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.
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.
Log in to IBM Cloud from the CLI.
ibmcloud login -apikey "your_api_key"
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
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.
List all the projects and select the desired project name.
ibmcloud ce project list
ibmcloud ce project select -n projectname
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
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
Push the image to IBM Cloud Container Registry
podman push us.icr.io/<your_namespace>/<reponame>
Verify the image is in IBM Cloud Container Registry by visiting IBM Container Registry.
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:
- Go to the IBM Cloud Container Registry Settings.
- In the Settings page, select the Namespace that you want to configure the recurring policy for.
- Under the Policy Type section, choose Retain only the most recent images in each repository.
Click Set Recurring Policy to enable automatic cleanup of old images.
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.