Skip to content

Installation

Jump to bottom Edit New page
tenzap edited this page Dec 21, 2024 · 15 revisions

Be sure to meet all requirements

Especially, be sure you have already setup the Gammu SMSD database. If you haven't yet, this howto will guide you.

Kalkun uses the database that is created by gammu with all the tables created by gammy. Kalkun then adds supplementary tables and some columns to the gammu tables. So there is no such case where one has a gammu database separate from the kalkun database. Both software share the same database.

Get the source code of Kalkun

Download and extract the latest release or tag to your web root folder.

If you run Debian or Ubuntu or any related distribution, there is a kalkun debian package: installation procedure for Debian package. Then jump to Configure the connection to the database

Get the third party php libraries

For this we use Composer which must be installed on your system. From the root dir of kalkun, run:

composer install

If composer install fails, read the error messages. You may need to run composer update, or composer install --ignore-platform-reqs instead.

Alternatively

In case you plan to deploy Kalkun on a server that has a different version of PHP than the one on your system, you can target a specific version of PHP. For example for PHP 7.1.24, run:

composer config platform.php 7.1.24

It adds this to your composer.json.

...
    "config": {
        "platform": {
            "php": "7.1.24",
        }
    },
...

Then run:

composer update --no-dev

Configure Daemon & outbox_queue scripts

The "daemon" task is to manage inbox and autoreply. It is invoked by gammu-smsd whenever new messages arrive. Gammu-smsd calls a script (batch script on windows, shell script on linux/unix).

⚠️ Important: You must configure the "daemon" otherwise you will not see the messages in your inbox.

  • Set correct path (to php command and daemon.php) on daemon.sh or daemon.bat:

    # Configure this (use absolute path)
PHP=/usr/bin/php # php cli path
DAEMON=/path/to/kalkun/scripts/daemon.php # daemon.php path

  • Set correct path (to php command and outbox_queue.php) on outbox_queue.sh or outbox_queue.bat:

    # Configure this (use absolute path)
PHP=/usr/bin/php # php cli path
DAEMON=/path/to/kalkun/scripts/outbox_queue.php # outbox_queue.php path

  • On linux/unix, make sure that the daemon & outbox_queue scripts are executable.

    sudo chmod +x daemon.php daemon.sh daemon.bat

  • Change URI path in daemon.php and outbox_queue.sh. Default is:

    // Please configure this
$url = "http://localhost/kalkun";

Configure gammu-smsd

  • Gammu-smsd has to be configured so that it invokes the daemon on each new incoming message. This is done by setting the value of the runonreceive directive in the gammu-smsd configuration file (smsdrc). On Debian/Ubuntu systems you will find it at /etc/gammu-smsdrc.

    • For example on Unix (using shell script):

      [smsd]
runonreceive = /var/www/html/kalkun/scripts/daemon.sh

    • If you use the Debian package the path is as follows:

      [smsd]
RunOnReceive = /usr/share/kalkun/scripts/daemon.sh

    • Or if you use Windows (using batch file):

      [smsd]
runonreceive = C:\xampp\htdocs\kalkun\scripts\daemon.bat

    ⚠️ Warning: It always a good idea to move the scripts directory outside the www, so it’s not accessible from browser.

  • After having updated the configuration, restart the gammu-smsd service for the changes to take effect.

Troubleshooting:

If somehow gammu-smsd fails to run the daemon script, it will throw an error like this:

gammu-smsd[3665]: Process failed with exit status 126

Check permission and try to run the script manually.

Increase the security of your installation

Although not mandatory, this is highly recommended. See Increase setup security.

Configure the connection to the database

Edit database.php located at application/config/database.php, you should see this line:

Set the correct value for the database you wish to use (here the example is with MySQL)

$active_group = 'kalkun_mysql';

Set the correction value at least for the database name, username & password fields:

