Initializing a microservice from scratch transforms a microservice source code project into a Kubernetes deployment using gopaddle command-line utility 'gpctl'. gopaddle builds the necessary Dockerfile and the Kubernetes artifacts based on the microservice profile.

Support Matrix

Project Type

gpctl Support

Long-running services

Terminal based services

Utilities, libraries, and short-lived binaries

Supported Languages

Java, NodeJS

Source Control Repositories



From the gopaddle UI, perform these steps:

1. Register a Cloud Account which can be used to provision a Kubernetes Cluster and to register a Docker registry.

2. Create or Register a Kubernetes Cluster. This cluster will be used to build the Docker container and to deploy the microservice. Follow these steps to create an EKS, GKE, or AKS cluster or register an external cluster.

3. Register a Docker Registry. This registry will be used for both pulling the base image used to build the microservice and also to push the final docker image generated after the build process.

4. Create an allocation policy to build and run the project.

5. Register a Source Control Repository.

Pre-requisites on the local environment:

1. Currently, Ubuntu 18.04 is the Linux distribution supported. Make sure that your system is installed with this Linux distribution.

2. Download and configure gopaddle command-line utility by following the steps here.

3. Install the 'git' package, if it is not already installed on the system (skip this step If 'git' package is already installed):

If you are running on the host/VM:

$ sudo apt-get install -y git

If you are running inside a container:

# apt-get install -y git

Important Note: There are a few other pre-requisites to run the gpctl tool. Please refer to the steps here first, before proceeding.

Login to the gopaddle account

Login to the gopaddle account using the email, password for root user / sub-user, and the account Id in case of sub-user:

$ gpctl login --emailID=<user email address> --password=<user password> --endPoint=<gopaddle endpoint>

*endPoint - gopaddle endpoint to connect to. If you are connecting to the gopaddle SaaS portal, then the endPoint is

Initialize the microservice

1. Clone the project from the source control repository and change it to the project root folder.

$ git clone <cloneURL>
$ cd <project-root-folder>

2. Make sure the .git file exists in the project root folder.

$ ls -la
drwxr-xr-x 15 demo staff 480 Mar 3 19:02 .git

Prepare the User Scripts

📌 Expose Environment Variables

Export ENVs that are to be used during the build or deployment process.
Say, if an environment variable named PORT is required by the application, then you can export the PORT variable in the local environment before running the gpctl init command.

📌 Self-sufficient - install required libs & packages

If each of these scripts is dependent on any libraries, packages or utilities, those dependencies must either be available in the base image or be installed or configured as a part of these scripts.
For example, if the build script uses npm command say npm run build, then the base image must have npm installed or the build script must install the npm command, before running npm run build.

📌 StartScript must start the application on the intended port

For instance, if a node-JS application is expected to bind on port 3000, but if the port is not available in the local environment, node-JS may automatically pick the next available port. This may break the discovery process. To overcome this scenario, assign a static port to the application while starting the application.

Build Script

Start Script

HealthCheck Script

Stop Script


Builds the app

Starts the app

Checks if the app is running

Stops the app

Used during

Discovery & Build

Discovery & Deploy

Discovery & Deploy


Success criteria

Exit 0

Runs forever

Exit 0












3. Create a build script to build the project. Say if it is a nodeJS application, you can create a as below.

npm install
npm run build

4. Create a run script to run the project. Say, if it is a nodeJS application that has a dependency on an external Mongodb database, you can create a as below:

cd dist
MONGODB_URI=mongodb:// npm start

🔔 Since the and will be run on two different environments, environment variables required to build the container and to run the container should be defined in these scripts appropriately.

🔔 Service started through must bind to instead of localhost.

5. Create a healthCheck script that checks for the running status of the microservice. A sample would look like this:

curl http://localhost:3000

6. Create a stopScript that stops the microsevice. A sample would look like this:

