Skip to content

Installation

Jump to bottom Edit New page
Eric Lee edited this page Dec 4, 2022 · 48 revisions

System Requirements

CORE-POS is a web based system. It requires a web server, a database server, and PHP.

  • PHP should be version 7+
  • Composer 2.0+ is needed to manage plugin packages.
  • Apache2+ is the primary webserver in production usage. CORE-POS does not rely on any Apache-specific features so other web servers will likely work if desired. Nginx is known to work on Linux.
  • MySQL (or MariaDB) 5+ is the only database server in production usage. Microsoft SQL Server has been supported in the past and is probably usable still with minimal effort. Adding support for additional flavors of SQL is not out of the question but would involve some work.
    • Setting sql_mode to '' is recommended. Somewhat stricter settings will work, but ONLY_FULL_GROUP_BY behavior varies by MySQL version down the patch level in what aggregate queries it supports.
  • PHP must be configured with support for your chosen DB. Using PDO or mysqli with MySQL/MariaDB is highly recommended. The POS installation also requires support for sockets. Some features may require additional PHP modules.
    • Integrated card processing requires cURL and OpenSSL
    • Zip is required to import zipped CSV files
    • gettext and intl are required for full language support
    • LDAP is required for LDAP authentication on Office

Supported Operating Systems

As primarily a web-based solution CORE is mostly platform independent but not completely. Known issues:

  • Lane
    • Some integrated card processing features are Windows-only. This relates to 3rd-party software and is unlikely to change.
  • Office
    • The task scheduler relies heavily on cron and does not work on Windows.
    • Customized table syncing uses symlinks and won't work out of the box on Windows.

System Architecture

CORE contains two distinct pieces of software. The front end software (Lane) runs an electronic cash register. The back end software (Office) manages the operational data required by the register(s) and reports on transaction data generated by the register(s). A typical real world installation has one machine running the back end software and one or more additional machines running the front end software. To push operational data from the back end to the register(s), the back end configuration must include the network address and database credentials of each register. Similarly, to push transaction data from the register(s) to the back end database, each register's configuration must include the network address and database credentials of the back end.

It is possible to run both software components on a single machine for development or testing purposes. However, you still need to specify database credentials in both directions even though the machine is pushing data to itself. Both pieces of software will run independently - and indeed are intended to be functional in the event of network outage or loss of communication - but transfer data between the pieces requires appropriate configuration at both ends.

Downloading CORE

You can download CORE directly, or you can clone a copy via git. Using git is recommended as it makes tracking changes and updates easier. To download a copy, use the Releases page. Unpack the archive somewhere under your web server root.

To download a copy via git, first decide whether you want to do any code editing. If you do, it will be easier to first create your own fork of the project. Sign up for a github account (if necessary), go to the project page, and use the Fork button in the upper right. Non-developers can skip this step.

These instructions assume you are using git from the command line. Github has extensive documentation if you go a different route. The goal is to clone the repository somewhere under your web server root.

$ cd /path/to/webroot
$ git clone --depth 1 --no-single-branch https://github.com/CORE-POS/IS4C.git
$ cd IS4C
# Check this website for named releases.
#  If you don't 'git checkout' you will be in the branch called 'master'.
$ git checkout version-2.11

If you are using your own fork, substitute your fork's URL in the clone step. To maintain a reference in your fork to the upstream project, type:

$ git remote add upstream https://github.com/CORE-POS/IS4C.git

Installing Dependencies

If necessary first install Composer on your system, then

$ cd /path/to/webroot/IS4C
$ cp composer.json.dist composer.json
# You may need to install composer. On Ubuntu:
#  $ apt-get install composer
$ composer install
# This may not work because of missing PHP extensions:
#  "the requested PHP extension gd is missing from your system."
# To get them under Ubuntu:
# $ apt-cache search gd php
# If that reports it available:
# php5.6-gd - GD module for PHP
# then
# $ apt-get install php5.6-gd
# Try again
# $ composer update
# If it succeeds composer.lock is created.

