Deploying your app from local source code with the CLI

You can deploy your application directly from source code on your local workstation with the IBM Cloud® Code Engine CLI. Use the app create command to both build an image from your local source, and deploy your application to reference this built image.

When you submit a build that pulls code from a local directory, your source code is packed into an archive file. Code Engine automatically uploads the image to an IBM Cloud® Container Registry namespace in your account, and then creates and deploys your app to reference this built image. Note that you can only target IBM Cloud Container Registry for your local builds. The source image is created in the same namespace as your build image. For this scenario, you need to provide only a name for the app and the path to the local source. For a complete listing of options, see the ibmcloud ce app create command.

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

You can choose to ignore certain file patterns from within your source code by using the .ceignore file, which behaves similarly to a .gitignore file. For example, entries for a .ceignore file for a node.js application might include node_modules and .npm. For more sample file patterns to ignore, see the GitHub .gitignore repository.

The IBM Cloud® Container Registry is required for this scenario.

Before you begin

• Set up your Code Engine CLI environment.
• Create and work with a project.

Before you work with local source, make sure that your source is in an accessible location on your local workstation.

This example uses the https://github.com/IBM/CodeEngine samples; in particular, the helloworld sample.

1. Download the https://github.com/IBM/CodeEngine sample source to your local workstation with the following command.

   git clone https://github.com/IBM/CodeEngine
   

2. Change to the CodeEngine\helloworld directory.

3. From the CodeEngine\helloworld directory, create and deploy the myapp-local app, which uses an image that is built from the CodeEngine\helloworld source on your local workstation. This command automatically builds and pushes the image to a Container Registry namespace in your account. If you do not have an existing Container Registry namespace, Code Engine automatically creates one for you.

   ibmcloud ce application create --name myapp-local --build-source .
   

   The . indicates the build source is located in your current working directory.

   Example output

   Creating application 'myapp-local'...
   Packaging files to upload from source path '.'...
   Submitting build run 'myapp-local-run-220414-171750199'...
   Creating image 'private.us.icr.io/ce--abcde-glxo4kabcde/app-myapp-local:220414-2117-rdaga'...
   Waiting for build run to complete...
   Build run status: 'Running'
   Build run completed successfully.
   Run 'ibmcloud ce buildrun get -n myapp-local-run-220414-171750199' to check the build run status.
   Waiting for application 'myapp-local' to become ready.
   Configuration 'myapp-local' 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-local' to check the application status.
   OK
   
   https://myapp-local.glxo4kabcde.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-glxo4kabcde 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.

   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 path to the local source.

4. Use the application get command to display information about your app, including information about the build.

   ibmcloud ce application get --name myapp-local
   

   Example output

   [...]
   Name:          myapp-local
   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-local.Sta.us-south.codeengine.appdomain.cloud
   Cluster Local URL:  http://myapp-local.glxo4kabcde.svc.cluster.local
   Console URL:        https://cloud.ibm.com/codeengine/project/us-south/01234567-abcd-abcd-abcd-abcdabcd1111/application/myapp-local/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--abcde-glxo4kabcde/app-myapp-local:220414-2010-sqsoj
   Resource Allocation:
     CPU:                1
     Ephemeral Storage:  400M
     Memory:             4G
   Registry Secrets:
     ce-auto-icr-private-us-south
   
   Revisions:
     myapp-local-00001:
       Age:                23m
       Latest:             true
       Traffic:            100%
       Image:              private.us.icr.io/ce--abcde-glxo4kabcde/app-myapp-local: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-local-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-local-run-220414-161009244' for details.
   [...]
   

Now that your app is created and deployed from local 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.

Instead of building your image from local source and deploying your app with a single command, you can choose to build from local source first before you deploy your app. See Creating a build configuration that pulls source from a local workstation.

When your app is deployed from local source or from repository source code from 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.