$db['kalkun_mysql'] = array(
//...
	'username' => 'root',
	'password' => 'password',
	'database' => 'kalkun',
//...

Launch the installer

If you are upgrading:

  • proceed with a backup of your database.
  • be sure that you have a file called install next to the index.php file. Its presence will permit to enter the installer The content of install file is not important).

Now, you can launch the installer by opening your browser and going to http://localhost/kalkun. You will be redirected to http://localhost/kalkun/index.php/install (if not, place a file named install next to index.php) and you will see the installation wizard there. The wizard will guide you to complete the installation, it should be easy.

This is the recommended way as it will automatically set-up and update the database whether this is a fresh install or an upgrade from a previous version of Kalkun.

ℹ️ Note: You may proceed with a manual DB install by injecting these SQL script (in the order they are here) into your DB, but only in the case of a fresh kalkun install. Don't do this if you upgrade, you will mess things up in your database:

  • application/sql/DBENGINE/kalkun.sql
  • application/sql/DBENGINE/pbk_gammu.sql
  • application/sql/DBENGINE/pbk_kalkun.sql

Delete install file

At the end of installation wizard, if it tells to do so, you must delete the install file yourself. It is likely the webserver hasn't the right to write to the directory. If you don't do so, you will be redirected to the begining of the installation wizard again. (Note: the installation wizard tries to do this automatically, but may fail due to lack of permission. Then you must delete it manually).

Change the default encryption key

  • To improve security, it's higly recommended to change the default encryption_key in application/config/config.php. See setting your encryption key.
  • On unix/linux you may run
php -r 'echo bin2hex(random_bytes(16)), "\n";'

Write the value in application/config/config.php and enclose it in a call to hex2bin() function. For example:

$config['encryption_key'] = hex2bin('32_CHAR_LONG_ENC_KEY');

Set the environment to 'production'

  • CodeIgniter permits to use a http server environment variable named CI_ENV. By default we left it it development. You may want to change it to production. If your webserver is Apache's httpd it is set in .htaccess file. However if you use another web server, set this environment variable in the configuration of your server. If set to production no errors will be reported. While if set to developent, the errors will be reported, what may be a security risk. More details in the CodeIgniter documentation.

Setup timezone

Before you run kalkun, you should check the timezone of your PHP server is setup correctly. To do so, run

php -r 'echo date_default_timezone_get()."\n";'

If the timezone is not correct the time will be shown incorrectly in Kalkun and it is likely your SMS will never be delivered.

Launch Kalkun

Open up your browser and go to http://localhost/kalkun

Default account for the Web Interface (you can change it after you login):

  • username = kalkun
  • password = kalkun

You should change the password after login for security issue.

Debian and related

Installing on Debian and derivatives systems like Ubuntu is easier since Debian packages are available. Most of the installation steps are already made by the package.

There are various sources to get the packages from:

  • For the releases
  • For daily snapshots (produced on every commit)
    • kalkun PPA (since Jul/2023) the latest snapshot.
    • Get the bundle for the commit which you are interested in, on the github actions page. Find them this way:
      1. go to https://github.com/kalkun-sms/Kalkun/actions?query=workflow%3APackaging++
      2. filter the branch you wish to have the packages for
      3. click on the header of the 1st workflow to get the most recent
      4. download the "Debian packages" artifact (it probably requires to login with your Github account)

Installation steps:

  • If you use the PPA, follow the installation instructions there
  • If you you a debian bundle from github

    1. Unpack the Debian bundle archive you downloaded and enter the unpack dir.

    2. The Debian bundle archive contains kalkun but also some dependencies that you may need if your distribution doesn't ship them.

    3. Install kalkun by running one of these commands:

      1. To install kalkun core only and the dependencies: 
        apt install \
  ./php-*.deb \
  ./kalkun_*.deb
      2. Optionally, you may install plugins. 
        apt install ./kalkun-plugins*.deb

Once you have installed kalkun package

  1. Continue the installation instructions from Configure the connection to the database
  2. You may also read the README.Debian at /usr/share/doc/kalkun/
Add a custom footer
Clone this wiki locally