This will create a vendor directory containing all the default dependencies. To install additional plugin packages use the require command, e.g.

$ composer require vendor-name/package-name

Installing Office

First Download CORE and Install Dependencies as described above.

  • Locate the directory named fannie in the downloaded folder. Inside fannie is a file named config.php.dist. Make a copy of this named config.php.
  • Now open a browser and navigate to fannie/install/ in the downloaded folder.
    • If it says config.php is missing, double check this first step.
    • If it says config.php is not writable, follow the on screen steps to resolve. config.php must be writable by the web server to save its configuration.
  • Fill in the the server database host, type, name, and password. You may specify different database names for operational, transaction, and archive data if desired.
  • Click Save Configuration at the bottom of the page. If the database connection fails you will see an error message detailing the problem. Otherwise Office will create all of the database structures it requires. This may take a little while to complete. Any errors with specific tables or views will be noted on screen.

Installing Lane

First Download CORE and Install Dependencies as described above.

  • Locate the directory named pos/is4c-nf in the downloaded folder. Inside pos/is4c-nf is a file named ini.php.dist. Make a copy of this named ini.php.
  • Now open a browser and navigate to pos/is4c-nf/install/ in the downloaded folder.
    • If it says ini.php is missing, double check this first step.
    • If it says ini.php is not writable, follow the on screen steps to resolve. ini.php must be writable by the web server to save its configuration.
  • Fill in the lane database host, type, name, and password. You may specify different database names for operational and transaction data if desired. The server database host, type, name, and password should refer to an Office server's transaction database. If you do not have an Office server, you can simply leave this blank or use the lane values so the single machine fills both roles. In the latter setup, the server database name must be different than the lane operational and transaction database names.
  • Adding hardware peripherals. Scanner scale and card terminals are managed by the New Magellan driver. Prebuilt drivers are available if you don't want to compile it yourself.
  • Enable the Paycards Plugin if using integrated card processing.
  • Lane Troubleshooting

Linking Components: Office => Lane

To link lane(s) to Office, go to the Office install/config page. Enter the number of lanes and save. Now fill in the IP address(es), MySQL username(s), MySQL password(s), and database name(s) for the connected lanes. Note that the lane firewall must allow connections to MySQL on port 3306 and the MySQL user account on the lane must be configured to allow remote access. Use the GRANT command in MySQL to create user accounts or add remote access to an existing account.

Linking Components: Lane => Office

To link a lane back to Office, go to the lane's install/config page. Enter Office's IP and MySQL credentials in the Server database section. Use Office's transactional database name for the lane's server database name setting. Note that the firewall on Office must allow connections to MySQL on port 3306 and the MySQL user account on the server must be configured to allow remote access. Use the GRANT command in MySQL to create user accounts or add remote access to an existing account.

Performance Tuning

CORE should work just fine without any special tuning but this section includes a handful of ideas. Optimizing the performance of PHP, Apache, and MySQL are all well-worn topics and most advice online is good. The only major difference in the case of POS is that network time is not a major consideration so something like gzip compression that uses extra CPU to reduce the request body size may not be a good tradeoff.

Apache Suggestions

  • Set AllowOverride to None. Disabling .htaccess files means the server doesn't need to search for them before processing a request.
  • Set Options +FollowSymLinks so the server can skip checking whether or not a file is a symlink.
  • Set KeepAlive On. In particular on the lane there's no reason to close connection between requests.
  • Disable the access log to reduce disk I/O (find the line(s) that start with CustomLog and comment them out).
  • Comment out or remove LoadModule directives for modules you aren't using. This reduces Apache's memory usage.

