IBM Cloud Docs
Deploying your app from repository source code

Deploying your app from repository source code

You can deploy your application directly from source code that is located in a Git repository with the IBM Cloud® Code Engine console and CLI. Find out what advantages are available when you build your image with Code Engine.

Deploying your app from repository source code from the console

You can deploy your application directly from source code with the console.

Before you begin, plan for your build. You can also find tips for creating a Dockerfile.

Code Engine can automatically push (upload) images to IBM Cloud® Container Registry namespaces in your account and even create a namespace for you. To upload images to a different Container Registry account or to a private Docker Hub account, see Accessing container registries.

For more information about required permissions for accessing image registries, see Setting up authorities for image registries.

  1. Open the Code Engine console.
  2. Select Let's go.
  3. Select Application.
  4. Enter a name for the application. Use a name for your application that is unique within the project.
  5. Select a project from the list of available projects. You can also create a new one. Note that you must have a selected project to deploy an app.
  6. Select Source code.
  7. Click Specify build details.
  8. Select a source repository, for example https://github.com/IBM/CodeEngine. Because we are using sample source that does not require credentials, select None for the Code repo access. You can optionally provide a branch name. If you do not provide a branch name and you leave the field empty, Code Engine automatically uses the default branch of the specified repository. Click Next.
  9. Select a strategy for your build and resources for your build. For more information about build options, see Planning your build. Click Next.
  10. Select a container registry location, such as IBM Registry Dallas to specify where to store the image of your build output. If your registry is private, you must set up access to it.
  11. Provide registry information about where to store the image of your build output. Select an existing Registry secret or create a new one. If you are building your image to a Container Registry instance that is in your account, you can select Code Engine managed secret and let Code Engine create and manage the secret for you.
  12. Select a namespace, name, and a tag for your image. If you are building your image to an IBM Cloud Container Registry instance that is in your account, you can select an existing namespace or let Code Engine create and manage the namespace for you.
  13. Click Done.
  14. Modify any runtime settings or environment variables for your app. For more information about these options, see Options for endpoint visibility of apps and Options for deploying an app.
  15. Click Create.
  16. After your build run is submitted, the built container image is sent to Container Registry and then your application pulls the image and deploys for you. After the application status changes to Ready, you can test the application. Click Test application and then click Send request in the Test application pane. To open the application in a web page, click Application URL.

Build runs that complete are ultimately automatically deleted. When your build run is based on build configuration, this build run is deleted after 3 hours if the build run is successful. If the build run is not successful, this build run is deleted after 48 hours.

Now that you have deployed your application, you can view information about application revisions and any running instances, and configuration details.

Deploying your app from repository source code with the CLI

You can deploy your application directly from repository source code with the CLI. Use the app create command to both build an image from your Git repository source, and deploy your application to reference this built image.

Before you begin

In this scenario, Code Engine builds an image from your Git repository source, automatically uploads the image to your container registry, and then creates and deploys your app to reference this built image. You need to provide only a name for the app and the URL to the Git repository if the image is to be located in an IBM Cloud® Container Registry account. In this case, Code Engine manages the namespace for you. However, if you want to use a different container registry, then you must specify the image and a registry secret for that container registry. For a complete listing of options, see the ibmcloud ce app create command.

For more information about required permissions for accessing image registries, see Setting up authorities for image registries.

The following example application create command creates and deploys the myapp app, which references an image that is built from the https://github.com/IBM/CodeEngine build source. This command automatically builds the image and uploads the image to an IBM Cloud® Container Registry namespace in your account and the application references this built image. By specifying the --build-context-dir option, the build uses the source in the helloworld directory. This example command uses the default dockerfile strategy, and the default medium build size. Because the branch name of the repository is not specified with the --build-commit option, Code Engine automatically uses the default branch of the specified repository.

ibmcloud ce application create --name myapp --build-source https://github.com/IBM/CodeEngine --build-context-dir helloworld

Example output

Creating application 'myapp'...
Submitting build run 'myapp-run-220411-13abcdefg'...
Creating image 'private.us.icr.io/ce--abcde-4svg40kna19/app-myapp:220411-1756-if8jv'...
Waiting for build run to complete...
Build run status: 'Running'
Build run completed successfully.
Run 'ibmcloud ce buildrun get -n myapp-run-220411-13abcdefg' to check the build run status.
Waiting for application 'myapp' to become ready.
Configuration 'myapp' is waiting for a Revision to become ready.
Ingress has not yet been reconciled.
Waiting for load balancer to be ready.
Run 'ibmcloud ce application get -n myapp' to check the application status.
OK

https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud

Notice the output of the application create command provides information on the progression of the build run before the app is created and deployed.

In this example, the built image is uploaded to the ce--abcde-4svg40kna19 namespace in Container Registry.

The following table summarizes the options that are used with the app create command in this example. For more information about the command and its options, see the ibmcloud ce app create command.

Table 1. Command description
Option Description
--name

