# Current release: 0.10.0 This documentation explains how to install, enhance and use OpenCATS, the free open-source applicant tracking system available at opencats.org. ## Release information The current OpenCATS application release documented here is **0.10.0**. The latest release packages are published at . ## Supported platform baseline OpenCATS is built and tested in CI on a Linux/Unix environment with **PHP 7.4** and **MariaDB 10.7**. Other versions or platforms may work, but they are not the CI/CD baseline used by the project. The main runtime dependencies are PHP, MariaDB, a web server, and the PHP extensions required by OpenCATS. Optional document parsing utilities such as `antiword`, `pdftotext`, `html2text`, and `unrtf` improve resume/document text extraction and search, but are not required just to complete installation. MySQL is not the documented database target. MariaDB is the recommended and tested database family for current OpenCATS deployments. ## Which package should I install? For a normal installation, download the release archive from GitHub Releases. Release archives are intended to be easier to install than a raw source checkout. If you install from source, clone the repository, or download source code instead of a prepared release archive, install PHP dependencies with Composer: ```bash composer install --no-dev ``` Use `--no-dev` for production so development and test packages are not installed. Developers who need to run the test suite should run Composer without `--no-dev`. ## Before upgrading Before upgrading an existing OpenCATS installation, take a CLI database backup, back up `attachments/`, preserve your `config.php`, and test the restore/upgrade process outside production first. See [Backup, Restore, and Upgrade](/technical-configuration-options/opencats-backup-restore-and-upgrade-instructions-this-section-incomplete). ## Documentation status This documentation is maintained by the OpenCATS community. If you find a mistake or a missing workflow, please submit a pull request to the GitBook documentation repository. # Introduction and Overview ![](/files/mmHODoyhS1hKhXvziPaD) OpenCATS is a free and open source, full-featured, web-based applicant tracking system, or ATS. It helps you manage the complete recruitment life-cycle from business development through finalizing a placement. It manages a huge range of information for you, including: ### What is an Applicant tracking system (ATS)?[¶](https://github.com/opencats/gitbook/blob/main/introduction-and-overview/broken-reference/README.md) An Applicant tracking system, or ATS, is software designed specifically for Recruiting firms, and HR departments within organizations to organize and track everything within the recruiting process for their organizations. ### How is it free and what is Open Source software?[¶](https://github.com/opencats/gitbook/blob/main/introduction-and-overview/broken-reference/README.md) Without getting too specific or technical on what is and is not open source, open source software is community developed software that is available to use for free, by anyone, at any time, in any way they choose to. It is truly “free” software. Furthermore, because of the open nature, if you want to dig into the code and customize it, you are allowed to. If you want to share your changes back with the community, you are allowed to (please do!). There are a lot of different variances in open source software and they’ve been covered extensively online. If you want to really dig into, and understand the purpose, intentions, limitations of open source software, please read up on it. The developers behind OpenCATS will never contact you to try to sell you anything. We are a community of people creating recruiting software for people who do recruiting. Pure and simple. ### OpenCATS vs CATSOne vs “open source”[¶](https://github.com/opencats/gitbook/blob/main/introduction-and-overview/broken-reference/README.md) OpenCATS is a free, open-source ATS. This means that there are no charges or limitations to install or to use it. * For software developers, this also means that you are free to modify or extend the OpenCATS software, and to participate as a member of its development community. * This also means that there is no help desk that you can call for support, though we do have this documentation, some YouTube videos, support forums and a community that helps. The origins of OpenCATS are in a commercial/open-source development effort called CATS, which split into two separate efforts: * This open-source OpenCATS system: [http://www.opencats.org](http://www.opencats.org/) * The commercial CATS product: [http://www.catsone.com](http://www.catsone.com/) The commercial CATS product is a highly polished, professionally supported, hosted software service. OpenCATS, on the other hand, has somewhat less functionality, is installed on your server(s), and is supported only by you – with some help from the community. The OpenCATS team and the CATSOne organization are not associated in any way. We will not push anyone into any paid service, any time, ever. ### What can OpenCATS be used for?[¶](https://github.com/opencats/gitbook/blob/main/introduction-and-overview/broken-reference/README.md) If you have to fill jobs, even if it’s only one or two jobs a year, OpenCATS can make your life a lot easier. It will work in small to enterprise sized environments. From one user to hundreds. ### How does OpenCATS compare to other free software and paid Applicant Tracking Systems?[¶](https://github.com/opencats/gitbook/blob/main/introduction-and-overview/broken-reference/README.md) If you compare OpenCATS to free resources out there, there’s nothing to compare. As far as I know, there are currently one open source applicant tracking system out there right now, which is an off-shoot of OpenCATS. The options as far as I can tell, are free tiers of paid applicant tracking systems that in my opinion don’t provide enough functionality to be practical for daily usage for any but the smallest recruiting environments. The only accurate comparison of a free Applicant tracking system would be the folks out there who are doing their tracking on excel sheets and storing resumes on their hard drives. If this is you….STOP IT! There is no reason to do that any more. OpenCATS solves your problems and is free. When you start comparing OpenCATS against the paid applicant tracking systems out there, it’s not such an easy decision. For example, even the lower priced applicant tracking systems generally are competitive or even far better than OpenCATS in terms of features. The higher priced, enterprise applicant tracking systems make OpenCATS (in it’s current state) an afterthought. So if you are willing to pay the monthly cost of even a cheaper applicant tracking system, and features that OpenCATS are lacking in are important enough, then a paid ATS may be a better option for you. The advantage in that scenario that OpenCATS still has however, is that OpenCATS is still free for multiple users. So, a low end applicant tracking system might bring value at $50/month for a solo recruiter over a free OpenCATS system. But, what if you have ten users? Are those features worth the $50/month per user price-tag ($500/month total)? These are factors to consider. Another aspect to OpenCATS that should be considered is data privacy and data security. With a self-hosted OpenCATS system, you are solely responsible for your data security. If you are managing that well, you won’t fall victim to the occasional hacks and data breaches you hear about on the news. Also, there is no chance of coming into the office one day to find that the company running your applicant tracking system has suddenly closed their doors overnight with no way to access your critical recruiting information. OpenCATS allows you to control the security of your data, and control of your recruiting information. There is tremendous value in that, if that is important to you. While OpenCATS is a perfectly functional applicant tracking system. It does not compete with most modern paid applicant tracking systems feature for feature. Whether it is the right solutions for you and your company is up to you! Test it out and decide. ### OpenCATS General Features[¶](https://github.com/opencats/gitbook/blob/main/introduction-and-overview/broken-reference/README.md) Try our demo! What better way to dig in to the OpenCATS capabilities and feature than to dig into it for yourself? [OpenCATS Demo](http://demo.opencats.org/) (Currently offline!) **Free:** OpenCATS is open source software. Which means it is free (no cost) to use, and you are free to modify it in (almost) any way you want. Seriously, if you can do it, get down into the code and change absolutely anything! **Support:** It also means support may be hard to find. We have an active community of people that are willing to help as much as possible though. Also, we are slowly adding to our documentation and YouTube channel. **It is easy:** OpenCATS has an easy to use, intuitive interface. This means minimal training time for you and your recruiters. The job portal has a simple search and application process that your candidates will get through easily. **Web based or local:** OpenCATS can be installed in a variety of environments. For the solo recruiter/single user, OpenCATS can be installed on your local computer, accessible only by you. OpenCATS can be installed on a local network, accessible by everyone within the office, with no limit on users, yet still protected and removed from the outside internet. OpenCATS can also be installed and accessible via the internet, through a public facing web server, A VPS, a shared-hosting environment, so multiple users from all over the world can access and use OpenCATS together. Keep in mind though, that because OpenCATS is open source software, security is your responsibility. Make sure the appropriate measures are taken for the setup that you choose. **Full recruiting life-cycle:** OpenCATS provides the infrastructure for the entire recruiting life-cycle, regardless of the type of role that you are recruiting for, or the volume of openings that you are dealing with. Note OpenCATS can get cumbersome for very high-volume recruiting due to the current lack of bulk recruiting features. Importing and dealing with many candidates at once per role may be prohibitive in OpenCATS. You would need to gauge the effort against the results and decide if OpenCATS is the best solution for your situation. OpenCATS will walk you through the process, including the sales cycle, from building targeted lead lists, making client calls, getting signed agreements and taking job orders. It will handle all of recruiting, from initial candidate intake, job posting and applications, through the interview, offer, acceptance and candidate start. OpenCATS was designed by recruiters, for recruiters and continues to be developed with recruiting as the sole focus. **Internal and external recruiting:** OpenCATS has all the functionality for companies that need an Applicant Tracking system for their internal recruiting as well as recruiting companies that are recruiting for multiple, external clients. For internal recruiting, all recruiting can be done by checking the “Internal posting” check-box on the job order. Departments can be created and customized within any organization, and contacts added for those departments. OpenCATS can be as thorough and specific as you need it to be. For recruiting firms with external clients, each client can be tracked individually, even if they have multiple locations, departments and hiring managers. The flexibility is there within OpenCATS to ensure accuracy throughout the recruiting process. **Company branding:** OpenCATS can be branded for your organization, you can replace the OpenCATS logo with your company logo, and the public-facing job posting page and outgoing emails, can be changed to match the look of your company’s website and emails. www **Skills based tagging:** Initially, OpenCATS had resume parsing and resume search built in. Over time, that functionality has been lost. The development team is focused on implementing long term solutions that will allow parsing and keyword search in OpenCATS. In the meantime, skill tagging is included in OpenCATS, and serves as a very functional alternative to keyword searching. **Lists:** OpenCATS can make lists for whatever you need. Lead lists for sales?Yes. Candidate hot-sheets? Yes. List by geographic location? Yes. Anything you may need a list for, sales or recruiting, you can generate in OpenCATS for quick access. Lists can also be conveniently be exported as a csv file for any external applications. **Calendar:** OpenCATS has a rich and immersive calendar built in that provides a thorough and accurate overview of activities. If you use the calendar system, you will always know what is coming up, and be able to quickly find information from past scheduled events. Unfortunately, at this time, there is no integration with any external calendar systems. OpenCATS can not sync with anything outside of OpenCATS. **Website integration and job board:** OpenCATS has a company job postings page built right in. All you have to do is turn it on and brand it however you want. All the “public” marked jobs in your OpenCATS system will show up on your jobs page, and candidates will be able to apply through your site. You can create questionnaires for candidates to answer prior to applying, to ensure only candidates that fit the requirements apply. The candidate would then be added to the pipeline of the job order, and the recruiter working the role would be notified of the new application for review. Lastly, your newly added openings can be automatically posted to certain job posting sites via a built in XML feed. This feature does not work with every job board out there, but it does work with some of the larger ones. **Candidate and client management:** From the first phone call to the last email. OpenCATS will help you keep track of all the details, activities, records, contact numbers and keep your work-flow managed. **Reporting:** Generate reports on recruiting activity for a quick and accurate overview. **Ownership of data:** You own it. It’s yours. You can control it and secure it however you want. No need for your data to be on someone else’s servers, unless that is how you choose to do it. **Backup and restore:** Your OpenCATS system can be backed up as often as you want, ensuring no loss of data, ever. There is an easy and intuitive GUI-driven backup/restore system. System administrators can also perform backups/restores through the MySQL database and file system if they prefer. Anyone can backup and restore OpenCATS, regardless of technical knowledge and ability. **User access levels:** Currently there are different access levels for users in the OpenCATS system, which the administrator can set up and assign. These are focused on the ability to manipulate data within OpenCATS. The OpenCATS dev team are working on features that will allow administrators to limit access to the records within OpenCATS (example: a recruiter will only be able to see the candidates/clients that are assigned to them, if that’s how you choose to set it up). **Built in Emailing:** The email functionality within OpenCATS is substantial. Currently, OpenCATS can be used to send emails to candidates, clients, and contacts. It can also be used to notify of status changes and new applications, or anything you would like it to do. Templates can be set up and used and branding can be included. **Built in modification system:** There are certain aspects of modifying OpenCATS that are built in and do not require any technical ability or coding. Fields can be added to the candidate, client, and contact pages quite easily. Any information you want included, or tracked, that isn’t built in to OpenCATS can be added through the intuitive interface with a few clicks. # Licensing OpenCATS licensing should mirror the application repository `LICENSE.md`. The application is available under two licenses: 1. OpenCATS code is under the **Mozilla Public License 2.0**. 2. Original code from the **CATS Project** circa 2007 is under the **CATS Public License Version 1.1a**, a modified Mozilla Public License. For the full license text, see the `LICENSE.md` file in the OpenCATS application repository: # Authors and Contributors OpenCATS is maintained by the OpenCATS community. ## Contributing The application source code is maintained at: Documentation is maintained separately in the GitBook documentation repository. Before opening an application pull request, review the current contributor guidance in the application repository. Pull request titles must use this format: If anyone has been forgotten, please let us know! # Installation OpenCATS can be installed from a release archive, from source with Composer, or in the repository Docker environment for development and testing. ## Choose an installation path * **Linux/Unix production-style install:** use the [Ubuntu installation guide](/installation/install-on-ubuntu) as the primary documented path. * **Windows/WAMP/XAMPP install:** use the [Windows guide](/installation/install-on-windows). OpenCATS is known to be deployed on Windows, but the project builds and tests only in a Linux/Unix CI environment. * **Docker:** use the [Docker guide](/technical-configuration-options/docker-opencats-installation-instructions) for development and testing. Some experienced users deploy Docker in production, but the repository Docker setup is not the recommended production configuration without hardening. * **Existing installation upgrade:** read [Backup, Restore, and Upgrade](/technical-configuration-options/opencats-backup-restore-and-upgrade-instructions-this-section-incomplete) before changing files or database schema. ## Baseline requirements OpenCATS 0.10.0 is built and tested with PHP 7.4 and MariaDB 10.7. Install required PHP extensions, create a MariaDB database and user, and ensure OpenCATS writable directories are owned by the web server user. If you use a source checkout or source archive instead of a prepared release archive, install dependencies with: ```bash composer install --no-dev ``` After files, database, and permissions are ready, continue to [Run the Installer](/installation/run-the-installer). # Install on Ubuntu These instructions describe a Linux/Apache/MariaDB/PHP installation path for OpenCATS 0.10.0. Commands may need small adjustments for your Ubuntu release and package repositories. ## Install MariaDB and Apache ```bash sudo apt-get update sudo apt-get install mariadb-server mariadb-client apache2 unzip wget sudo mysql_secure_installation ``` MariaDB is the documented database family for OpenCATS. Current CI Docker tests use MariaDB 10.7. ## Install PHP 7.4 and extensions OpenCATS 0.10.0 requires PHP 7.4. If your Ubuntu release does not provide PHP 7.4 packages directly, use a trusted package source such as the Ondrej Surý PHP PPA. ```bash sudo add-apt-repository ppa:ondrej/php sudo apt-get update sudo apt-get install php7.4 php7.4-cli php7.4-fpm php7.4-mysql php7.4-gd php7.4-soap php7.4-ldap php7.4-xml php7.4-curl php7.4-mbstring php7.4-zip sudo systemctl restart apache2 ``` Depending on your Apache configuration, you may use PHP-FPM or an Apache PHP module. Confirm that the web server is actually using PHP 7.4 before running the installer. ## Optional document parsing utilities Install these if you want OpenCATS to extract text from common resume and document formats: ```bash sudo apt-get install antiword poppler-utils html2text unrtf ``` After installation, verify or update the parser paths in `config.php` if your distribution installs binaries in non-standard locations. ## Create the MariaDB database and user Log in to MariaDB as root: ```bash sudo mysql -u root -p ``` Then create a database and user. Replace `databasepassword` with a strong unique password. ```sql CREATE DATABASE opencats CHARACTER SET utf8 COLLATE utf8_general_ci; CREATE USER 'opencats'@'localhost' IDENTIFIED BY 'databasepassword'; GRANT ALL PRIVILEGES ON opencats.* TO 'opencats'@'localhost'; FLUSH PRIVILEGES; EXIT; ``` These database credentials are separate from your OpenCATS application login. ## Download OpenCATS Download the latest release archive from [GitHub Releases](https://github.com/opencats/OpenCATS/releases). For OpenCATS 0.10.0, an example release archive workflow is: ```bash cd /var/www/html sudo wget https://github.com/opencats/OpenCATS/releases/download/v0.10.0/opencats-v0.10.0.zip sudo unzip opencats-v0.10.0.zip -d opencats ``` If the release asset name differs, use the exact filename shown on GitHub Releases. ## Installing from source instead If you clone the repository or download source code instead of using a prepared release archive, install Composer dependencies: ```bash cd /var/www/html/opencats composer install --no-dev ``` Use `--no-dev` for production-style installs. ## Configure ownership and permissions The web server user must own or be able to write OpenCATS runtime directories: ```bash sudo chown -R www-data:www-data /var/www/html/opencats sudo chmod 750 /var/www/html/opencats sudo chmod 770 /var/www/html/opencats/attachments sudo chmod 770 /var/www/html/opencats/upload sudo chmod 770 /var/www/html/opencats/temp ``` If you restore from a GUI backup file, also create and make a `restore/` directory writable by the web server user. ## Start the installer Open your browser at your OpenCATS URL, for example: ``` http://your-server/opencats/ ``` If an `INSTALL_BLOCK` file exists before first install, remove it so the installer can run: ```bash sudo rm /var/www/html/opencats/INSTALL_BLOCK ``` After installation, confirm `INSTALL_BLOCK` exists so the installer is not exposed again. Now continue to [Run the Installer](/installation/run-the-installer). # Install on Windows OpenCATS is known to be deployed in many Windows/WAMP/XAMPP environments. However, the OpenCATS project builds and tests in a Linux/Unix CI environment only. WAMP and XAMPP can work, but Windows-specific behavior is not covered by automated project testing. ## Windows prerequisites Install a Windows web stack that provides: * PHP 7.4 * MariaDB * Apache or another PHP-capable web server * phpMyAdmin or another MariaDB administration tool XAMPP and WAMP are common choices. Select a package that includes PHP 7.4 or lets you install PHP 7.4. ## Download OpenCATS Download the current release archive from [GitHub Releases](https://github.com/opencats/OpenCATS/releases). Extract it under your web root, for example: ``` C:\xampp\htdocs\opencats ``` If you download source code or clone the repository instead of using a release archive, install Composer for Windows and run this from the OpenCATS directory: ```bat composer install --no-dev ``` ## Start Apache and MariaDB Open your XAMPP or WAMP control panel and start only the services you need: * Apache * MariaDB/MySQL service provided by the stack Even if the control panel labels the service as MySQL, use a MariaDB-backed stack for the documented OpenCATS path. ## Create the database in phpMyAdmin Open phpMyAdmin, usually at: ``` http://localhost/phpmyadmin/ ``` Create a database named `opencats`. Use UTF-8 character set and collation when available, for example: ```sql CREATE DATABASE opencats CHARACTER SET utf8 COLLATE utf8_general_ci; ``` Create a database user, for example `opencats`, and grant that user all privileges on the `opencats` database. Use a strong password and save it for the installer. ## Configure parser utility paths on Windows Document parser utilities are optional, but if you install them, Windows paths in `config.php` must use escaped backslashes. For example: ```php define('ANTIWORD_PATH', 'C:\\antiword\\antiword.exe'); define('PDFTOTEXT_PATH', 'C:\\path\\to\\pdftotext.exe'); define('HTML2TEXT_PATH', 'C:\\path\\to\\html2text.exe'); define('UNRTF_PATH', 'C:\\path\\to\\unrtf.exe'); ``` ## Run the installer Open your browser at: ``` http://localhost/opencats/ ``` If an `INSTALL_BLOCK` file exists before first install, remove it so the installer can start. After installation, confirm `INSTALL_BLOCK` exists again so the installer is not left exposed. Continue to [Run the Installer](/installation/run-the-installer). # Run the Installer After the web server, PHP, MariaDB database, OpenCATS files, and directory permissions are ready, open OpenCATS in your browser. For a local installation, use: ``` http://localhost/opencats/ ``` For a server or VPS, use the hostname and path you configured. ## If the installer does not start OpenCATS starts the installer when `INSTALL_BLOCK` is missing. If you are doing a first-time installation and the installer does not appear, check whether `INSTALL_BLOCK` exists in the OpenCATS directory and remove it only for the installation step. After installation or upgrade, confirm `INSTALL_BLOCK` exists again so the installer is not exposed. ## Database connectivity Enter the MariaDB database name, user, password, and host you created during installation. Common host values: * `localhost` for a normal local Linux or Windows stack. * `opencatsdb` for the repository Docker Compose development environment. * A hosting-provider database hostname for shared hosting or managed database services. Use the installer database connectivity test before continuing. If the test fails, confirm: * the database exists; * the database user has privileges on that database; * the password is correct; * the database host is reachable from the web server; * PHP has the MariaDB/MySQL extension installed. ## Resume indexing and document parsing OpenCATS can use external tools to extract text from uploaded resumes and documents. The installer may ask for paths to these tools. Typical Linux paths are: ``` /usr/bin/antiword /usr/bin/pdftotext /usr/bin/html2text /usr/bin/unrtf ``` OpenCATS can be installed without these tools. Resume indexing and text extraction will be limited until you install the utilities and configure the paths in `config.php`. ## Mail settings OpenCATS can send mail through PHP mail, Sendmail, or SMTP. If you do not want OpenCATS to send email immediately, disable mail during installation and configure it later. For SMTP, collect these values before enabling mail: * SMTP host * SMTP port * authentication username * authentication password or app password * security mode such as `tls` or `ssl` OpenCATS uses PHPMailer for email delivery. ## Installation type The installer may offer options such as: * new installation; * demo/test data installation; * restore from backup; * use an existing OpenCATS database and perform required upgrades. For production upgrades, use the existing installation/upgrade path only after taking CLI backups and testing the upgrade on a copy of production data. ## First login For a new installation, the default login is commonly: ``` admin / admin ``` Change the administrator password immediately after logging in. ## Post-install checklist After clicking `Start OpenCATS` and logging in: * Change the default administrator password. * Confirm `INSTALL_BLOCK` exists. * Confirm `attachments/`, `upload/`, and `temp/` permissions are no broader than necessary. * Configure upload-directory execution restrictions before exposing the career portal or accepting uploads. * Configure mail and scheduled reminders if needed. * Take an initial CLI database and attachments backup. If you are exposing OpenCATS to the web, review [Security](/technical-configuration-options/security) and [Vital Security: Restrict access to upload folders (.htaccess)](/technical-configuration-options/vital-security-restrict-access-to-upload-folders-.htaccess). # Using the software # Companies, contacts, job orders, and candidates ### Using OpenCATS-The building blocks: companies, contacts, job orders, and candidates[¶](https://github.com/opencats/gitbook/blob/main/using-the-software/broken-reference/README.md) ### The modules[¶](https://github.com/opencats/gitbook/blob/main/using-the-software/broken-reference/README.md) OpenCATS is made up of the following modules: **Home:** When you log into CATS, you will see the Home module. This is your dashboard, which lists your activities. The Dashboard is customizable from the Settings module. **Activities:** All of your daily activities and interactions with candidates, companies and contacts are populated in this module. **Job Orders:** All of the available Job Orders are displayed in this module. Search existing and create new Job Orders. **Candidates:** All of the available Candidates are displayed in this module. Search existing and create new Candidates. Access your Saved Lists. **Companies:** All of the available Companies are displayed in this module. Search existing and create new Companies. **Contacts:** All of the available Candidates are displayed in this module. Search existing and create new Contacts. Access your Cold Call List. **Calendar:** All scheduled events are populated in this module. By default, the Calendar shows the week view of the current week. Add new Events and access your Upcoming Events. **Reports:** All available reports are populated in this module. **Settings:** Options to customize your account and CATS features are available in this module. Users change your Profile, Password. Administrators access your account, change your Career Portal and E- mail configurations, and customize your dashboard, import and backup data. Note Let’s start entering in information and populating our fantastic new OpenCATS system. ### Add a new Company[¶](https://github.com/opencats/gitbook/blob/main/using-the-software/broken-reference/README.md) Click on `Companies` Note I have already entered some test information. A new system screen will look a little different. This is your main company screen. This will have an overview of all the companies in your OpenCATS system. From new leads, to active clients and old clients. They will all be here. Note For internal hiring (your company), select `Internal postings` as the client. Click on `Add Company` There are two ways to add information into OpenCATS. * Copy and paste it into the box labeled `cut and paste free-form address here` Then click the `<--` button to populate the fields. * Manually type and paste it into each field on the left. Note Don’t forget to enter key technologies for the company and any miscellaneous notes that you want to save in the bottom two fields for future reference. Warning The success rate of auto-populating the information fields for me has always been terrible. Sometimes it works great, sometimes it’s doesn’t. I usually just enter the fields one at a time manually. If it worked, it should look like this. If some of the information did not populate, manually enter it and let’s move one. This is what you should see. Click `Add Company` Voila! You have a new client! If you want to add any relevant attachment documents such as a copy of your client agreement, benefits overview, etc. Click the `Add Attachment` button. ### Add a new Contact[¶](https://github.com/opencats/gitbook/blob/main/using-the-software/broken-reference/README.md) Next let’s add a Company Contact. Click `Add Contact` at the bottom of the current screen. Fill in all the information fields, including any relevant notes that’s you want to remember for later. Then click `Add Contact` You should now see the contact listed in the Contacts section of the Company screen. ### Add a new Job Order[¶](https://github.com/opencats/gitbook/blob/main/using-the-software/broken-reference/README.md) From the current screen, let’s add our first Job order. Click `Add Job Order` in the Job Orders section of Bob’s Company page. Note OpenCATS is set up to run Direct-hire (Perm) or Contract (project) jobs. We will note the differences below. Let’s look at the fields in the **Add Job Order** screen: The fields on the upper left column are self-explanatory. * **Start Date** is when the hired candidate should start. * **Duration** The length of contract (Project) for a temporary role. It this is a permanent role, you can put “direct hire”, whatever you want, or just leave it blank. * **Maximum rate** Self-explanatory * **Type** This drop-down field let’s you select the type of role. Options are: Hire, Contract to hire, Contract, or freelance * **Salary** Put the salary range here * **Openings** Number of openings * **Company Job ID** This is for the unique Job ID assigned to this role. * **Hot** If this is a hot job, check this box. * **Public** If you have the OpenCATS job board set up (we will do this later), checking this box will make this job order visible on it. Candidates will be able to view and apply. * **Description** Enter your job description here * **Internal Notes** Any notes or information entered here will be visible within your company, but not visible on your public job board. Note If you have the public job board set up (we will go through this later), all the information on this screen **except** the **Internal Notes** section will be viewable to anyone looking at your jobs. Including the listed salary information. If you do not want that visible, put it in the **Internal Notes** section. Click `Add Job Order` This will take you to your new Job Order screen. If everything looks correct, let’s move on to adding our first candidate in OpenCATS and into the pipeline for this job. ### Adding a Candidate and attaching them to the Job Order pipeline[¶](https://github.com/opencats/gitbook/blob/main/using-the-software/broken-reference/README.md) Click `Add Candidate to This Job Order Pipeline` at the bottom of the screen. Then `Add Candidate`. Click `Browse` to upload a resume from your local file system. From this screen you need to manually copy and paste into the information fields on the left. When you have filled out all of the necessary information, click `Add Candidate` in the bottom left corner. Success! We have a candidate in the pipeline! Note Make sure to Rate your candidates with the stars under **Match** on the bottom this screen. It will help with quick reference later on. ## Current behavior notes for OpenCATS 0.10.0 Recent OpenCATS versions changed several day-to-day workflows: * **Contact title is optional.** You can create a contact without entering a title if that information is not known. * **Job order state is optional.** Job orders can be saved without a state value when the role is remote, international, or otherwise not tied to a state/province. * **Activity date and time can be set manually.** The date/time when an activity happened is separate from the date/time when the record was created. * **Closed jobs are excluded from activity job references.** When logging activities, expect closed job orders to be hidden from active job reference lists. * **Status change notes are safely rendered by templates.** Do not rely on custom inline HTML being stored in activity notes. These changes make data entry more flexible while keeping activity history clearer. # Screens In-Depth [OpenCATS](broken://pages/RIgE1m24ArFwfc7kSFi9) In this section, we will go through each of the OpenCATS screens in depth and go over all of the various functions. ### OpenCATS dashboard/home screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) Note The OpenCATS dashboard (home screen) is broken up into three rows at the top and a grid of six sections below. * **The main OpenCATS module tabs:** The main navigation tabs. * **Recent:** Your five most recently viewed candidates/contacts. Names are clickable for quick access. * **Quick Search:** Search for candidate/contact name, job title, and Company name * **My Recent Calls:** Most recent candidate/contact calls. Names are clickable for quick access. * **My upcoming calls:** List of upcoming, scheduled calls, IF scheduled in OpenCATS. * **My upcoming events:** List of upcoming, scheduled calls, IF scheduled in OpenCATS. * **Recent Hires:** Short list of your company’s most recent hires * **Hiring Overview:** Overview of submission/interviews/hires. You can select weekly, monthly or yearly tabs on the right * **Important Candidates:** Small overview of some recent candidate activity. The columns in this section are adjustable by dragging the column title left or right. ### Activities Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) The activities screen gives you an overview of recent candidate, company and contact activities. Note The rows at the top always stay the same in OpenCATS (Main navigation tabs, recent, and quick search). We won’t cover that again in the documentation. * **Time-frame of results:** Click these to filter your results by day, week, month, etc. * **Rows per page:** Click the drop-down bar to change the amount of results per screen. 15, 30, 50, or 100 * **Filter:** Options to filter results by Date, Regarding, Activity, Notes, Entered By * **Activity columns:** * **Show Columns:** Select which columns to be visible in the activities grid * **Rearrange Columns:** Columns can be moved left and right by grabbing the column name and moving it left or right. * **Sort Columns:** Each column can also be sorted alphabetically by clicking the column title at the top of the column. ### Job Orders Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) The Job Orders screen is job order specific. It is where all the job orders are. Note The job order screen is structured similarly to the Activities screen. So we won’t go through the same features again. In the top, right, highlighted row, we have the following: * **Active/On Hold/Full Drop-down box:** This allows you to filter your results based on the status of the job order. Options are: `Active/On Hold/Full`, `Active`, `On Hold/Full`, `Closed/Canceled`, `Upcoming/Lead`, `ALL`. * **Only My Job Orders:** This will return results that are only your job orders. * **Only Hot Job Orders:** This will return results that are only marked as Hot Jobs. **Show Columns (highlighted box, upper right corner of grid):** There are quite a few options here to select or deselect. The checked options will include in the job order screen information. See image below. Note As with the other screens, all columns can be moved left and right, as well as sorted alphabetically. The last thing to note on the Job order screen is the action button in the bottom left corner. Action: * Clicking the action button will allow you to export results to a .csv sheet, or import results to a hot-list within the OpenCATS system. We will go into those further later in the documentation. Add specified job orders to an OpenCATS Hot-list, or export them to a CSV: * Select the checkbox (next to `action`), this will select all the boxes on this screen only. * Manually select specified candidates * Then `export` or `add to list` and click `selected`. OR: * select `action` then `add to list` or `export` and select `all` to include the entire database (in this case, it would include ALL of the job orders in your OpenCATS system) in your hot-list or CSV export. ### Candidates Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) The main Candidates screen is laid out similarly to the others. There are two checkboxes in upper right for filtering the results on this screen. `Only My Candidates` and `Only Hot Candidates`. Again, there are additional options below that with the `Rows Per Page` dropdown and the `Filter` dropdown. As before, the columns can be moved right and left by dragging the column title word at the top, and columns can be added or removed by the Show Columns (Image of a grid) in the upper left corner of the main section of the candidates screen. See example below. There are different options for candidates in the `Action` button at the bottom left. You can select specific candidates, the candidates showing on the screen, or all of the candidates in OpenCATS and `Add to List`, `Add To Pipeline`, `Send E-Mail`, or `Export`. * **Add to List:** Add to a hotlist * **Add To Pipeline:** Add to a job order pipeline * **Send E-Mail:** Means type your own email to candidate(s) or use an OpenCATS template. * **Export:** Export selected candidates to a csv file. ### Companies Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) The main Companies page is very similar to the Candidates page. Everything functions the same, and it has the same options. The only exception is that there are different columns available to choose in the `Show Columns` button. See image below. ### Lists Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) Hot lists, Lead Lists, tear sheets, call lists. Whatever you call them, most recruiters have used them at some point. OpenCATs has them here. The only new clickable button on the Lists screen is the `Show Lists` button in the upper right corner of the blue bar. ### Calendar Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) The Calendar is a central hub for your OpenCATS usage. Every phone call and event, if scheduled through OpenCATS will appear here. The default Calendar screen will show a list of upcoming events in the left column and a Calendar overview on the right. * `My Upcoming Events:` Shows all upcoming, scheduled events in the left column. * `Add Event:` Add a new event to your calendar * `Goto Today:` Shows you todays events * Calendar date views can be changed by clicking: `Day`, `Week`, or `Month`. * The Green Arrows can be clicked to move you back or forward on the Calendar. Every Event box within the calendar is clickable for event information, which will appear in the left column. Red Arrows: * The first arrow points to a clickable icon that opens up the record of the Candidate included in the scheduled event. * The middle red arrow points to an icon that indicates this is a “Public” event, which means it is viewable by any OpenCATS user. * The third red arrow points to a clickable icon that opens up the record of the Contact included in the scheduled event. * Lastly, every date number on the Calendar can be clicked on to view that date’s scheduled events. Note At this time, the OpenCATS calendar does not sync with outside calendars (Outlook, Google Calendar, etc.). However, that functionality CAN be added if you know a little coding, or a developer willing to do it. ### Reports Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) There are a few reporting options in OpenCATS. The Reports screen provides reports on `New Submissions` and `New Placements` for a specified time period. Unfortunately the other options on the screen weren’t built into the system and will (hopefully) be added in with time. There are additional reporting features within OpenCATS that will be explored later. ### Settings Screen[¶](broken://pages/1lHahaTJEqWTtfSSJGAN) There isn’t much to the settings screen. In the upper left corner: * `Administration` If you are the OpenCATS system administrator, this will take you to the administration screen. * `My Profile` View your OpenCATS user profile or change your password. * `Downloads` For now, this page serves no purpose. Disregard it completely. # How-to's # Hiding tabs ### Hiding some tabs all the time If you only want to use a subset of the tabs available, and want to hide the ones you don't use, then add the names of the tabs you want hidden to the printTabs method in the `TemplateUtility.php` class on line 602 like so `if (empty($tabText) || $tabText === 'Companies' || $tabText === 'Job Orders' || $tabText === 'Activities') { continue; }` Originally the line was: `if (empty($tabText)) { continue; }` and only add the modules you want to hide. ### Hiding tabs for users based on privilege turn off / on tabs for different permissions. This is a way for tabs not to appear (but users may still access them) At any time - you can get the permission of the logged in user with `$loggedInAccessLevel = $_SESSION['CATS']->getRealAccessLevel(); Real Access level returns the logged in user access:, Read Only - 100, Add / Edit - 200, Add / Edit / Delete (Default) - 300, Site Administrator - 400, Root - 500` Adding this code to printTabs in TemplateUtility.php in the f`oreach ($modules as $moduleName => $parameters)` loop will hide certain tabs if a user does not meet the appropriate permissions. Module names are: home, activity, joborders, candidates, companies, contacts, lists, calendar, reports, settings `$loggedInAccessLevel = $_SESSION['CATS']->getRealAccessLevel(); $minimumAccessLevel = array ("lists" => 400, "companies" => 400); if (array_key_exists($moduleName, $minimumAccessLevel)) { if ($loggedInAccessLevel < $minimumAccessLevel[$moduleName]) { continue; //Disabling module for the user by not showing it - if they do not have the minium access level } }` This is partially supported in the [ACL implementatio](/technical-configuration-options/access-control-lists)n - there is explained ACL.\ In some pages, there is a check for 'calculated''access level and required access level, if added into all pages (modules), then it shall be easy to hide menu an also to protect backend functionality. (hiding menu just don't show page to user but it is easy to construct get request to change values).
There was this change for some menu:\ \ and also implementation in Template utility Usage is documented at: # Password resets OpenCATS stores passwords with PHP `password_hash()` and verifies them with `password_verify()`. Older installations may still contain legacy hashes that OpenCATS migrates after successful login. ## Preferred reset method When possible, have an administrator reset the user's password from inside OpenCATS. This avoids direct database edits and ensures the new password is stored with the current hashing method. ## Emergency database reset If you are locked out and must reset a password directly in MariaDB, do **not** use MD5. Generate a modern PHP password hash first. On a server with PHP 7.4 available: ```bash php -r "echo password_hash('NewStrongPasswordHere', PASSWORD_DEFAULT), PHP_EOL;" ``` Copy the generated hash. Then update the relevant user record in the OpenCATS database using phpMyAdmin or the MariaDB CLI. The exact user table and user ID depend on your installation, so make a database backup before changing anything. Example CLI workflow: ```bash mysqldump -u opencats -p opencats > before-password-reset.sql mysql -u opencats -p opencats ``` Then inspect the users table, identify the correct account, and update only that account's password field with the generated hash. ## Security notes * Do not store or share the temporary password in tickets, chat, or email. * Require the user to change the password after login. * Keep the pre-reset database backup only as long as required and protect it because it contains personal data and password hashes. * If LDAP authentication is enabled, reset the password in the LDAP directory instead of the OpenCATS database. # Emails & reminders cronjob to send reminder emails for events / appointments OpenCATS can send email through PHP mail, Sendmail, or SMTP. Calendar reminders require both email configuration and a scheduled job that invokes `QueueCLI.php`. ## Configure email Email settings live in `config.php`. `MAIL_MAILER` selects the delivery method: * `0` - disabled * `1` - PHP built-in mail support * `2` - Sendmail * `3` - SMTP Common SMTP settings are: ```php define('MAIL_MAILER', 3); define('MAIL_SMTP_HOST', 'smtp.example.org'); define('MAIL_SMTP_PORT', 587); define('MAIL_SMTP_AUTH', true); define('MAIL_SMTP_USER', 'user@example.org'); define('MAIL_SMTP_PASS', 'strong-password'); define('MAIL_SMTP_SECURE', 'tls'); ``` For Sendmail, configure: ```php define('MAIL_MAILER', 2); define('MAIL_SENDMAIL_PATH', '/usr/sbin/sendmail'); ``` Do not commit real SMTP passwords to public repositories. ## Scheduled email reminders OpenCATS sends calendar event reminders when `QueueCLI.php` is run by cron or another scheduler. A typical Linux cron entry runs every minute: ```cron * * * * * /usr/bin/php /var/www/html/opencats/QueueCLI.php >/dev/null 2>&1 ``` Use the correct PHP binary and OpenCATS path for your server. A URL-based scheduler can also call the script, but local CLI execution is preferred when available: ```cron * * * * * curl -fsS http://example.org/QueueCLI.php >/dev/null 2>&1 ``` ## Reminder template The event reminder email template is configured in `config.php` as `$GLOBALS['eventReminderEmail']`. Back up `config.php` before changing the template. ## SMTP certificate problems If you see certificate verification errors from PHPMailer, fix the server trust store or SMTP configuration where possible. Disabling certificate verification weakens security and should only be used as a temporary troubleshooting step. PHPMailer troubleshooting documentation is available at: # Technical configuration options This explains usage of optional add- ons or configuring advanced features (such as the Access List fearure) # Technical overview of original OpenCATS Source code Note This was written for the original source code. It may not apply completely to the current OpenCATS version We have not used any outside frameworks. The OpenCATS framework is very light and conceptually simple to understand. This allows for modifications to be isolated, preventing, for example, a small change to a template from affecting library code, or a major change in database structure from requiring a change to every single page. Let’s have a look at the layout of the code OpenCATS is roughly divided into three parts: > * Modules > * Library Components > * Templates **Modules** A module is loosely related to the tabs you see in the GUI and consists of the user interface logic and one or more “templates” to render the HTML page. Some of the modules in OpenCATS are: > * Home > * Candidates > * Contacts > * Calendar, etc. Browse the modules directory to see the all the current modules in OpenCATS. Each module has its own separate directory. **Library Components** Library components are PHP objects which encapsulate lower-level functionality, such as interfacing with a database, parsing addresses, sending e-mail, etc. For each module, there is a roughly corresponding library component (but not all libraries directly correspond to a module). Examples of some library components are: > * Candidates > * Search > * Users > * VCard > * AddressParser Browse the lib/ directory to see the all different library components. **OpenCATS Page Request Flow** Every page request to OpenCATS goes through index.php, which acts as a “router” or delegator to the modules. > * A page request is sent to index.php > * index.php parses the URL and sends the request to the corresponding module (specified by m= in the URL) for further processing > * A module parses the “action” (specified by a= in the URL) and invokes the corresponding method within the module. > * The method processes the request, often using library components > * The function displays a template file, if necessary, and fills in the appropriate data and renders the HTML page Every OpenCATS page request goes more or less through the above 5 steps. **OpenCATS URLs** OpenCATS URLs are designed to be intuitive and easy to use for developers: E.g. [HTTP://OpenCATS.org/index.php?m=clients\&a=show\&clientID=239](http://opencats.org/index.php?m=clients\&a=show\&clientID=239) means: > * m = clients > * a = show > * clientID = 329 index.php sends the URL to the “clients” module. The clients module processes the action “show” for clientID 329. We want to display details of client 239. Here is the basic layout of a module: 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