PHP Suggestions

  • Disable modules you aren't using. The bare minimum is a driver for your database (typically mysqli, PDO, or mysql). POS also requires sockets. Integrated card processing requires cURL and OpenSSL. LDAP is required for LDAP-based authentication. Some spreadsheet report formats may require DOM, XSL, and Pear.
  • Use Zend OpCache. This extension is the replacement of APC as of PHP 5.5 and is supposed to be better. It's available as a PECL extension for PHP 5.3+. Installing on a linux system is probably "sudo pecl install zendopcache". If "pecl" isn't available, you need to install the base PEAR package for your distro. Whether PHP ini file(s) need to be edited to enable the new extension likely varies by distro.
  • Try FastCGI instead of mod_php (and report back whether or not it helps!)
    • If you choose to use FastCGI, or find it is being used (see "Server API" in phpinfo()), set auto_globals_jit=false in your PHP configuration.

MySQL

  • Disable DNS lookups. Either put "skip-name-resolve" in my.cnf so lookups don't occur at all or put common clients in the OS' hosts file so lookups are near instantaneous.
  • Convert tables to InnoDB storage engine. CORE never requires a specific storage engine and will use the server's default when creating tables.
  • Ensure tables have consistent character set and collation. Again CORE will always use the server's default when creating tables. However, if you're moving data between servers with different settings using mysqldump you could end up with mismatches that slow performance.
  • Use a dedicated database server (Office only). Hosting Apache and MySQL on separate machines may well improve the performance of both but the database is most often the bottleneck.

Windows Notes

Windows setup tends to be more annoying. You need a PHP binaries and Apache binaries that are compatible with each other and with an installed Visual C runtime. These are usually listed as VC9, VC11, etc.

  • Apache binaries are found at Apache Lounge rather than Apache's own site. The Download page has links on the upper left for different VC versions. VC9, VC11, and VC14 versions of Apache 2.2 and 2.4 have been used in production.
    • Installing Apache
      • Download from Apache Lounge and unzip the file. It should contain a directory named "Apache2" or "Apache24" depending which version you chose. Copy this directory to C:\ for simplest configuration.
      • Run cmd.exe as administrator and go to the bin directory (i.e., C:\Apache2\bin or C:\Apache24\bin)
      • Run "httpd.exe -k install" to add Apache as a Windows service
      • Run "net start Apache2.2" or "net start Apache2.4" to start the service
    • If errors occur, make sure you have the appropriate VC runtime installed
  • PHP binaries are found at windows.php.net. Again you need a matching VC version; you also need the thread-safe version. You also want a PHP version compiled against the same version of OpenSSL as Apache. This is usually 0.9.8 or 1.1.0.
    • For PHP 5.4.26 and higher have trouble loading the php_curl extension. Copy the libssh2.dll included with PHP into Apache's bin directory. Copying libssh2.dll is also necessary for PHP 5.5 and 5.6.
    • Installing PHP
      • Download a PHP binary, unzip it, and place it at C:\ (you don't have to put it there, but complex paths can cause problems later on)
      • Find your Apache config file (e.g., "C:\Apache2\conf\httpd.conf" or "C:\Apache24\conf\httpd.conf")
      • Find the "DirectoryIndex" line and add "index.php"
      • Add these lines to enable PHP:
        • PHPIniDir "C:/PHP5"
        • LoadModule php5_module "C:/PHP5/php5apache2_4.dll"
        • AddHandler application/x-httpd-php .php
      • Note: the LoadModule line should use php5apache2_2.dll with Apache 2.2 and php5apache2_4.dll with Apache 2.4.
      • Go to C:\PHP5 and copy either php.ini-development or php.ini-production to php.ini. Make additional edits as needed (typically set a timezone, enable extensions, possibly set extension_dir).
      • Restart the Apache service (see above)
      • You can install multiple versions of PHP side by side - e.g., C:\PHP5.3.29, C:\PHP5.4.38, C:\PHP5.5.23, etc. Just alter Apache's httpd.conf to point at a particular PHP version and restart the Apache service. This is the safest way to test new versions and roll back if needed. When installing a new version, you probably want to copy the php.ini file from the current version's directory to the new version's directory.
  • MySQL is much simpler. Just download the Windows installer and click next a lot. When the option comes up to include MySQL in the system PATH, choosing yes may be a good idea. I'm not sure if PHP's mysql extensions are statically or dynamically linked.
Add a custom footer
Clone this wiki locally