These are functions you can use within your project.
See common.sh for all available functions.
You shoudn't need to include common.sh in your project.sh file, since the script is automatically imported (sourced) before each build or deployment.
Although there are more functions within common.sh, please only use the ones detailed here. Other functions may be removed at any time and are not designed for project use.
Terminates the script if the first argument is non-zero, after printing out the second argument as an error message.
{exit code} {error message}
replace_config_value
Replaces entries in a config file, assuming that the target file stores properties in the syntax: key=value.
{key} {value} {file path}
replace_persistence_config_value
Replaces entries in a JPA config file, persistence.xml. This assumes that there is only one persistence units - please do not use this if you have more than one.
{property name} {property value} {file path}
clear_old_tomcat_deployments
Clears down Tomcat deployments, keeping {number of deployments to keep} .war files. Matches the pattern supplied as {2} to find files: e.g.: dev## will match against dev##1 dev##2 dev##3.
{number of deployments to keep} {pattern to match against .war files} {deployment location}
clear_old_apache_deployments
Clears down Apache deployments, keeping {number of deployments to keep}.
{number of deployments to keep} {target directory}
Should be set to a simple title for the project, e.g.: "aple" or "actss".
Used to form part of the deployment directory for Apache-based projects. See deployment/deploy.sh for usage.
BUILD_AREA
Y
Global
Full path to a directory.
Passed to build_artefact function as the location that the build (file or directory) should be placed into. Directory must be writable by the project user.
DB_ENABLED
Y
Global
"true" or "false"
Signals if the project requires a database or not. If true, DB_CONFIG variables will be checked for values.
DB_CONFIG[host]
Global
Hostname of the database server (e.g.: "127.0.0.1").
To be used in the generation of config files or deployment checks. This should be set at runtime by set_{live/demo/dev}. See building environment configuration files.
DB_CONFIG[port]
Global
Port for the database service (e.g.: "3306" for MySQL").
To be used in the generation of config files or deployment checks. This should be set at runtime by set_{live/demo/dev}. See building environment configuration files.
DB_CONFIG[schema]
Global
Schema nane (aka database name).
To be used in the generation of config files or deployment checks. This should be set at runtime by set_{live/demo/dev}. See building environment configuration files.
DB_CONFIG[username]
Global
Valid username to connect to host:port/schema.
To be used in the generation of config files or deployment checks. This should be set at runtime by set_{live/demo/dev}. See building environment configuration files.
DB_CONFIG[password]
Global
Valid password to connect to host:port/schema.
To be used in the generation of config files or deployment checks. This should be set at runtime by set_{live/demo/dev}. See building environment configuration files.
Should set any variables required to build the product for a live environment. If this is a database project, you should be writing database values into DB_CONFIG. See building environment configuration files.
All
1
set_demo
Y
Should set any variables required to build the product for a demo environment. If this is a database project, you should be writing database values into DB_CONFIG. See building environment configuration files.
All
1
set_dev
Y
Should set any variables required to build the product for a development environment. If this is a database project, you should be writing database values into DB_CONFIG. See building environment configuration files.
Build
2
deployment_checks
Y
Used to check any deployment pre-requisites (i.e database is available and has been patched). This function should signal a failure if the deployment is not ready.
If the function returns an exit code other than 0, deployment pre-requisites have not been met and so the pipeline will terminate.
Build
3
generate_config_files
Y
Generates configuration files for your application, which should modify files in the current directory. These will later be copied to the deployment location, or built as part of the build_artifact. Usually you should be reading in database information from DB_CONFIG and writing it out to your configuration files. At this point DB_CONFIG should contain live/demo/dev information and so you shouldn't need to check any details (e.g. branch names).
On a non-zero exit code, pipeline will terminate.
Build
4
build_artifact
Y
Builds the artefact to deploy and should place it within the $BUILD_AREA directory. For example, using Maven to build the JAR and then moving it into the build area. If this is an Apache-based project, this should just copy the whole project folder to the build area. Upon completion, a deployment-ready artefact (a single file for a Tomcat deployment, or a single directory for an Apache project) should reside within $BUILD_AREA. If the file/directory isn't present, the deployment will terminate at the deployment stage.
On a non-zero exit code, pipeline will terminate.
Deploy
2
get_deployment_location
Y
Should echo the base directory to deploy to (e.g. echo /srv/http/projectname.beautifulcanoe.com/). If the project is an Apache-based one, this is the directory that contains public_html. public_html is then symlinked to get_deployment_location()/$PROJECT_TITLE/$CI_BUILD_ID/.
Deploy
3
post_deployment_extras
Y
Execute any commands needed after deployment has taken place. This is executed before any symbolic linking. This must be defined, but may do nothing (e.g.: return 0).
Deploy
4
target_subdirectory
Usually, public_html will be linked to get_deployment_location()/$PROJECT_TITLE/$CI_BUILD_ID/. In the event that public_html should be symlinked to a directory within $CI_BUILD_ID, the subdirectory name should be echoed out here. For example, echo "foo" will result in public_html being symlinked to get_deployment_location()/$PROJECT_TITLE/$CI_BUILD_ID/foo/.
Deploy
5
post_linking_extras
Execute any commands needed after the public_html link has been created. This does not need to be defined.