/* mymodule/MyModuleUI.php: */
class MyModuleUI extends UserInterface
{
public function __construct()
{
parent::__construct();
$this->_moduleDirectory = ‘mymodule’;
}
public function handleRequest()
{
$action = $this->getAction();
switch ($action)
{
case ‘myAction’:
$this->myAction();
break;
…
}
}

public function myAction()
{
    …
}
**Templates** Modules, as mentioned above, contain the necessary code to render the HTML pages in OpenCATS. HTML is separated from the rest of the code via “templates”. A page is displayed by a template by assigning variables to it using assign() and then call it’s display() method. 
public function myAction()
{
…

$this->\_template->assign(‘myVariable’, $myValue);
$this->\_template->display(‘./modules/mymodule/MyTemplate.tpl’);
}
To display a variable inside a template, use: `_($this->myVariable); ?>` Interfacing with the database is only done at the library level. This limits the effects that a change in the database structure can have on the upper layers of the code. # Access control lists OpenCATS uses access-control checks around modules, actions, settings pages, imports, and AJAX behavior. Recent security work tightened authorization checks for module actions and AJAX endpoints, so custom code should not assume that a reachable URL is permission-free. ## Practical guidance * Give users the lowest access level that supports their role. * Review access after adding users, changing roles, or enabling optional workflows such as import. * Test custom modules or custom AJAX endpoints with low-privilege users. * Do not expose administrative actions through custom links unless the action is protected by OpenCATS permission checks. * Preserve CSRF token handling when customizing forms or JavaScript. ## Customization note If you add custom modules, actions, or settings pages, review the OpenCATS configuration and permission mappings in the application code so your new entry points are covered by the same authorization model as built-in pages. # CMS addons Front-ends for popular CMS are available in the github project; * [Wordpress](https://github.com/UltraSimplified/OpenCATS/tree/master/wordpress-plugin/wp-opencats) (for job listing display only) - an alternative is to use WP Job Manager and provide it with jobs via an XML feed. * [Drupal](https://github.com/Inuits/drupal-cats-plugin) (job listings, and applications direct into opencats) * [Joomla *DEPRECATED*](https://github.com/opencats/joomla-connector) but retained for example of complete Joomla integration # Dev Guide to migrate Legacy to Symfony ## Introduction The OpenCATS legacy code is stored in the root of the OpenCATS project, while the code of OpenCATS Symfony it's on the src/ folder. The legacy application was intended to be light and conceptually to understand. It separated the code in three main areas: * **Modules:** A module consists of the user interface logic and one or more “templates” to render the HTML page. Some of the modules in OpenCATS are Home, Candidates, Contacts, Calendar, etc. * **Library components:** Library components are PHP objects which encapsulate lower-level functionality, such as interfacing with a database, parsing addresses, sending e-mail, etc. For each module, there is a roughly corresponding library component but not all libraries directly correspond to a module. * **Templates:** HTML/CSS/js code with some light logic. ### OpenCATS Legacy Request Flow Most of OpenCATS request went through index.php and ajax.php files which acted as “router” or delegator to the modules. 1. A page request is sent to index.php or ajax.php file 2. index.php parses the URL and sends the request to the corresponding module (specified by m= in the URL) for further processing 3. A module parses the “action” (specified by a= in the URL) and invokes the corresponding method within the module. 4. The method processes the request, often using library components 5. The function displays a template file, if necessary, and fills in the appropriate data and renders the HTML page ### OpenCATS Legacy URLs OpenCATS Legacy URLs were designed to be intuitive and easy to use for developers. E.g. means: m = clients a = show clientID = 329 Translation: index.php sends the URL to the “clients” module. The clients module processes the action “show” for clientID 329. We want to display details of client 239. ## Version 0.9.4 This version aims to provide a bridge between Symfony and the legacy code so that the legacy code can be migrated little by little without requiring to rewrite the whole app at a single shot. In this version, there are no significant changes to the Legacy URLs and the way they are managed from a user point of view. From the request flow, there is an important change. In this version all requests go through a Symfony's front controller. ## What's changed? * A new docker image: this is required to load the symfony requirements + nginx configuration for the FrontController pattern * config.php was changed to get variables from environment, to allow configuring symfony app and legacy configuration from the docker image * Changes to all include paths: A new constant called LEGACY\_ROOT is prepended to all paths for compatibility * Removal of index.php and ajax.php entry points, they are now functions in LegacyController * All assets (css, images, javascripts) were relocated into the public assets folder * Base composer.json and composer.lock are removed (all migrated to composer.json and composer.lock in Symfony structure) * Behat and PHPUnit tests were standardized into a unified testing framework: Codeception and moved out of their legacy structure to Symfony's. ## Decisions In order to simplify deployment and installation, the default mode for running OpenCATS will be docker (on all platforms). ## Migration challenges ### Configuration Symfony configuration is managed by a set of yml files while the legacy application utilizes config.php. The first attempt was to migrate all config.php variables to the parameters.yml but it resulted to be a huge task. In order to solve this issue and also following the recommendations of , all values were replace with environment variables which are now injectable through docker-compose by replacing the .env file in the folder where the docker-compose file is executed. ### Functional test code 90% of the time is spent on updating test code. What's causing the issue? Mainly selenium and the PHP frameworks being used do not play well nor work reliable with: * code that's using blocking javascript alert and confirm functions * code that's using iframes ## Further performance improvements? 1. 2. # Developer Guide This guide helps contributors run OpenCATS locally and mirror the current CI test workflow. ## Prerequisites * Git * Docker with Docker Compose v2 * PHP 7.4 if running tests directly on the host * Composer 2 The project CI currently tests PHP 7.4. ## Clone and install dependencies ```bash git clone https://github.com/opencats/OpenCATS.git cd OpenCATS composer install ``` Do not use `--no-dev` for development, because PHPUnit, Behat, and related tools are development dependencies. ## Prepare the Docker test environment The local test workflow mirrors CI: ```bash cp test/config.php ./config.php touch ./INSTALL_BLOCK cd docker/ docker compose -f docker-compose-test.yml up -d --build ``` The test Docker setup uses two MariaDB databases: * `opencatsdb` on port `3306` for functional and Behat testing. * `integrationtestdb` on port `3307` for disposable PHPUnit integration tests. Install dependencies inside the PHP container if needed: ```bash docker compose -f docker-compose-test.yml exec -T --workdir /var/www/public php composer install --no-interaction --prefer-dist ``` ## Run tests From the `docker/` directory: ```bash docker compose -f docker-compose-test.yml exec php ./vendor/bin/phpunit --testsuite UnitTests docker compose -f docker-compose-test.yml exec php ./vendor/bin/phpunit --testsuite IntegrationTests docker compose -f docker-compose-test.yml exec php ./vendor/bin/behat -c ./test/behat.yml ``` CI also runs a PHP syntax check over `src/` and a Composer audit. The audit is currently non-blocking in CI so legacy dependency advisories can be reviewed without stopping all builds. ## Pull request title format OpenCATS pull request titles must use: ``` type: description ``` Allowed types are: * `chore` * `docs` * `feat` * `fix` * `refactor` * `security` * `test` Scopes are not currently allowed. For example, use `fix: correct login redirect`, not `fix(auth): correct login redirect`. ## Development notes * Do not commit local credentials or production `config.php` changes. * Use the Docker test stack when changing database, authorization, upload, import, or installer behavior. * Add or update tests when changing application behavior. * Shut down the test stack when finished: ```bash cd docker docker compose -f docker-compose-test.yml down ``` # Configuration Reference Most OpenCATS runtime configuration is stored in `config.php`. This page summarizes commonly changed settings. Always back up `config.php` before editing it. ## Database settings | Setting | Purpose | | --------------- | -------------------------------------------------------------------------------------------- | | `DATABASE_USER` | MariaDB user OpenCATS uses to connect. | | `DATABASE_PASS` | Password for `DATABASE_USER`. | | `DATABASE_HOST` | Database host name. Use `localhost` for local installs or the Docker service name in Docker. | | `DATABASE_NAME` | OpenCATS database name. | ## Authentication settings | Setting | Purpose | | ----------- | ------------------------------------------------------------------------ | | `AUTH_MODE` | Authentication mode. Supported values are `sql`, `ldap`, and `sql+ldap`. | Use `sql` for normal OpenCATS-managed users. Use LDAP modes only after configuring the PHP LDAP extension and the LDAP connection settings required by your environment. ## Resume/document parser settings | Setting | Purpose | | ----------------- | -------------------------------------------------------------------- | | `PARSING_ENABLED` | Enables external resume parsing service integration when configured. | | `ANTIWORD_PATH` | Path to `antiword` for Word document text extraction. | | `ANTIWORD_MAP` | Antiword character map. | | `PDFTOTEXT_PATH` | Path to `pdftotext`. | | `HTML2TEXT_PATH` | Path to `html2text`. | | `UNRTF_PATH` | Path to `unrtf`. | Parser utilities are optional for installation but useful for resume text extraction and search. ## Runtime paths | Setting | Purpose | | --------------- | -------------------------------------------------------- | | `CATS_TEMP_DIR` | Temporary directory writable by the web server. | | `MODULES_PATH` | Path to OpenCATS modules. Usually does not need editing. | ## Sphinx search settings | Setting | Purpose | | --------------- | ---------------------------------- | | `ENABLE_SPHINX` | Enables Sphinx search integration. | | `SPHINX_HOST` | Sphinx host. | | `SPHINX_PORT` | Sphinx port. | | `SPHINX_INDEX` | Sphinx index names. | Leave Sphinx disabled unless you have installed and configured Sphinx. ## Session and display settings | Setting | Purpose | | ----------------------- | ------------------------------------------------------------------------------------------- | | `CATS_SESSION_NAME` | Session cookie name. Change only if hosting multiple OpenCATS instances on the same domain. | | `ENABLE_SINGLE_SESSION` | Enforces one active session per user when enabled. | | `OFFSET_GMT` | Legacy GMT offset setting. | | `HTML_ENCODING` | HTML output encoding. | | `AJAX_ENCODING` | AJAX output encoding. | | `SQL_CHARACTER_SET` | SQL character set. | ## Email settings | Setting | Purpose | | -------------------- | ---------------------------------------------------------------- | | `MAIL_MAILER` | Mail method: `0` disabled, `1` PHP mail, `2` Sendmail, `3` SMTP. | | `MAIL_SENDMAIL_PATH` | Sendmail binary path when using Sendmail. | | `MAIL_SMTP_HOST` | SMTP server host. | | `MAIL_SMTP_PORT` | SMTP server port. | | `MAIL_SMTP_AUTH` | Whether SMTP authentication is required. | | `MAIL_SMTP_USER` | SMTP username. | | `MAIL_SMTP_PASS` | SMTP password. | | `MAIL_SMTP_SECURE` | SMTP security mode: empty string, `ssl`, or `tls`. | Calendar reminder email text is also configurable in `config.php`. ## Career portal and SSL settings | Setting | Purpose | | -------------------------------- | --------------------------------------------------------------- | | `SSL_ENABLED` | Enables SSL-aware behavior when your site is served over HTTPS. | | `CAREERS_CANDIDATEAPPLY_SUBJECT` | Candidate email subject after career portal application. | | `CAREERS_OWNERAPPLY_SUBJECT` | Owner email subject after career portal application. | | `CANDIDATE_STATUSCHANGE_SUBJECT` | Candidate email subject when status changes. | ## Demo and testing settings | Setting | Purpose | | -------------------- | -------------------------------------------------------------------------- | | `ENABLE_DEMO_MODE` | Enables demo mode behavior. Do not enable on normal production systems. | | `TESTER_*` constants | Automated testing defaults. Do not rely on these for production users. | | `DEMO_*` constants | Demo login defaults. Do not expose demo credentials on production systems. | # Security This page summarizes security practices for current OpenCATS installations. It complements the application repository `Security.MD` file and the upload-folder hardening guide. ## Reporting security issues Report security issues privately to the OpenCATS maintainers so the community has time to respond and upgrade. The application repository currently directs reports to `russh@opencats.org`. ## Password storage OpenCATS stores user passwords with PHP `password_hash()` and verifies them with `password_verify()` using the running PHP version's `PASSWORD_DEFAULT` algorithm. Legacy password hashes may be migrated when users successfully log in. Do not reset passwords by writing MD5 hashes into the database. If a database-level reset is unavoidable, generate a modern hash with PHP `password_hash()`. ## CSRF protection Current OpenCATS validates CSRF tokens for normal POST requests and logged-in AJAX POST requests. If you customize templates, forms, JavaScript, modules, or AJAX endpoints, preserve CSRF token output and submission. ## Upload security OpenCATS applies server-side upload extension validation. Current allowed upload extensions include: ``` bmp, csv, doc, docx, heic, jpeg, jpg, msg, odg, odt, pages, pdf, png, ppt, pptx, rtf, tiff, wpd, wps, xls, xlsx, xps ``` This validation is not a replacement for web server hardening. Configure Apache or Nginx so uploaded files cannot execute as scripts, and review [Vital Security: Restrict access to upload folders (.htaccess)](/technical-configuration-options/vital-security-restrict-access-to-upload-folders-.htaccess). ## Installer protection OpenCATS runs the installer when `INSTALL_BLOCK` is missing. Remove `INSTALL_BLOCK` only when intentionally installing or upgrading, and confirm it exists again afterward. ## Composer and dependencies If installing from source, run production installs with: ```bash composer install --no-dev ``` Review Composer audit output and update dependencies when security fixes are available. Development dependencies are not needed on production systems. ## Deployment checklist Before exposing OpenCATS to users: * Use HTTPS. * Use strong unique MariaDB credentials. * Do not expose phpMyAdmin publicly. * Ensure `attachments/`, `upload/`, and `temp/` are writable only as needed. * Prevent script execution from upload and attachment directories. * Keep `INSTALL_BLOCK` in place after installation. * Keep `config.php` out of public repositories and backups with weak access controls. * Back up MariaDB and `attachments/` regularly and test restores. # How\_to\_install\_Sphinx \###How to install Sphinx ##OpenCats Sphinx Integration - latest version contributed by @zoomiest from the OpenCATS forums. \##Download Sphinx **Login As User Root in Server via SSH** **Download Sphinx Version 2.1.3 Source Tar Ball** `root@c1:~#cd /root` `root@c1:~#wget [http://sphinxsearch.com/files/sphinx-2.1.3-release.tar.gz](http://sphinxsearch.com/files/sphinx-2.1.3-release.tar.gz)` \*\*Extract Contents of Tar Ball \*\* `root@c1:~#tar xvd sphinx-2.1.3-release.tar.gz` **Configure Sphinx Installer** `root@c1:~#cd sphinx-2.1.3-release` `root@c1:~#./configure --prefix=/opt` NOTE: The command above will set the Directory where Sphinx will be installed "/opt" **Compile Sphinx Source Code** `root@c1:~#make` **Install Sphinx in Server** `root@c1:~#make install` **Configure Environment Settings for Sphinx** `root@c1:~#echo "export PATH=/opt/bin:$PATH" >> ~/.bashrc` `root@c1:~#echo "export LD_LIBRARY_PATH=/opt/lib:$LD_LIBRARY_PATH" >> ~/.bashrc` `root@c1:~#source ~/.bashrc` NOTE: These commands ensures that Sphinx and its libraries are configured properly. \##2. Sphinx Configuration for Open Cats## \###1. Sphinx Configuration Explained### **1. source catsdb** { ``` type = mysql sql_host = localhost sql_user = cats sql_pass = yourpasshere sql_db = cats sql_port = 3306 # optional, default is 3306 sql_query_pre = \ REPLACE INTO sph_counter SELECT 1, MAX(attachment_id) from attachment sql_query = \ SELECT attachment_id, title, attachment.site_id AS site_id, UNIX_TIMESTAMP(attachment.date_created) AS date_added, text \ FROM attachment LEFT JOIN candidate ON data_item_id = candidate_id \ WHERE resume = 1 AND data_item_type IN(100,500) AND text IS NOT NULL AND text != '' \ AND attachment_id <= (SELECT max_doc_id FROM sph_counter WHERE counter_id = 1) sql_attr_uint = site_id sql_attr_timestamp = date_added sql_query_info = SELECT * FROM attachment WHERE attachment_id=$id ``` } ``` NOTE: In this section parameters that are of interest are the following: sql_host – is the hostname where the mysql database is hosted. ``` If the same server just set to localhost. ``` sql_user - username to access the database ``` sql\_pass – password to access database sql\_db – database name sql\_port – port used to access the database. If mysql should be default to 3306 **2. source delta : catsdb** { ``` sql_query_pre = sql_query = \ SELECT attachment_id, title, attachment.site_id AS site_id, UNIX_TIMESTAMP(attachment.date_created) AS date_added, text \ FROM attachment LEFT JOIN candidate ON data_item_id = candidate_id \ WHERE resume = 1 AND data_item_type IN(100,500) AND text IS NOT NULL AND text != '' \ AND attachment_id > (SELECT max_doc_id FROM sph_counter WHERE counter_id = 1) ``` } NOTE: This setting is the used for computing the delta/changes in the indexes when reindexing the database. This should not be changed. **3. index cats** { ``` source = catsdb path = /opt/var/data/catsindex docinfo = extern min_word_len = 1 charset_type = utf-8 ``` } NOTE: The parameter that might be of interest here is the path. This setting indicates where the index file will be generated by the indexer application. Normally you don’t need edit this parameter. Unless you run out of disk space and need to point that to another mountpoint or disk with space. **4. index catsdelta : cats** { ``` source = delta path = /opt/var/data/catsdelta ``` } NOTE: This is used as a reference file when reindexing the database. The parameter that might be of interest is the path parameter. Which indicated the location where the delta/difference of the index is stored. Normally you don’t need to edit this parameter unless you run of out disk space in /opt and need to point this to a different disk/mountpoint. **5. indexer** { ``` mem_limit = 32M ``` } NOTE: This Configuration is for the memory allowed to be used by the indexer application. It’s assumed in the current setup we only have 512 MB of RAM. This setting has been computed based on the available memory left in the server with MySQL and Apache running in the same Virtual Machine. If you increase your memory and want to optimize you might want to increase this setting higher so that the indexer can run faster. **6. searchd** { ``` listen = 9312 listen = 9306:mysql41 log = /opt/var/log/searchd.log query_log = /opt/var/log/query.log read_timeout = 5 max_children = 30 pid_file = /opt/var/log/searchd.pid max_matches = 1000 seamless_rotate = 1 preopen_indexes = 1 unlink_old = 1 workers = threads # for RT to work binlog_path = /opt/var/data ``` } NOTE: This are the searchd configuration. The parameters that are of interest are: listen – This is the port where searchd will be listening for opencast queries log – logfile where searchd enters results and errors encountered query\_log – logfile for search queries done binlog\_path – the directory where binary logs are written. The settings identified are normally not edited unless you run out of disk space in /opt and needs to point these parameters to a different disk or mountpoint. #### Installing Sphinx Configuration for Open Cats This document comes with a sphinx.conf file with the default configuration detailed in section A of this chapter. In order to install that configuration file to sphinx upload the file to the server and execute the following commands: `root@c1:~#cp sphinx.conf /opt/etc/sphinx.conf` \##Open Cats Configuration \*\*1. Open Cats Sphinx Configuration \*\* /\* CATS can optionally use Sphinx to speed up document searching. * Install Sphinx and set ENABLE\_SPHINX (below) to true to enable Sphinx. \*/ define('ENABLE\_SPHINX', true); define('SPHINX\_API', '/var/www/cats/lib/sphinx\_latest/sphinxapi.php'); define('SPHINX\_HOST', 'localhost'); define('SPHINX\_PORT', 9312); define('SPHINX\_INDEX', 'cats catsdelta'); NOTE: This are the parameters related to sphinx in the config.php file in /var/www/cats/. The SPHINX\_INDEX and SPHINX\_PORT should be the same as the settings in sphinx.conf. If you are using the sphinx.conf file that came with this document. These settings should work properly. The SPHINX\_API parameter is the location of the php library to allow opencast talk to our sphinx server. The actual sphinxapi.php file is included in the sphinx tarball that was extracted earlier. A section later will outline details on how to setup sphinxapi.php **2. Installing the Search.php file** This update to Searchd comes with a Search.php file that has been modified to work with open cats. The original Search.php file had some "die" commands that caused that module to exit prematurely. We have commented those lines in the version of the Search.php file that came with this document. To install upload the search.php file in the server. Login as root and execute the following commands: `root@c1:~#cd /root` `root@c1:~#cp Search.php /var/www/cats/lib/Search.php` NOTE: Copy the new Search.php to /cats/lib/. **3. Installing the Sphinxapi.php file** The sphinx tarball that was downloaded earlier contains the latest sphinxapi.php file compatible with the version of sphinx we configured. We need to install this in the open cats directory. To do that execute the following commands as user root: `root@c1:~#cd sphinx-2.1.3-release/api` `root@c1:~#mkdir /var/www/cats/lib/sphinx_latest` `root@c1:~#cp sphinxapi.php /var/www/cats/lib/sphinx_latest/.` NOTE: The following commands will create the directory /var/www/cats/lib/sphinx\_latest. And copy the latest sphinxapi.php that came with the sphinx installer in that directory. This will now be used by the open cats application. **4. Installing config.php file in opencats** This update comes with some changed sections for config.php, and are detailed separately. document came with a config.php file. This file has already been preconfigured with the settings outlined in section A of this chapter. To install upload config.php in the server. And as user root execute the following commands. `root@c1:~#cp config.php /var/www/cats/.` NOTE: This command will install config.php in the cats directory. #### 4. Indexer and Cronjob Indexer is the Sphinx application that creates and index file from the data in the mysql database. It is supposed to be run every 30 minutes. **1. Running the indexer** `root@c1:~#indexer --all` NOTE: This command normally takes 1 minute based on the current 4GB size of data. After this has been ran you can proceed with running the searchd application. **2. Setting the Indexer to run in the cronjob every 30 minutes** In order to set a cronjob that will run the indexer every 30 minutes execute the following commands: `root@c1:~#crontab -e` NOTE: This command will open a vim shell it normally has default values like this ``` # Edit this file to introduce tasks to be run by cron. # # Each task to run has to be defined through a single line # indicating with different fields when the task will be run # and what command to run for the task # # To define the time you can provide concrete values for # minute (m), hour (h), day of month (dom), month (mon), # and day of week (dow) or use '*' in these fields (for 'any'). # # Notice that tasks will be started based on the cron's system # daemon's notion of time and timezones. # # Output of the crontab jobs (including errors) is sent through # email to the user the crontab file belongs to (unless redirected). # # For example, you can run a backup of all your user accounts # at 5 a.m every week with: # 0 5 * * 1 tar -zcf /var/backups/home.tgz /home/ # # For more information see the manual pages of crontab(5) and cron(8) # # m h dom mon dow command ``` NOTE: To be able to edit go to the last line and press the i key. Then add the following entries: 30,59 \* \* \* \* /opt/bin/indexer --merge cats catsdelta --rotate > /tmp/indexer.log NOTE: Then press esc :wq then enter. This will save the line you added. To verify if the changes you did took effect run this command: `root@c1:~#crontab -l` NOTE: You should get a result similar to this `# Edit this file to introduce tasks to be run by cron.` `#` `# Each task to run has to be defined through a single line` `# indicating with different fields when the task will be run` `# and what command to run for the task` `#` `# To define the time you can provide concrete values for` `# minute (m), hour (h), day of month (dom), month (mon),` `# and day of week (dow) or use '*' in these fields (for 'any').#` `# Notice that tasks will be started based on the cron's system` `# daemon's notion of time and timezones.` `#` `# Output of the crontab jobs (including errors) is sent through` `# email to the user the crontab file belongs to (unless redirected).` `#` `# For example, you can run a backup of all your user accounts` `# at 5 a.m every week with:` `# 0 5 * * 1 tar -zcf /var/backups/home.tgz /home/` `#` `# For more information see the manual pages of crontab(5) and cron(8)` `#` `# m h dom mon dow command` 30,59 \* \* \* \* /opt/bin/indexer --merge cats catsdelta --rotate > /tmp/indexer.log Indexer now runs and indexes every 30th minute and 59th minute every hour. #### 5. Searchd Startup and Shutdown \*\*1. Searchd Startup \*\* To run searchd login as user root in the server and run the following commands: `root@c1:~# searchd -c /opt/etc/sphinx.conf` or searchd -c /etc/sphinxsearch/sphinx.conf NOTE: If the you already followed the instructions in the previous chapters and have already ran the indexer command in chapter 6, the searchd command stated here ought to work. To validate if it’s running you can run this command: `root@c1:~#ps –ef|grep searchd` NOTE: You should get something like this after running the ps –ef|grep searchd command. `root 21323 1 0 Nov26 ? 00:00:00 searchd -c /opt/etc/sphinx.conf` `root 21324 21323 0 Nov26 ? 00:01:40 searchd -c /opt/etc/sphinx.conf` `root 26474 26427 0 07:58 pts/0 00:00:00 grep --color=auto searchd` NOTE: 21323 is the process ID of the searchd application. Whenever you successfully run the searchd application Linux assigns a process ID to it. You can use this process ID in the next section when you want to kill the searchd application. **2. Searchd Shutdown** In case you need to shutdown searchd application you can run the ps –ef |grep searchd command in the previous section. Get the process id and run this command to kill the searchd application: `root@c1:~#kill -9 21323` NOTE: Where 21323 is the process id that was returned after you did the ps –ef |grep searchd command. This number/value changes every time you run searchd. # How\_to\_script\_database\_backups \###How to script database backups ### ####Backup all databases nightly w/ mysqldump (from linux.org) So, I want to take a shell script and be able to put it on any machine - and have it backup the databases on that machine using mysqldump.. and put them each separately into a backup directory.. here's what I came up with. Can you make it better? `#!/bin/bash` ``DB_BACKUP="/backups/mysql_backup/`date +%Y-%m-%d`"`` `DB_USER="root"` `DB_PASSWD="secretttt"` `` HN=`hostname | awk -F. '{print $1}'` `` `# Create the backup directory` `mkdir -p $DB_BACKUP` `# Remove backups older than 10 days` `find /backups/mysql_backup/ -maxdepth 1 -type d -mtime +10 -exec rm -rf {} ;` `# Option 1: Backup each database on the system using a root username and password` `for db in $(mysql --user=$DB_USER --password=$DB_PASSWD -e 'show databases' -s --skip-column-names|grep -vi information_schema);` `do mysqldump --user=$DB_USER --password=$DB_PASSWD --opt $db | gzip > "$DB_BACKUP/mysqldump-$HN-$db-$(date +%Y-%m-%d).gz";` `done` `# Option 2: If you aren't using a root password then comment out option 1 and use this` `# for db in $(mysql -e 'show databases' -s --skip-column-names|grep -vi information_schema);` `# do mysqldump --opt $db | gzip > "$DB_BACKUP/mysqldump-$HN-$db-$(date +%Y-%m-%d).gz";` `# done` `# Make it so only root can read the backup files` `chmod -R 600 $DB_BACKUP` If you use this, throw this text into something like /usr/local/bin/mysql\_backup.sh and since it has mysql's root password in it, make sure that you chmod 700 to it so no one else can read it. Then just call it from cron like: `30 3 * * * /usr/local/bin/mysql_backup.sh` BTW, a simpler way to grab all of them is to use the --all-databases flag in the mysqldump command.. but it doesn't make nice separate files for you.. # Docker - OpenCATS Installation Instructions The Docker files in the OpenCATS repository are intended for **development and testing**. Some experienced users deploy OpenCATS with Docker in production, but the repository Docker Compose configuration is not the recommended production configuration without hardening, secret management, persistent backup planning, and web/database security review. ## Current architecture The repository Docker Compose setup starts these services: * `opencats_web`: Nginx web container, exposed on ports `80` and `443`. * `opencats_php`: PHP-FPM container built from `docker/php/Dockerfile`. * `opencats_data`: shared source/data volume mounting the repository into `/var/www/public`. * `opencats_mariadb`: MariaDB database container. * `opencats_phpmyadmin`: phpMyAdmin container exposed on port `8080`. The PHP image is based on PHP 7.4 FPM Alpine and installs OpenCATS runtime tools and extensions, including document parser utilities, `mysqli`, `gd`, `soap`, `zip`, `ldap`, and `mcrypt`. ## Default development credentials The default Docker Compose database values are for local development only: * MariaDB root password: `root` * Database: `cats` * User: `dev` * Password: `dev` * phpMyAdmin: * OpenCATS web: Do not expose these defaults to the internet. ## Start the development environment From the OpenCATS application repository: ```bash cd docker docker compose up -d --build ``` If you are working from source and dependencies are missing, install Composer dependencies in the PHP container: ```bash docker compose exec --workdir /var/www/public php composer install ``` For production-style dependency installation, use `composer install --no-dev` instead. ## Running the installer in Docker Open and follow the installer. Use the database values from the Docker Compose configuration: * Database host: `opencatsdb` * Database name: `cats` * Database user: `dev` * Database password: `dev` If an existing `INSTALL_BLOCK` file prevents the installer from starting in a fresh development environment, remove it from the mounted repository. After installation, ensure `INSTALL_BLOCK` exists again. ## Test Docker environment The CI/test environment uses `docker/docker-compose-test.yml`, MariaDB 10.7 containers, Selenium, PHPUnit, and Behat. See [Developer Guide](/technical-configuration-options/developer-guide) for the full local test workflow. ## Production warning If you choose to adapt Docker for production, at minimum you should: * Replace all default passwords. * Use managed secrets rather than committing credentials. * Pin image versions. * Use durable database and attachment storage volumes. * Back up MariaDB and `attachments/` outside the containers. * Put TLS termination and HTTP security controls in front of OpenCATS. * Restrict phpMyAdmin or remove it entirely. * Review upload directory execution restrictions. This is an advanced deployment path and is not the primary recommended production installation in this documentation. # LDAP Authentication OpenCATS supports SQL authentication, LDAP authentication, and mixed SQL plus LDAP authentication through `AUTH_MODE` in `config.php`. ## Authentication modes ```php define('AUTH_MODE', 'sql'); ``` Supported values are: * `sql` - OpenCATS authenticates users against the OpenCATS database. * `ldap` - OpenCATS authenticates users through LDAP. * `sql+ldap` - OpenCATS can use both SQL and LDAP authentication paths. ## Requirements LDAP authentication requires the PHP LDAP extension. The repository Docker image installs the LDAP extension in its PHP container. ## Example settings Your exact LDAP settings depend on your directory server. A typical configuration uses values like these in `config.php`: ```php define('AUTH_MODE', 'ldap'); define('LDAP_HOST', 'ldap.example.org'); define('LDAP_PORT', '389'); define('LDAP_BASEDN', 'ou=users,dc=example,dc=org'); define('LDAP_UID', 'uid'); define('LDAP_CONNECT_DN', 'cn=readonly,dc=example,dc=org'); define('LDAP_PASSWORD', 'readonly-password'); ``` For Active Directory, `LDAP_UID` is often `sAMAccountName`, but this depends on your directory design. ## Troubleshooting If LDAP login fails: * Confirm the PHP LDAP extension is installed and enabled. * Confirm the OpenCATS server can reach the LDAP host and port. * Confirm bind DN and password are valid. * Confirm `LDAP_BASEDN` points to the subtree containing users. * Confirm `LDAP_UID` matches the attribute users enter at login. * Check whether your directory requires LDAPS, StartTLS, or firewall changes. * Test with `sql` mode first to separate database/application issues from LDAP issues. Do not publish LDAP bind credentials in public repositories or screenshots. # Multi lingual\_version \###Multi-lingual version There are some language packs available for the (short-lived) successor to OpenCATS (OSATS). This is now considered abandonware. Languages supported are/were; * German * English * Spanish # OpenCATS Youtube channel We have a with some tutorial videos. Please le tus knos if ther eare configuration / features you want added. [OpenCATS YouTube Channel](https://www.youtube.com/channel/UChJ_YF1w74o8iWFAYa9w0xQ) # Prerequisites This page lists the current baseline for OpenCATS 0.10.0. ## Tested CI/CD baseline OpenCATS is built and tested in CI on Linux with: * PHP 7.4 * Composer 2 * MariaDB 10.7 for Docker-backed integration and Behat tests Other PHP, database, operating system, or web server combinations may work, but this is the baseline used by project CI/CD. ## Required runtime components * A Linux/Unix web server environment such as Apache or Nginx with PHP-FPM. * PHP 7.4. * MariaDB. MariaDB 10.7 is used by current Docker test services. * Composer if you install from source rather than from a prepared release archive. * Writable OpenCATS directories for uploads, attachments, temporary files, and restore operations when used. ## PHP extensions The repository Docker image installs the PHP extensions OpenCATS expects in that environment: * `mysqli` * `gd` * `soap` * `zip` * `ldap` * `mcrypt` On distribution packages, extension package names vary. Ubuntu-style package names are usually similar to `php7.4-mysqli`, `php7.4-gd`, `php7.4-soap`, `php7.4-zip`, and `php7.4-ldap`. ## Composer dependencies OpenCATS runtime Composer dependencies include CKEditor, Sphinx search API support, PHPMailer, and FPDF. For production source installs, run: ```bash composer install --no-dev ``` For development and testing, omit `--no-dev` so PHPUnit, Behat, and related test packages are installed. ## Optional document parsing utilities OpenCATS can extract text from uploaded documents when parser utilities are installed and configured in `config.php`: * `antiword` * `pdftotext` / poppler utilities * `html2text` * `unrtf` These utilities are useful for resume search and parsing, but they are not required to launch the installer. ## Optional Sphinx search Sphinx is optional. Enable it only after Sphinx is installed and the `ENABLE_SPHINX`, `SPHINX_HOST`, `SPHINX_PORT`, and `SPHINX_INDEX` settings are configured in `config.php`. ## Writable directories The web server user must be able to write to the directories OpenCATS uses for runtime files. Common directories include: * `attachments/` * `upload/` * `temp/` * `restore/` when restoring from a GUI backup file Avoid world-writable permissions such as `777` unless you fully understand the risk and have no safer option in your hosting environment. # Roadmap This page is intentionally conservative. OpenCATS roadmap commitments should come from current maintainer planning and GitHub issues rather than old documentation tables. ## Current documented baseline The documentation currently targets OpenCATS 0.10.0, PHP 7.4, and the Linux/MariaDB CI environment used by the application repository. ## Recently completed modernization themes Recent application work includes: * PHP 7.4 support and CI coverage. * Composer-managed runtime and development dependencies. * PHPUnit and Behat test infrastructure. * Security hardening for CSRF, AJAX, authorization, uploads, and password storage. * Docker-based development and test workflows. * Activity, job order, contact, and schema refinements. ## Where to track future work For current priorities, use the OpenCATS GitHub issue tracker and pull requests: * [OpenCATS issues](https://github.com/opencats/OpenCATS/issues) * [OpenCATS pull requests](https://github.com/opencats/OpenCATS/pulls) If maintainers publish a new formal roadmap, this page should be updated to reflect that source of truth. # Vital Security: Restrict access to upload folders (.htaccess) OpenCATS performs server-side upload extension validation, but you should still configure your web server so uploaded files cannot execute as scripts. Treat web server restrictions as defense in depth. ## Upload directories Review restrictions for these directories: * `opencats/upload` * `opencats/attachments` The web server user must be able to write files OpenCATS needs, but uploaded content should not be executable. Avoid permissions such as `777` unless your hosting environment leaves no safer option. Example ownership and permissions on many Linux systems: ```bash sudo chown -R www-data:www-data upload attachments sudo chmod 770 upload attachments ``` ## Current allowed upload extensions Current OpenCATS upload validation allows these extensions: ``` bmp, csv, doc, docx, heic, jpeg, jpg, msg, odg, odt, pages, pdf, png, ppt, pptx, rtf, tiff, wpd, wps, xls, xlsx, xps ``` Your web server allow-list should be no broader than the file types you actually need. ## Apache 2.4 `.htaccess` example Place an `.htaccess` file in each upload directory if your Apache configuration allows overrides: ```apache IndexIgnore * Options -ExecCGI -Indexes AddHandler cgi-script .php .php2 .php3 .php4 .php5 .php6 .php7 .php8 .php9 .pl .py .js .jsp .asp .sh .cgi Require all granted ``` For stronger control, put equivalent rules in the main Apache virtual host or server configuration and disable `.htaccess` overrides. ## Apache server configuration example ```apache IndexIgnore * Options -ExecCGI -Indexes AddHandler cgi-script .php .php2 .php3 .php4 .php5 .php6 .php7 .php8 .php9 .pl .py .js .jsp .asp .sh .cgi Require all granted IndexIgnore * Options -ExecCGI -Indexes AddHandler cgi-script .php .php2 .php3 .php4 .php5 .php6 .php7 .php8 .php9 .pl .py .js .jsp .asp .sh .cgi Require all granted ``` Adjust paths for your installation. ## Test after changes After changing upload restrictions: * Upload a valid document and confirm OpenCATS can attach and download it. * Try uploading an invalid script file and confirm OpenCATS rejects it. * Try browsing directly to uploaded content and confirm scripts cannot execute. * Review web server logs for unexpected denials or executable handling. ## Reference material * * * * # Backup, Restore, and Upgrade This page describes the recommended backup, restore, and upgrade approach for OpenCATS. ## Recommendation Use **CLI database backups** and filesystem backups as your primary backup method. OpenCATS includes GUI backup features, but command-line database and attachment backups are easier to automate, inspect, test, and restore consistently. ## What to back up A complete OpenCATS backup must include: * The MariaDB database. * The `attachments/` directory. * The `upload/` directory if your workflow uses pending bulk imports. * `config.php` and any local web server configuration. * Any custom templates, patches, or integrations you maintain outside the database. ## CLI database backup Replace database name, user, and output path with your own values: ```bash mysqldump --single-transaction --routines --triggers -u opencats -p opencats > opencats-$(date +%F).sql ``` Store backups somewhere other than the OpenCATS web directory. ## Attachments backup From the OpenCATS installation directory: ```bash tar -czf opencats-attachments-$(date +%F).tar.gz attachments/ ``` If your installation uses `upload/` for pending import files, back it up too: ```bash tar -czf opencats-upload-$(date +%F).tar.gz upload/ ``` ## Test your backups A backup is not complete until you have restored it in a separate test environment. Test restores should verify: * users can log in; * candidates, companies, contacts, and job orders load; * attachments download correctly; * search and parsing features work if enabled; * email settings are not accidentally sending production email from a test system. ## Restore from CLI backup 1. Install OpenCATS files for the target version. 2. Create a fresh MariaDB database and user. 3. Import the SQL backup: ```bash mysql -u opencats -p opencats < opencats-backup.sql ``` 4. Restore `attachments/`: ```bash tar -xzf opencats-attachments-backup.tar.gz -C /path/to/opencats/ ``` 5. Restore or recreate `config.php` with the correct database settings. 6. Ensure writable directory ownership and permissions are correct. 7. Run the installer/upgrade path only when intentionally upgrading an existing database. 8. Confirm `INSTALL_BLOCK` exists after installation or upgrade. ## Upgrade checklist Before upgrading production: * Read release notes for the target OpenCATS release. * Confirm your server meets the current PHP and MariaDB baseline. * Back up the database with `mysqldump`. * Back up `attachments/`, `upload/` if used, and `config.php`. * Test the upgrade on a copy of production data. * Schedule a maintenance window. * Have a rollback plan using the backups you just tested. ## Upgrading OpenCATS files A typical upgrade flow is: 1. Put the site into maintenance or stop web traffic. 2. Back up database and files. 3. Deploy the new OpenCATS release files. 4. Restore or merge the existing `config.php` settings carefully. 5. Ensure Composer dependencies are installed if using source: ```bash composer install --no-dev ``` 6. Remove `INSTALL_BLOCK` only when you are ready to run the installer/upgrade workflow. 7. Visit the site in a browser and choose the existing installation/upgrade path if presented. 8. After upgrade, confirm `INSTALL_BLOCK` exists. 9. Test login, records, attachments, reports, search, email, and scheduled reminders. ## GUI backup and restore OpenCATS has GUI backup screens under Settings and Administration. These may be useful for small installations or quick exports, but CLI backups are the recommended operational backup method. If you use GUI restore, the backup file must be named `catsbackup.bak` and placed in a writable `restore/` directory under the OpenCATS installation before running the installer restore path. ## Security notes * Do not keep backup files inside the public web root longer than necessary. * Protect SQL backups because they contain personal data and password hashes. * Protect attachment backups because they may contain resumes and other sensitive documents. * Do not expose restored test systems publicly with production data.