procs=`ps -ae -o comm,pid | grep "^node" | tr -s ' ' | cut -f2 -d' '`
if [ -n "$procs" ]
kill -1 $procs

7. Change the mode of the,, and scripts so that they have execute permissions:

$ chmod +x
$ chmod +x
$ chmod +x
$ chmod +x

8. Now, run each of the scripts, and make sure that the 'build', 'start', 'health check' and 'stop' scripts execute successfully, in that order, for the application:

$ ./ 
$ ./
$ ./ [ This may have to be issued on different terminal, based on the application ]
$ ./

9. Initialize the project by executing the gpctl init command

$ gpctl init --buildScript=<file pathname> --startScript=<file pathname> --healthCheck=<file pathname> --stopScript=<file pathname> [--baseImage=<image name>] [[--configMap=<folder1>:<folder2>] ...] [--startAwait=<time in seconds>] [--timeout=<time in seconds>] [--svcTimeout=<time in seconds>] [--projectID=<project ID>] [--releaseID=<release ID>] [--distributionID=<distribution ID>] [--desc=<description>] [--outputType=<output type>] [--outputDir=<directory for helm>] [--fsGroup=<desired group id>] [--enableVulScan] [--enableCI] [--buildOutputDir=<directory name>] [--help]

Mandatory options:

  • buildScript - Pathname of the file that contains the script/program that builds the service

  • startScript - Pathname of the file that contains the script/program that starts the service

  • healthCheck - Pathname of the file that contains the script/program that checks for the health of the service

  • stopScript - Pathname of the file that contains the script/program that stops the service

Non-mandatory (Optional) options:

  • baseImage - This specifies the name of image to be used to bring up a container that acts as the build environment to build the service. Build script will be executed within this container to build the service.

  • configMap - A folder in the current project (folder1) that needs to be added as configMap (folder2) in Kubernetes. All regular files within this folder (folder1) in the current project will be added to a configMap (folder2) and used for service deployment. To specify multiple such mappings, use configMap option multiple times.

  • startAwait - Initial wait time before the initialization process starts. Defaults to 30 seconds if not provided.

  • timeout - Seconds to wait before stopping command/script previously started (if still running). Default: 360 seconds.

  • svcTimeout - Seconds to await completion before exiting gopaddle-internal svcs previously initiated. Default: 540 seconds.

  • projectID - The 'project' identifier for this service. When this option is omitted, resources are added under 'default' project.

  • releaseID - The 'release' identifier for this service. When this option is omitted, resources are added under 'default' release.

  • distributionID - The 'distribution' identifier for this service. When this option is omitted, resources are added under 'default' distribution.

  • desc - Description for all gopaddle resources created. When not provided, defaults to contents of project 'description' file.

  • outputType - can either be appLaunch, helm, or template. When not specified, or if this option is omitted, defaults to appLaunch.

  • outputDir - Output directory to store helm charts. Applicable only when --outputType is used and specfied to be: helm.

  • fsGroup - set the filesystem mount group in Kubernetes for this service (a group to which the permission of all files in volumes will be changed when mounted by Kubernetes). If this option is omitted, fsGroup in Kubernetes is set to the GID (group id) of the current user.

  • enableVulScan - Enable Vulnerability scanning during 'image build' on Kubernetes

  • enableCI - Enable triggering build on commit to the git repository involved.

  • buildOutputDir - The output directory to place the artifacts generated during 'image build' on Kubernetes. This is applicable only when the root directory of the git source repository for this project does not contain a Dockerfile.

  • purge - remove/purge all gopaddle resources associated with this project.

  • help - Help for init process.

10. On executing 'gpctl init', you will be asked to choose the cluster where the build needs to be executed, the docker registry where the docker image has to be pushed, the allocation policy to use for building and deploying the container. When 'gpctl init' completes, you will get the application URL to access the microservice running in the Kubernetes environment.

Open up the firewall for the nodeports, to access the application URL from the browser.

Did this answer your question?