Difference between revisions of "Install On The Command Line"

From WHMCS Documentation
(→‎Installing from the command line)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
=== Installing from the command line ===
 
=== Installing from the command line ===
 +
 +
<div class="docs-alert-warning">
 +
WHMCS 8.8 and later include configuration settings for encrypted MySQL connections. For more information, see [[System Environment Guide]] and [https://help.whmcs.com/m/installation/l/1706785-enabling-encrypted-mysql-connections Enabling Encrypted MySQL Connections].
 +
</div>
  
 
In addition to our [[Installing_WHMCS|other methods]], you can install and upgrade WHMCS on the command line. This is useful when you provision WHMCS for multiple installations. To use this method of installation, you must first download the <tt>.zip</tt> file for the desired version of WHMCS and unzip it.  
 
In addition to our [[Installing_WHMCS|other methods]], you can install and upgrade WHMCS on the command line. This is useful when you provision WHMCS for multiple installations. To use this method of installation, you must first download the <tt>.zip</tt> file for the desired version of WHMCS and unzip it.  
Line 5: Line 9:
 
<div class="docs-alert-warning">
 
<div class="docs-alert-warning">
 
<span class="title">For advanced users</span><br />
 
<span class="title">For advanced users</span><br />
−
* We only recommend this method for advanced users who are familiar with database management and the command line.
+
* We only recommend this method for advanced users who are familiar with WHMCS, database management, and the command line.
−
* Configuration and database issues can prevent you from using this method. We recommend that you perform a backup first.
+
* Configuration and database issues can prevent you from using this method. Always create file and database backups before you use this method.
−
* This installation method doesn't perform checks for [[Installing_WHMCS|InnoDB or database setup]].
+
* This installation method doesn't perform [[Installing_WHMCS|system requirement]] checks.
 
</div>
 
</div>
  
Line 24: Line 28:
 
You can use these options with the installation script:
 
You can use these options with the installation script:
  
−
{| class="wikitable"
+
<table class="table table-striped table-condensed">
−
!  Option
+
<tr>
−
!  Description
+
<th>Option</th>
−
|-
+
<th>Description</th>
−
|  <tt>-c</tt> or <tt>--config</tt>
+
</tr><tr>
−
|  Provide configuration data in the JSON format. Use this with the <tt>-n</tt> or <tt>--non-interactive</tt> option.
+
<td><tt>-c</tt> or <tt>--config</tt></td>
 +
<td>Provide configuration data in the JSON format. Use this with the <tt>-n</tt> or <tt>--non-interactive</tt> option.
 
For more on how to use this, see [[#data|Supplying configuration data]] below.
 
For more on how to use this, see [[#data|Supplying configuration data]] below.
−
<div class="docs-alert-warning"><span class="title">Added in WHMCS 7.10</span><br />We added this option in WHMCS version 7.10.</div>
+
<div class="docs-alert-warning"><span class="title">Added in WHMCS 7.10</span><br />We added this option in WHMCS version 7.10.</div></td>
−
|-
+
</tr><tr>
−
|  <tt>-h</tt> or <tt>--help</tt>
+
<td><tt>-h</tt> or <tt>--help</tt></td>
−
|  View help information.
+
<td>View help information.</td>
−
|-
+
</tr><tr>
−
|  <tt>-i</tt> or <tt>--install</tt>
+
<td><tt>-i</tt> or <tt>--install</tt></td>
−
|  Perform a new installation.
+
<td>Perform a new installation.</td>
−
|-
+
</tr><tr>
−
|  <tt>-n</tt> or <tt>--non-interactive</tt>
+
<td valign="top" style="white-space:nowrap">
−
|  Don't require user input while the script runs.
+
<tt>-n</tt> or <tt>--non-interactive</tt></td>
−
|-
+
<td>Don't require user input while the script runs.</td>
−
|  <tt>-s</tt> or <tt>--status</tt>
+
</tr><tr>
−
|  Provide status information about the installation's files and databases.
+
<td><tt>-s</tt> or <tt>--status</tt></td>
−
|-
+
<td>Provide status information about the installation's files and databases.</td>
−
|  <tt>-u</tt> or <tt>--upgrade</tt>
+
</tr><tr>
−
|  Upgrade an existing installation.
+
<td><tt>-u</tt> or <tt>--upgrade</tt></td>
−
|-
+
<td>Upgrade an existing installation.</td>
−
|  <tt>-v</tt> or <tt>--verbose</tt>
+
</tr><tr>
−
|  Run the script with verbose output.
+
<td><tt>-v</tt> or <tt>--verbose</tt></td>
−
|}
+
<td>Run the script with verbose output.</td>
 +
</tr>
 +
</table>
  
 
==== <span id="data"></span>Supplying configuration data ====
 
==== <span id="data"></span>Supplying configuration data ====
  
−
If you use the <tt>-c</tt> or <tt>--config</tt> option, you must supply configuration data in the JSON format. For example:
+
If you use the <tt>-c</tt> or <tt>--config</tt> option, you must supply configuration data to STDIN as a single line of input in the JSON format.  
 +
 
 +
You can supply data for two elements:
 +
 
 +
<table class="table table-striped table-condensed">
 +
<tr><th>Array</th>
 +
<th>Description</th>
 +
</tr><tr>
 +
<td><tt>admin</tt></td>
 +
<td>Provide information for the initial administrator account using the <tt>username</tt> and <tt>password</tt> parameters. If you don't supply these, the system generates and displays them at the end of installation.</td>
 +
</tr><tr>
 +
<td><tt>configuration</tt></td>
 +
<td>Provide variable data for the creation of a new configuration file. For a list of parameters to use, see our documentation on [[Restoring_WHMCS#Creating_a_New_Configuration_File|creating a new configuration file for WHMCS]].
 +
* The system creates a <tt>configuration.php</tt> file when your input contains the <tt>configuration</tt> element.
 +
* If you supply the <tt>configuration</tt> element and a <tt>configuration.php</tt> file already exists, an error will occur.
 +
* If your input doesn't contain the <tt>configuration</tt> element, the installation process requires that a valid <tt>configuration.php</tt> file is present.
 +
For an example of installation using this element, see the [[#ex-config|Example installation with configuration data]] section below.</td>
 +
</tr>
 +
</table>
 +
 
 +
<div class="docs-alert-warning">
 +
<span class="title">Warning</span><br />
 +
Exercise caution when you supply sensitive information on the command line.
 +
</div>
 +
 
 +
===== <span id="ex-config"></span>Example installation with configuration data =====
 +
 
 +
When you use the <tt>configuration</tt> element, your JSON data could resemble this example:
  
 
<div class="source-cli">
 
<div class="source-cli">
−
echo '{"admin":{"username":"name","password":"12345luggage"}}' | php -f bin/installer.php – -i -n -c
+
<nowiki/>#!/bin/env bash
 +
<br/><nowiki/># The following assumes the respective environment variables are populated
 +
<br/>
 +
<br/>CONF='{
 +
<br/>&nbsp;"admin":{
 +
<br/>&nbsp;&nbsp;"username":"name",
 +
<br/>&nbsp;&nbsp;"password":"'$ADMIN_PASS'"
 +
<br/>&nbsp;},
 +
<br/>&nbsp;"configuration":{
 +
<br/>&nbsp;&nbsp;"license": "'$LICENSE_KEY'",
 +
<br/>&nbsp;&nbsp;"db_host": "'$DB_HOST'",
 +
<br/>&nbsp;&nbsp;"db_username": "'$DB_USER'",
 +
<br/>&nbsp;&nbsp;"db_password": "'$DB_PASS'",
 +
<br/>&nbsp;&nbsp;"db_name": "'$DB_NAME'",
 +
<br/>&nbsp;&nbsp;"cc_encryption_hash": "'$ENCRYPT_HASH'",
 +
<br/>&nbsp;&nbsp;"mysql_charset": "utf8"
 +
<br/>&nbsp;}
 +
<br/>}'
 
</div>
 
</div>
  
−
The script uses your input to create a <tt>configuration.php</tt> file for the installation.
+
You would then supply this data via the following command:
  
−
You can configure two arrays:
+
<div class="source-cli">
 +
echo $(echo $CONF | tr -d "\n") | php -f bin/installer.php – -i -n -c
 +
</div>
  
−
{| class="wikitable"
+
<div class="docs-alert-info">
−
!  Array
+
<span class="title">Important</span><br />
−
!  Description
+
The encryption hash value must be 64 characters long and contain only a–z, A–Z, and 0–9 ASCII values.
−
|-
+
Generate this value with a high-entropy random data source or a cryptographic password generation tool. For example:
−
|  <tt>admin</tt>
+
<div class="source-cli">
−
|  Provide information for the installation's administrator account using the <tt>username</tt> and <tt>password</tt> parameters.
+
<nowiki/># Example hash value generation with the OpenSSL utility
−
<div class="docs-alert-warning">
+
<br/><nowiki/>ENCRYPT_HASH=$(openssl rand -base64 128|tr -d "\n\/+="|cut -c 1-64)
−
<span class="title">Warning</span><br />
+
</div>
−
Exercise caution using the <tt>admin</tt> array to supply passwords. It could pose a security risk.
 
 
</div>
 
</div>
−
|-
 
−
|  <tt>configuration</tt>
 
−
| Provide configuration information for the WHMCS installation.  For a list of parameters to use, see [[Restoring_WHMCS#Creating_a_New_Configuration_File|Restoring WHMCS]].
 
−
|}
 

Latest revision as of 17:13, 28 August 2023

Installing from the command line

WHMCS 8.8 and later include configuration settings for encrypted MySQL connections. For more information, see System Environment Guide and Enabling Encrypted MySQL Connections.

In addition to our other methods, you can install and upgrade WHMCS on the command line. This is useful when you provision WHMCS for multiple installations. To use this method of installation, you must first download the .zip file for the desired version of WHMCS and unzip it.

For advanced users

  • We only recommend this method for advanced users who are familiar with WHMCS, database management, and the command line.
  • Configuration and database issues can prevent you from using this method. Always create file and database backups before you use this method.
  • This installation method doesn't perform system requirement checks.

Input

The installation script uses the following syntax:

php -f bin/installer.php –- [options]

Options

Defaults
The script enables non-interactive mode (-n or --non-interactive) and performs an upgrade (-u or --upgrade) by default.

You can use these options with the installation script:

Option Description
-c or --config Provide configuration data in the JSON format. Use this with the -n or --non-interactive option.

For more on how to use this, see Supplying configuration data below.

Added in WHMCS 7.10
We added this option in WHMCS version 7.10.
-h or --help View help information.
-i or --install Perform a new installation.
-n or --non-interactive Don't require user input while the script runs.
-s or --status Provide status information about the installation's files and databases.
-u or --upgrade Upgrade an existing installation.
-v or --verbose Run the script with verbose output.

Supplying configuration data

If you use the -c or --config option, you must supply configuration data to STDIN as a single line of input in the JSON format.

You can supply data for two elements:

Array Description
admin Provide information for the initial administrator account using the username and password parameters. If you don't supply these, the system generates and displays them at the end of installation.
configuration Provide variable data for the creation of a new configuration file. For a list of parameters to use, see our documentation on creating a new configuration file for WHMCS.
  • The system creates a configuration.php file when your input contains the configuration element.
  • If you supply the configuration element and a configuration.php file already exists, an error will occur.
  • If your input doesn't contain the configuration element, the installation process requires that a valid configuration.php file is present.
For an example of installation using this element, see the Example installation with configuration data section below.

Warning
Exercise caution when you supply sensitive information on the command line.

Example installation with configuration data

When you use the configuration element, your JSON data could resemble this example:

#!/bin/env bash
# The following assumes the respective environment variables are populated

CONF='{
 "admin":{
  "username":"name",
  "password":"'$ADMIN_PASS'"
 },
 "configuration":{
  "license": "'$LICENSE_KEY'",
  "db_host": "'$DB_HOST'",
  "db_username": "'$DB_USER'",
  "db_password": "'$DB_PASS'",
  "db_name": "'$DB_NAME'",
  "cc_encryption_hash": "'$ENCRYPT_HASH'",
  "mysql_charset": "utf8"
 }
}'

You would then supply this data via the following command:

echo $(echo $CONF | tr -d "\n") | php -f bin/installer.php – -i -n -c

Important
The encryption hash value must be 64 characters long and contain only a–z, A–Z, and 0–9 ASCII values. Generate this value with a high-entropy random data source or a cryptographic password generation tool. For example:

# Example hash value generation with the OpenSSL utility
ENCRYPT_HASH=$(openssl rand -base64 128|tr -d "\n\/+="|cut -c 1-64)

Retrieved from "http://3.17.75.209/index.php?title=Install_On_The_Command_Line&oldid=34208"