Scheduling, job, crew, and customer management web application for construction companies.

• Homepage: https://katmore.github.io/clientcal
• Github: https://github.com/katmore/clientcal
• Packagist: https://packagist.org/packages/katmore/clientcal
• Latest release: https://github.com/katmore/clientcal/releases/latest
• Download: .zip file, .tar.gz

ClientCal is a PHP+MySQL based project initially released in 2006 to facilitate the management of customer info, job scheduling, job site info, and work crew scheduling for small to medium sized construction operations (SMBs). As a traditional HTML form based application it has proved to be very stable over the years. I have released this project in preparation for improvements to the UI (to make it mobile friendly) and implementing a RESTful API backend.

• Installation
• Utilities
• Upgrades
  • Update workflow
• Docker
  • Docker-compose application
  • Docker images
• Screenshots

Completing the installation of ClientCal involves 5 steps (after you have copied the source somewhere).

git clone https://github.com/katmore/clientcal.git 
cd clientcal

Composer update

Use composer update to install the necessary dependencies.

composer update

MySQL Preparation

A MySQL (or MariaDB) database must be provisioned along with a MySQL user with corresponding permissions by external means, such as with the mysql console.

mysql> CREATE DATABASE clientcal;
mysql> GRANT ALL ON clientcal.* TO 'clientcal'@'localhost' IDENTIFIED BY ...

Initialize configuration

Use the command-line config update utility to customize and properly configure the local clientcal installation.

php bin/config-update.php

Initialize Database

Use the the command-line database update utility to install the latest database structure.

php bin/db-update.php

Create a web user

Use the command-line user manager utility to create at least one web user that can login to the ClientCal web application.

php bin/web-user.php add my_user

Active deployments of ClientCal can be safely upgraded in-place using a 3 step workflow.

The ClientCal source itself can be updated using the same means as when it was copied to a local system initially.

cd clientcal
git update

Use composer update to upgrade and install any new dependencies.

composer update

Use the config update utility command-line script to safely upgrade the existing ClientCal configuration.

php bin/config-update.php

Use the database update utility command-line script to safely apply database schema updates (database migrations).

php bin/db-update.php

The ClientCal project includes command-line utility scripts to facilitate installation and ongoing operation.

• user manager utility
• database export utility
• database update utility
• configuration update utility

• Location: bin/web-user.php

The user manager utility manages ClientCal web users. Web users can be created, removed, and modified.

web-user.php commands:

• add: creates a new user

  php bin/web-user.php add my_user

• set-password: modifies an existing user's password

  php bin/web-user.php set-password my_user

• remove: removes an existing user

  php bin/web-user.php remove my_user

See web-user.php --help for details regarding advanced usage (such as quiet mode and avoiding interactive prompts):

php bin/web-user.php --help

• Location: bin/db-export.php

The database export utility facilitates the creation of database backups of the ClientCal database using the local installation configuration.

See db-export.php --help for details regarding advanced usage (such as quiet mode or specifying the output file basename and full path):

php bin/db-export.php --help

• Location: bin/db-update.php

The database update utility can be invoked without any arguments; it will prompt for all the required parameters (such as the host, dbname, user, pass, etc.). It reads the app/data/db-schema.json file which specifies the latest database structure version and relative locations of the corresponding SQL resources. The latest SQL update and structure dumps for ClientCal are contained in the app/data/schema-sql directory. When a database is empty (i.e. contains no tables), the database is created from scratch using the SQL dump file of the latest database revision. For existing databases, migrations are perfomed using SQL update files as specified by a database revsions corresponding db-version.json file. The current applied schema version is stored in the table schema_version of the same database.

See db-update.php --help for details regarding advanced usage (such as quiet mode and avoiding interactive prompts).

php bin/db-update.php --help

• Location: bin/config-update.php

php bin/config-update.php

The configuration update utility creates and updates configuration file values in the ClientCal config path (/app/config/clientcal) by reading values from *-sample.php files. The utility provides a prompt to input each configuration value; along with a default value. The utility resolves the "default value" by using the existing configuration value; if no configuration value yet exists, the "default value" is obtained from the -sample.php file. If the utility is started with the --non-interactive option, the default values are automatically used.

See config-update.php --help for details regarding advanced usage (such as quiet mode and avoiding interactive prompts).

php bin/config-update.php --help

A docker-compose application is provided using docker-compose. It facilitates deploying a self-contained ClientCal application without the need to perform the individual "Installation Steps" other than managing web-users with the user manager utility. See docker-compose.yml for full configuration details.

• docker version 18.03 or newer
• docker-compose version 1.19 or newer

cd docker/compose/clientcal
docker-compose build
docker-compose up

When docker-compose containers are run (via docker-compose up or docker compose start), the following occurs:

• non-ephemerial MySQL data is mounted on the host system
• the database is initialized if starting the first time using the latest schema dump according to db-schema.json
• php-fpm starts, and is available to nginx
• nginx starts, and the ClientCal application is available on the local system
  • Default Entrypoint URL: http://localhost:8080
• PHP errors are logged to the terminal as they occur (as long as the 'php-fpm' container is attached to your terminal, i.e. docker-compose up)
• nginx errors are logged to the terminal as they occur (as long as the 'nginx' container is attached to your terminal, i.e. docker-compose up)

The docker-compose configuration included with this project IS NOT suitable for public deployment of ClientCal as provided. It could be made suitable to deploy publicly only if modifications are made to provide provide SSL.

Examples of how to accomplish a safe public deployment with docker:

• modifying the provided nginx configuration (such as with a volume mount) to use SSL
• deploying a separate public facing HTTP server with SSL that is configured to be a reverse proxy to the clientcal docker network port 8080
• deploying a separate public facing HTTP server with SSL that is configured to use Fast-CGI over the clientcal docker network port 9000

The following images are included to facilitate ClientCal usage with docker.

• php
• mariadb

• php/Dockerfile

The "php" docker image contains all dependencies for running the ClientCal web application. It is suitable for stand-alone use (i.e. docker run ...) or in conjunction with docker-compose (such as configured in the "docker environment" included in this project). It uses alpine linux and the PHP Repositories for Alpine - by CODECASTS for php related packages.

• mariadb/Dockerfile

The "mariadb" docker image provides a MariaDB service suitable for use with the "docker-compose environment" included in this project. It uses the official mariadb image with some user permissions tweaks to better facilitate executing seed scripts and saving non-ephemerial data to the host.

• Month View:

  

ClientCal is distributed under the terms and conditions of the MIT license (see LICENSE), or the terms and conditions of the GPLv3 license (see GPLv3).

Copyright (c) 2006-2018, Paul Douglas Bird II. All rights reserved.