Configuration

Edit on Gitlab

Table of Contents

Global configuration

Set up access to package server

This setting is for all projects on the server. It has to be done once.

  • in ./bin directory copy getfile.sh.cfg.dist to getfile.sh.cfg
  • edit getfile.sh.cfg and define software endpoint and set the phase:
IMLCI_URL=https://software.example.com
IMLCI_PKG_SECRET=put-secret-here
IMLCI_PHASE=preview
name type description
IMLCI_PHASE string name of the phase; one of preview
IMLCI_PKG_SECRET string Secret to download software packages; recommendation: do NOT set a shared secret for all applications but an individual one
IMLCI_URL string Url to server with software packages

Set up software rollout

The deployment client can handle multipe profiles. One profile is for one application.

In the subdir ./profile is an example profile:

.
└── example
    ├── config.sh.dist
    ├── replace.txt
    ├── tasks_config.sh
    ├── tasks_postinstall.sh
    └── tasks_preinstall.sh

Files:

File Description
config.sh.dist Configuration file for the application rollout
replace*.txt Files containing replacement data. You can create multiple files eg. for different responsible groups like sysadmin, developers
tasks_config.sh
tasks_postinstall.sh
tasks_preinstall.sh

Create a profile

  • Create a subdirectory in ./profiles/ for each product
  • The example subdir gives an orientation and can be copied, i.e. cp -r example myapp
  • create a config file named ./profiles/myapp/config.sh (copy the config.sh.dist from example profile)
# my install dir
installdir=/var/www/myapp

# fileowner
# appowner="user:www-data"

# ----- settings for CI server software package 


IMLCI_PROJECT=id-in-ci-server

# override global value 
# IMLCI_PHASE=preview

# cleanup after pre install tasks and bevore extracting data
# set both to 0 .. or only one of them to 1
cleanup_preview=0
cleanup_force=0

Config variables:

name type description
installdir string target directory of your application
appowner string if not empty a chown -R will be applied in target directory by chwon -R ${appowner} ${installdir}; appowner is the parameter behind -R. It is something like “myuser.” or “myuser:mygroup”. For a web application it should be the user of your webservice (www-data/ apache/ nginx). The command chown requires to run the deploy script as root.
IMLCI_PROJECT string Project id in IML CI server
IMLCI_PHASE string optional: override the global IMLCI_PHASE in ./bin/getfile.sh.cfg; it is one of preview|stage|live
cleanup_preview 0 or 1 Cleanup preview - shows diff between downloaded TGZ and ${installdir}.
cleanup_force 0 or 1 Run cleanup: it deletes all files in target directory that aren’t in the last downloaded tgz. To keep runtime data like logs or uploads you can add a file .keep in the directory.

Make a testrun: ./deploy_app.sh in application root. It should download the software package and extract it and install it into you ${installdir}.

Add hooks

If needed you can create hook scripts. The working directory is ${installdir} that you can use relative pathes to point to your files in the the extracted sources.

To access other ressources you can user these variables:

${selfdir}     application root of deployment scripts
${profiledir}  project config dir i.e. [path]/profiles/myapp

For hooks you can create files with pre defined names. A hook script must have executable rights. You get a hint message if it does not exist or has no x permission. A missing hook script does not result in an error.

  • profiles/myapp/tasks_preinstall.sh - do something before extracting the archive.
  • profiles/myapp/tasks_config.sh - replace config files (see below)
  • profiles/myapp/tasks_postinstall.sh - do postinstall actions before finishing

Create configs for an application

Run script tasks_config.sh

The script ./bin/create_config.sh can read config templates and create an output file.

You need to reference the template, output file and a file for replacement data.

# ----------------------------------------------------------------------
# TASKS :: GENERATE CONFIGS
# ----------------------------------------------------------------------

#               create_config.sh    template_file                                 target_file                       replacements (can be multiple files)
#               |                   |                                             |                                 |
#               v                   v                                             v                                 v
"${selfdir}/bin/create_config.sh"   hooks/templates/mytemplate.erb                config/target.php                 ${profiledir}/replace.txt

During execution the working directory is the target directory of your application.

  • “${selfdir}/bin/create_config.sh” is the script that replaces config data in a template.
  • In your software repsoitory put a template into ./hooks/templates/. It will be found if the archive was extracted.
  • the target file is relative to your application root.
  • files with replacement data. You can use file globbing, eg. ${profiledir}/replace*.txt

Replacements

A sample replacement file is profiles/example/replace.txt:

# ----------------------------------------------------------------------
# REPLACEMENTS
# ----------------------------------------------------------------------
#
# SYNTAX:
# key=value
#
# - no spaces around first "="
# - value can contain any char, no quoting
# ----------------------------------------------------------------------

dbhost=localhost
dbuser=fred
dbpassword=vom-jupiter
dbport=3306

api-key=12345678

# ----------------------------------------------------------------------

The idea for several replacent files is that different groups can set their replacement data:

  • sysadmins add connections and credentials to needed services/ database connections
  • developers add api keys and other internal values
  • …

Ciserver project values

After extracting the software there is an atomatic step that generates a replacement from [PROJECTID].json in the install directory.

It generates a replacement file named replace_ciserver.txt in the profile directory and contains the branch name and the revision id of the last commit:

ci-branch=origin/master
ci-revision=9f041d5f3fe9faa43769da97f3eb46d5c553e3fe

Pre and post install actions

Example: A simple tasks_postinstall.sh can contain the start of a script that is delivered in the tgz archive.

# ----------------------------------------------------------------------
# TASKS :: POST INSTALL ACTIONS
# ----------------------------------------------------------------------
hooks/ondeploy