The name of the application. Use a name that is unique within the project. This value is required.

  • The name must begin with a lowercase letter.
  • The name must end with a lowercase alphanumeric character.
  • The name must be 63 characters or fewer and can contain letters, numbers, and hyphens (-).
--build-source The URL of the Git repository that contains your source code; for example, https://github.com/IBM/CodeEngine.
--build-context-dir The directory in the repository that contains the buildpacks file or the Dockerfile. This value is optional.

The following output shows the result of the application get command for this example, including information about the build.

Example output

[...]
Name:          myapp  
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
Project Name:  myproject  
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
Age:           2d15h
Created:       2022-04-14T16:10:11-04:00
URL:                https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.4svg40kna19.svc.cluster.local
Console URL:        https://cloud.ibm.com/codeengine/project/us-south/01234567-abcd-abcd-abcd-abcdabcd1111/application/myapp/configuration
Status Summary:  Application deployed successfully

Environment Variables:    
    Type     Name             Value  
    Literal  CE_API_BASE_URL  https://api.us-south.codeengine.cloud.ibm.com  
    Literal  CE_APP           myapp  
    Literal  CE_DOMAIN        us-south.codeengine.appdomain.cloud  
    Literal  CE_PROJECT_ID    abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
    Literal  CE_REGION        us-south  
    Literal  CE_SUBDOMAIN     abcdabcdab
Image:                  private.us.icr.io/ce--27fe9-4svg40kna19/app-myapp:220414-2010-sqsoj
Resource Allocation:
  CPU:                1
  Ephemeral Storage:  400M
  Memory:             4G
Registry Secrets:
  ce-auto-icr-private-us-south

Revisions:
  myapp-00001:
    Age:                23m
    Latest:             true
    Traffic:            100%
    Image:              private.us.icr.io/ce--27fe9-4svg40kna19/app-myapp:220414-2010-sqsoj (pinned to 86944c)  
    Running Instances:  0

Runtime:
  Concurrency:    100
  Maximum Scale:  10
  Minimum Scale:  0
  Timeout:        300

Build Information:
  Build Run Name:     myapp-run-220414-161009244
  Build Type:         git
  Build Strategy:     dockerfile-medium
  Timeout:            600
  Source:             https://github.com/IBM/CodeEngine
  Context Directory:  helloworld
  Dockerfile:         Dockerfile

  Build Run Summary:  Succeeded
  Build Run Status:   Succeeded
  Build Run Reason:   All Steps have completed executing
  Run 'ibmcloud ce buildrun get -n myapp-run-220414-161009244' for details.
[...]

Now that your app is created and deployed from repository source code, you can update the app to meet your needs by using the ibmcloud ce app update command. For more information about updating apps, see Updating your app. If you want to update your source to use with your app, you must provide the --build-source option on the application update command.

When your app is deployed from repository source code or from local source with the CLI, the resulting build run is not based on a build configuration. Build runs that complete are ultimately automatically deleted. Build runs that are not based on a build configuration are deleted after 1 hour if the build run is successful. If the build run is not successful, this build run is deleted after 24 hours. You can only display information about this build run with the CLI. You cannot view this build run in the console.

Next steps

After your app is deployed, you can update your deployed app and its referenced code by using any of the following ways, independent of how you created or previously updated your app:

  • If you have a container image, per the Open Container Initiative (OCI) standard, then you need to provide only a reference to the image, which points to the location of your container registry when you deploy your app. You can deploy your app with an image in a public registry or private registry.

    If you created your app by using the app create command and you specified the --build-source option to build the container image from local or repository source, and you want to change your app to point to a different container image, you must first remove the association of the build from your app. For example, run ibmcloud ce application update -n APP_NAME --build-clear. After you remove the association of the build from your app, you can update the app to reference a different image.

  • If you are starting with source code that resides in a Git repository, you can choose to let Code Engine take care of building the image from your source and deploying the app with a single operation. In this scenario, Code Engine uploads your image to IBM Cloud® Container Registry. To learn more, see Deploying your app from repository source code. If you want more control over the build of your image, then you can choose to build the image with Code Engine before you deploy your app.

  • If you are starting with source code that resides on a local workstation, you can choose to let Code Engine take care of building the image from your source and deploying the app with a single CLI command. In this scenario, Code Engine uploads your image to IBM Cloud® Container Registry. To learn more, see Deploying your app from local source code with the CLI. If you want more control over the build of your image, then you can choose to build the image with Code Engine before you deploy your app.

    For example, you might choose to let Code Engine handle the build of your local source while you evolve the development of your source for the app. Then, after the image is matured, you can update the deployed app to reference the specific image that you want. You can repeat this process as needed.

When you deploy your updated app, the latest version of your referenced container image is downloaded and deployed, unless a tag is specified for the image. If a tag is specified for the image, then the tagged image is used for the deployment.

Looking for more code examples? Check out the Samples for IBM Cloud Code Engine GitHub repo.