(Archived) How deployment via CLI is working

You have tried to access an archived page. Please go to the new https://root360.atlassian.net/wiki/spaces/KB to find more documents.

General usage instructions

The general usage instructions for the cloud managment tool suite r3 can be found here.

For this mechanism, it is important that all database updates be backward-compatible!

On the jump server the root360 cloud management cli is installed. It initiates the rollout by notifying the configuration management system that this application deployment is to be initiated.

The current source code is loaded from the specified sources and stored on a distributed file system for further processing.

After this, all web servers start their deployment based on the new source code. Once all defined deployment steps have been completed, the resulting project directory is activated and all caches (eg opcache, apc, etc.) are emptied.

The Deploy system supports hooks that are started before or after deployment. These hooks are executable files of any kind (eg script, Linux binary file). See further documentation.

Restrictions

Parallel deployment

Parallel deployments are possible when the stack and deployment procedure adheres to the following requirements:

roles for parallel deployment must not be on the same instances
deployment must run in 2 subsequent stages:
- first stage updates the sources sequentially (parameter -m)
- second stage deploys the source code to the target instances (parameter -n)

Step-by-step guide

Show help context

Connect to the Jump server
Execute command

Show help example

~$ r3 deploy -h

# Response
Deploy software to instances in project environment

optional arguments:
  -h, --help            show this help message and exit
  -d                    run in debug mode
  -q                    run in quiet mode (only errors are shown)
  -p PROJECT, --project PROJECT
                        The necessary name of the project to work on
  -r ROLE, --role ROLE  Server role to work on
  --pre-hook [PRE_HOOK]
                        run pre-deploy hook scripts in default path "pre-
                        hook.d/" or given directory (optional)
  --post-hook [POST_HOOK]
                        run post-deploy hook scripts in default path "post-
                        hook.d/" or given directory (optional)
  --rev REV             specify tag/branch/revision to clone (git deployment
                        only!)
  --list-roles          list deployable roles and exit
  --list-sources        list source details and exit
  -n                    skip update of source code (optional)
  -m                    skip distribution of source code (optional)

List available applications/roles, which can be deployed

List deployable applications example

~$ r3 deploy --list-roles

# Response
+-------+
| Roles |
+-------+
| admin |
+-------+
| api   |
+-------+
| web   |
+-------+

How to start a deployment process

Minimal deployment command example

~$ r3 deploy --role YOUR-ROLE

How to clone a deviant branch or tag at git

Working with branches and tags example

How to review configured deployment sources

r3 deploy --list-roles allows you to see the static configuration for each application/role of the respective environment, e.g. prod.

Response Explanation

Role: the name of the role
Deployment Method: names the method (see details below) used
Source: The source repository or path in filesystem used to obtain data from
Branch: In case of Git a branch was named by you during setup. You can overwrite this reference by giving the --rev command line option.
Excludes: If the filesystem is used as source, sometimes files or folders should be excluded from deployment generally or to protect against human error ( e.g. .git/* or /cache)

List deployment sources example

Command response

The response is presented to the command line directly.
The response is logged to /var/log/application/deploy.log on the JumpServer for downstream analysis.
On each target /var/log/application/deploy.log furthermore locally captures additional process information for deeper downstream analysis.
Exit Codes are returned for programmatical integration e.g. in CI/CD (details can be found below).

Response Example

Supports methods for loading the source code

Method	Authentication	Description

Method	Authentication	Description
git	Private-public-key via SSH	Clones a Git repository over SSH (recommended)
svn	Username Password	Clones an SVN repository over HTTP / HTTPS
HTTP / HTTPS	Username Password	Loads packed source code (eg Zip / Tar)
rsync	Private-public-key via SSH	Synchronizes source code from a server via SSH

Exit codes

The Deploy script returns different exit codes in case of an error.

These can be read in the shell with the following command, for example:

Breakdown of the codes

code	importance	solution
0	Deployment was successful
1	Could not run install.sh	Read the error message (red) accurately and correct the error
2	Error updating from project sources	Access to the location of the project sources (eg customer Git servers)
3	Failed to determine the number of servers to update	Open the support ticket
4	Failed to update servers	Check log file /var/log/application/deploy.log for issues
5	Users can not be resolved for hooks	Open support ticket and append Deployment Log at /var/log/application/deploy.log
6	A hook terminated with non-zero return code	Check the output of the hook and correct the fault
7	There was a global Hook execution error	Check output of hooks and eliminate errors
8	No valid hooks found in the specified path	Hook option or at least one valid hook script
9	A deployment is already in progress	Check who started a deployment and wait for it to complete
10	An unknown error occurred	Open support ticket and append Deployment Log at /var/log/application/deploy.log
11	Can not connect to the configuration management system	Open support ticket and append Deployment Log at /var/log/application/deploy.log
12	Maximum number (10) achieved at simultaneous deployments	Wait for the ongoing deployments to terminate
13	The user canceled the deployment with Ctrl + C	Ask users for the reason and, if necessary, start deployment again
15	project is missing and could not be determined	Specify project using '–project' option
16	role is missing and could not be determined	Specify role using '–role' option
17	given role is unknown	check role given with '–role' option for typos and fix those
18	Encountered a timeout while waiting for status messages	Open a support ticket mentioning the used commandline and the whole command output
19	Found some minions that cannot be deployed	wait up to 10 minutes and try again
20	Got several different states during minion count resulting in deploy stop	check messages returned by the minions and solve the specified issues, if that's not possible contact our support with the output
21	Retry limit for getting available port reached	Contact our support with the output and deploy command
22	revision is unknown and could not be determined	Revision parameter (`--rev`) missing
23	unable to detect IP address	Contact our support with the output and deploy command

Knowledge Base