HOAM Documentation


Table of Contents

  1. Welcome
    1. Features
    2. License
  2. Pre-Installation Requirements
    1. Information Required
    2. Apache
      1. Linux
      2. Windows
    3. MySQL
      1. Linux
      2. Windows
      3. UTF-8
    4. PHP
      1. Linux
      2. Windows
      3. Uploads
  3. Installation Tasks
    1. Installation Tasks
      1. Webserver Configuration
      2. Installing HOAM
        1. Maintenance Script
    2. Installation Troubleshooting
  4. Initial Configuration
    1. Default Password
    2. Initial Customization Steps
    3. System Configuration
      1. Attachment Configuration
      2. Budget Configuration
      3. Email Configuration
      4. File Configuration
      5. Group Configuration
      6. Homeowner Configuration
      7. Letter Configuration
      8. Logging Configuration
      9. Messageboard Configuration
      10. Lot Configuration
        1. Common Areas
        2. Miscellaneous Property
      11. News Configuration
      12. Organization Configuration
      13. Sections Configuration
      14. Users Configuration
      15. Violation Configuration
      16. Website Configuration
        1. Record Installation
      17. Wiki Configuration
      18. Work Request Configuration
  5. Daily Use
    1. Advertisements
    2. Articles
      1. Wiki Markup
    3. Attachments
    4. Financial
      1. Accounts
      2. Budgets
      3. Categories
      4. Vendors
    5. Form Letters
    6. Homeowners
    7. Lots
      1. Miscellaneous Property
    8. Users
    9. Violations
      1. Violation Categories
      2. Violation Severity
    10. Voting
  6. Advanced Configuration
    1. Attachments
    2. Groups
    3. Messageboard
    4. Plugins
    5. Sections
    6. Users
    7. Wiki / Articles
  7. Development
    1. Bug Tracker and Source Repository
    2. Languages and Country Specific Settings
    3. Plugins
    4. 3rd Party Code
    5. About The Author
  8. Bug and Security Reports
    1. Bug Tracker and Source Repository
  9. Optional Server Configuration Changes
  10. Troubleshooting
  11. Footnotes

Welcome

Welcome to HOAM! HOAM is designed primarily for single-family and condominium property management, although it also can be used for managing rental* and commercial properties or even as a general web "portal" if you choose to use it that way.

HOAM is intended to give owners living in a neighborhood or condominium building the tools they need to easily administer and operate an property owners association without the need for an outside management company, given a minimum amount of time. Indeed, HOAM is designed specifically to streamline and automate many of the operational tasks of running an HOA.

That said, it's just as easy for a professional management company to set up and use HOAM*, making their operations more cost-effective and efficient.

While HOAM is essentially ready to go out of the box, there is a need for investigation and data-entry on your part before it becomes truly usable. Specifically:

Features

It's free (both monetarily and philosophically). But why else would you want to use HOAM instead of another property management system?

PROS:
Active development
There are usually tweaks and updates to some part of the code an average of 1-2 times a week. Stable versions of HOAM are released at least once per year.
Easy export, migration of information
If (for whatever reason) you need to export data into another application (such as an Excel® spreadsheet with a list of all homeowners), that functionality is built into the system. If you want to create backups of your information, or migrate from one installation to another, documentation and scripts are provided to automate much of that process for you.
Security Focused
All user input is filtered. Database calls are done using prepared statements to reduce the occurrence of SQL attacks. HOAM does not use / need PHP's register_globals enabled, or safe_mode to be disabled.
Multilingual
Multiple languages are supported throughout. Additional languages and customizations may be easily added by editing the appropriate file. See Development for more information.
Additionally, where possible, we have tried to use unicode characters (e.g. ✓ or ☠) instead of graphic images in order to reduce the amount of traffic that must be sent.
IPv6 Support
HOAM supports IPv6. That is to say, HOAM really doesn't have much to do with network-level addressing. The one place where HOAM does care about addressing is in the system logging, which supports IPv6 addresses.
Flexibility
HOAM has been written with flexibility in mind, most especially because of it's constant ongoing development.
If you really want to do major modifications, those are easy to do as well. Most limitations are artificial, such as the length of articles being imposed by the limits of the database; HOAM checks to see what is the maximum capacity allowed by the table, and that becomes the maximum size of the article. Similarly, article IDs are currently 32-character MD5 strings, which allows for a maximum of a few trillion unique articles. If you chose to restrict or enhance the IDs (or even change from MD5 to SHA-1 or even simple integers), there is no programmed limit in HOAM preventing that.
Standards compliant
Unlike many other CMS systems out there, it's a pet peeve of ours to keep content separate from presentation and functionality wherever possible.
We've also tried to make (at least the base site) as accessible and semantically correct as possible.
We are targeting modern browser functionality, meaning using features such as CSS2, DOM, XMLHTTPRequest, etc.
The code is easy to read
This won't apply to most people, but we've done our best to comment the code (the original computer software) to make it easy to understand.
Not only does this mean that any aspiring contributors can get up to speed quicker, but our own failing memories get a refresher when looking at a piece of old code.
CONS:
Active development
Because there is such active development, and because HOAM has evolved over time, there are a few old design decisions and old cruft laying about. Additionally, it means that often there are large rewrites of major features, meaning that portions of HOAM are relatively "young".
MySQL is the only supported database
At some point we may look at supporting other databases. Early on there was a database abstraction layer, but performance problems meant eliminating it.
Multilingual
While HOAM does support multiple languages for display, some of the specifics are still relatively US-centric (e.g., date formats, telephone number formats, ZIP code formats).
Additionally, the only translation available at this time is English.
Standards Compliant
Since we focus on using the documented standards, rather than coddling each and every browser platform and bug out there, there will inevitably be pages that don't display (or even function) correctly on all browsers, specifically Internet Explorer < v8.0.
Since we are using modern standards such as CSS2, DOM, XMLHTTPRequest, etc., older browsers will likely have problems (usually those more than 3-4 years old). Versions of Internet Explorer less than 8.0 are known to have problems.
HOAM uses Javascript extensively
Javascript must be enabled in order to use almost all of the administrative functions, and the whole site in general, while not requiring Javascript, benefits enormously.
HOAM is very tightly interwoven with the backend database.
If the database dies, your entire site is kaput. As such, the system automatically performs checks of the database integrity as part of the maintenance routine.
Flexibility
HOAM has been written with flexibility in mind, most especially because of it's constant ongoing development. However, that flexibility imposes a small increase in processing overhead. While it's not noticeable on modern servers, you may see performance problems on older (< 1GHz) or busy systems.
If you're still not convinced, there are many other commercial management programs available on the market. However, none that we know of are free (either monetarily or philosophically) and none are designed for Board Members and Officers to manage an association without an outside professional management company.

License

HOAM is copyright © 2002-2015 ARP Realty, Inc.

HOAM is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

HOAM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with HOAM; if not, see http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301

Questions specific to HOAM should be directed to ARP Realty Services. Please see the HOAM web site at http://hoam.arprs.com/.

Some portions of HOAM incorporate ideas and/or code from other sources, and those portions are explicitly mentioned and attributed in the relevant section of HOAM source code. Questions about that code should be directed to the original authors.

Reading Convention

The following formats are in use:

> sudo service apache restart
Indicates how something will look on your screen.
This is a test. or This is a test
Indicates a command or text you should enter.
/a/directory/path/
Indicates a variable name or setting you need to change.
Important information.
Indicates important information for you to be aware of.

Additionally, most of the documentation is written from a Linux/UNIX viewpoint; if you are installing under Windows you will need to remember to change from forward slashes (/) to back-slashes (\) and adding drive letters where necessary (C:\www) when reading instructions.

Pre-Installation Requirements

HOAM has been deployed successfully and used long-term with several different versions of Apache, MySQL, and PHP. Most of the testing (and all of our deployments) have been in the Linux environment. While it will work (and has been tested with several versions of Windows from Server 2003 through Server 2019), it is strongly recommended to run HOAM under Linux. The versions of each application that have been tested are:

As of April 2020, the minimum requirements are:

Server Sizing

As for server size, you can easily run HOAM under Linux with 1 CPU, 1GiB RAM, and 40GiB of drive space. For Windows, whatever minimum specs are necessary for the version of Windows Server (eg, 2GiB RAM and 40GiB storage) are sufficient — however, it's recommended that Windows servers have at least 4GiB RAM and 80GiB storage.

Start-up Checks

HOAM performs several checks when it starts to ensure that the minimum requirements are met for the particular version being used. When upgrading HOAM to a new version, it will check whether the minimum requirements are met during the upgrade.

Please note, most recent installations and testing of HOAM have been done on dedicated cloud-based servers; while nothing should prevent you from running HOAM in a shared ISP account (such as under cPanel), we have not performed recent testing to validate it for the last several years.

Information Required

You'll need to complete several other tasks before starting the installation, as this information will be required during configuration.

  1. Find a server to host your website. Selection of ISPs and service comparisons are outside the scope of this document*.
  2. Obtain a domain name for the Association's website and point it at the chosen webhost.
  3. Obtain email addresses for relevant parties:
  4. If desired, create and configure accounts for use with optional components (such as PayPal for online payments, Google Analytics for website traffic information, and others).
  5. It is strongly recommended that you have both a good understanding of your Association's governing documents, as well as a copy handy for reference as you go through the configuration. You will need to know details such as the amount of time allowed for assessment payments, how interest rates are charged, the types of deed restrictions your association monitors, and other information.
    Depending on the age of your governing documents, as well as the content within, there may be applicable laws (such as the Fair Debt Collection Practices Act) that override certain portions. For the best, most accurate information, consult an attorney.

Apache

Linux

Ubuntu

On an Ubuntu 8.10 and newer system, enter sudo apt-get install apache2 to install the Apache web server software:

> sudo apt-get install apache2
Redhat / Fedora

On a Fedora 29 or newer system, enter the below. Several additional commands are necessary which allow access through the system firewall, and also allow Apache write access (needed for attachments, system backups, upgrades, etc.)

> sudo dnf -y install httpd
> sudo systemctl start httpd
> sudo systemctl enable httpd
> sudo firewall-cmd --add-service={http,https} --permanent
> sudo firewall-cmd --reload
> sudo setenforce 0
> sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/g' /etc/selinux/config
Additional Apache Modules

On UNIX systems, a number of Apache features are disabled in a default installation. HOAM requires the headers and rewrite modules to be enabled. On Ubuntu 8.10 and newer, you can do so at the command line by running sudo a2enmod module

> sudo a2enmod headers
> sudo a2enmod rewrite

You will need to ensure that you can either modify the configuration entry for the website to allow rewrites, or that Apache will respect rewrite changes in .htaccess.

Windows

You will want to download the Apache binary build from one of the mirrors. Once downloaded, follow the instructions to install, which typically entails extracting the archive, updating the httpd.conf file, and installing Apache as a service.

You will need to uncomment the various modules from httpd.conf:

LoadModule headers_module modules/mod_headers.so
LoadModule rewrite_module modules/mod_rewrite.so

Apache also needs to be configured to load the PHP module; you'll need to do this once PHP is installed.

LoadModule php5_module "C:\Program Files\PHP-5.6.5\php5apache2_4.dll"
AddHandler application/x-httpd-php .php

# configure the path to php.ini
PHPIniDir "C:\Program Files\PHP-5.6.5"

<FilesMatch \.php$>
      SetHandler application/x-httpd-php
</FilesMatch>

MySQL

While MySQL is required, we're not going to cover specific details about the installation (such as setting the root password, installation path, etc.) For more detailed instructions on installing and using MySQL, please review the documentation available for that product.

Linux

Ubuntu

On an Ubuntu 8.10 and newer system, enter sudo apt-get install mysql-server to install the MySQL database software:

> sudo apt-get install mysql-server
RedHat / Fedora
> sudo dnf -y install mariadb-server
> sudo systemctl start mariadb
> sudo systemctl enable mariadb
> sudo firewall-cmd --add-service=mysql --permanent
> sudo firewall-cmd --reload

A MySQL client on UNIX can connect to the mysqld server in two different ways: by using a UNIX socket file to connect through a file in the filesystem (the default socket file location is dependent on your distribution), or by using TCP/IP, which connects through a port number. A UNIX socket file connection is faster than TCP/IP, but can be used only when connecting to a server on the same physical computer. A UNIX socket file is used if you don't specify a hostname or if you specify the special hostname localhost.

Configure root Password

On recent versions of Ubuntu and RedHat/Fedora, the MySQL root password is blank by default. In order to install HOAM using the automated install script, you will need to configure a password for the root account. You can do this by running:

> sudo mysql_secure_installation

Windows

You will want to download the MySQL binary build from Oracle. Once downloaded, follow the instructions to install, which typically entails extracting the archive, creating/updating the my.ini file, and installing MySQL as a service. As mentioned in the installation instructions, you will likely want to update your environment variables to place the MySQL bin directory in your path.

UTF-8

HOAM uses and is capable of handling Unicode throughout; everything is done in UTF-8. The default installation of HOAM imports a database already in UTF-8 format, and all of the PHP code forces UTF-8 to be used. However, you may want to also modify the default MySQL configuration to use UTF-8 by default. In my.cnf, set:

[mysqld]
loose-character-set-server=utf8
loose-collation-server=utf8_unicode_ci

Versions of MySQL earlier than 5.5.3 also usually needed a config option default-collation. If you're using an earlier version, add this to the configuration, but it will cause the MySQL service to fail to start if used in 5.5.3 or later.

[mysqld]
default-collation=utf8_unicode_ci

If for some reason your installation of HOAM is not using UTF-8, you can update the database with the following commands:

ALTER DATABASE hoam_xyz
	CHARACTER SET utf8
	DEFAULT CHARACTER SET utf8
	COLLATE utf8_general_ci
	DEFAULT COLLATE utf8_general_ci
	;
And for each table, do:
ALTER TABLE table_name
	DEFAULT CHARACTER SET utf8
	COLLATE utf8_general_ci
	;

PHP

Linux

Ubuntu

On Ubuntu 8.04 and newer, enter the following commands to install PHP:

> sudo apt-get install php php-cli
On older versions of Ubuntu (16.04 and earlier, you may also need to install libapache2-mod-php if the browser just shows a bunch of text but not the HOAM page.
Most Linux distributions we've tested automatically integrate PHP with Apache when installed, but a few require additional packages (such as Ubuntu 16.04 requiring libapache2-mod-php, or other distributions requiring the specific PHP version (eg., php7 and php7-cli instead of just php and php-cli).
RedHat / Fedora
> sudo dnf -y install php php-cli

On most Linux systems, PHP by default does not have either the MySQL or GD libraries installed / compiled by default. It is necessary to add those two libraries before HOAM will function properly. When starting, HOAM does a requirements check and will complain if the MySQL, GD, or other required libraries are not available.

Ubuntu
> sudo apt-get install php-curl php-gd php-mysql php-zip
RedHat / Fedora
> sudo dnf -y install php-mbstring php-mcrypt php-mysqlnd php-curl php-gd php-xml php-zip
PHP Modules
Several other extensions, such as mbstring and xml are also required, but may or may not be included in by default depending on the distribution (and it varies from version to version as well). HOAM will check for required extensions at startup, and inform you of any additional extensions your particular distribution is lacking. If you discover you need these additional libraries after trying to start HOAM, you'll need to install them and then restart Apache.

Windows

You will want to download the PHP binary build, the debug pack is not required by HOAM. Once downloaded, follow the instructions to install, which typically entails extracting the archive, creating/updating the php.ini file, and configuring it as a module in Apache.

Make sure you download the Thread Safe version of PHP, and also that both the VCC versions of Apache and PHP match (eg, both are VC6, VC9, VC11, etc.) and that both Apache and PHP are either 32- or 64-bit otherwise you will have difficulty with the installation and the vendor instructions may not work.

If you did not already add the PHP module to the Apache configuration (described earlier) do so now.

You will need to uncomment the various modules from php.ini:

extension=php_com_dotnet.dll
extension=php_curl.dll
extension=php_exif.dll
extension=php_gd2.dll
extension=php_mbstring.dll
extension=php_mysqli.dll
extension=php_zip.dll

Make sure you also uncomment and update your extension_dir path to where you installed PHP as shown in the example below:

extension_dir = "C:\Program Files\PHP-5.6.5\ext"

If not already configured, you will likely need to update the timezone line in php.ini as well. You should have a block like this in your php.ini file:

[Date]
; Defines the default timezone used by the date functions
; http://php.net/date.timezone
date.timezone = America/Chicago

If not, add it (replacing the timezone with yours); a list of supported timezones is available in the PHP manual. After configuring, make sure to restart httpd (service httpd restart).

Additionally, although this should not normally be necessary, you may want to increase the execution time of PHP scripts from the default of 30 seconds. This has only been observed to be necessary when the maintenance script is manually started from the website administration page. By default the maintenance script runs as a scheduled task using the PHP CLI (which has no timeout), and this change would not be required.

max_execution_time = 90

Uploads

If you are planning to allow file uploads (attachments) larger than the default size (the default maximum is 2MB), you must edit several settings in the php.ini configuration file. Based on your Linux distribution this can be found in various places, like /etc/php.ini, /etc/php5/apache2/php.ini, etc.

Each of these settings should be set to the maximum desired size. For example, set upload_max_filesize = 32M.

At this time, it is not necessary to modify the PHP CLI configuration file, only the one running via Apache; all cli settings can be left at the default.

Installation Tasks

At this time, there is only a limited automated installation routine for HOAM; most of the installation will need to be performed manually by someone with at least a passing knowledge of server administration.

Webserver Configuration

  1. Extract HOAM archive.
    1. You'll need an appropriate location for the installation. Often this is in the /var/www/ directory, so you would run (for instance):
      > sudo mkdir /var/www/association.domain.name
      where association.domain.name is the FQDN* of your website. For instance, you may have something like www.harvesthoa.com or www.middlebrookcondos.org. This really is optional, however, you can set the directory name to whatever you choose; remember it though, you'll need this name below when telling the web server which directory to use and when scheduling the maintenance script to run.
    2. Extract the HOAM archive you downloaded in this directory.
      > sudo cp /path_to_download/hoam-20150301.tgz .
      $ sudo tar -xvf hoam-20150301.tgz
  2. You will need to configure the web server (Apache) so that it knows where you installed HOAM, and how files should be loaded. Generally, with Apache, there are two basic configurations: you have full control over the system where you are installing HOAM (such as a dedicated server or cloud hosted system), or when you typically don't have control over the webserver configuration (such as in a shared hosting environment).
    1. Configure the entire site and all options directly in the server configuration. You will want to modify the site configuration similar to the below; the Apache site configuration file is usually located at /etc/apache2/sites-available/000-default.conf (newer Ubuntu releases) /etc/apache2/sites-available/default (older Ubuntu releases), /etc/httpd/conf/httpd.conf (RedHat/Fedora), or C:\Apache24\conf\httpd.conf (Windows).
      <VirtualHost *:80>
              DocumentRoot /var/www/association.domain.name/
              ServerName association.domain.name
              <Directory /var/www/association.domain.name/>
                      DirectoryIndex index.php
                      Options Indexes
                      <IfVersion < 2.4>
                              Allow from all
                      </IfVersion>
                      <IfVersion >= 2.4>
                              Require all granted
                      </IfVersion>
              </Directory>
              RewriteEngine on
              RewriteRule /$ /index.php
              <IfModule mod_expires.c>
                      ExpiresActive on
                      ExpiresDefault "access plus 24 hours"
                      ExpiresByType application/pdf "access plus 1 week"
                      ExpiresByType application/x-javascript "access plus 2 days"
                      ExpiresByType application/x-shockwave-flash "access plus 1 month"
                      ExpiresByType image/gif "access plus 1 month"
                      ExpiresByType image/png "access plus 1 month"
                      ExpiresByType image/jpeg "access plus 1 month"
                      ExpiresByType image/x-icon "access plus 1 month"
                      ExpiresByType text/css "access plus 2 weeks"
                      ExpiresByType text/html "now"
                      ExpiresByType text/xml "now"
                      ExpiresByType text/plain "access plus 2 weeks"
                      ExpiresByType video/x-flv "access plus 1 month"
                      ExpiresByType video/quicktime "access plus 1 month"
              </IfModule>
              <IfModule mod_headers.c>
                      <FilesMatch "\.(js|css|xml|gz)$">
                              Header set Vary: Accept-Encoding
                      </FilesMatch>
      		Header always append X-Frame-Options SAMEORIGIN
              </IfModule>
              ErrorLog /var/log/apache2/error_association.domain.name.log
              # For Redhat/Fedora, make sure to swap apache2 for httpd:
              # ErrorLog /var/log/httpd/error_association.domain.name.log
              ServerSignature Off
      </VirtualHost>
      
      On Windows systems, you will need to change the DocumentRoot and ErrorLog paths to match Windows conventions, i.e.: "C:\www\association.domain.name".
  3. Create the attachments directory for HOAM to store uploaded and generated files
    > sudo mkdir /var/www/association.domain.name/attachments
  4. Create the sessions directory for HOAM to store HTTP session cookies
    > sudo mkdir /var/www/association.domain.name/sessions
  5. Set the appropriate file permissions for the website directory. You'll likely want the ownership of the directory to be as the same user as the web server runs as. On a Linux system, this is typically the www-data or apache user, meaning you will enter something similar to the following:
    > sudo chown www-data:www-data -R /var/www/association.domain.name/
    or
    > sudo chown apache:apache -R /var/www/association.domain.name/
    HOAM performs several checks at startup to make sure the essential permissions are set and will inform you if they are not.
  6. It is critical that overall file and directory permissions and ownership are set correctly! Strange and difficult to reproduce errors are possible if they are not correctly set.
  7. You will probably need to restart Apache so it learns about the new sites. In Windows, restart the service from the Services applet. In Ubuntu, run the below command:
    > sudo service apache2 restart
    In Redhat/Fedora, run the below command:
    > sudo systemctl restart httpd

Installing HOAM

The following steps can be performed from within your web browser by navigating to http://association.domain.name/install.php and allowing the installation script to handle it for you. This requires you to have administrative credentials to the MySQL server.

Alternatively, follow the below steps if you would like to install HOAM manually.

  1. Create the initial database
    1. Select a name for your database, MySQL user account that will access the database, and password for this account.
    2. Start your MySQL database client with a user account that has permissions to create other users and databases.
    3. Create database:
      mysql> create database hoam_xyz;
    4. Create database user:
      mysql> create user xyz_user@localhost identified by 'password';
      mysql> grant create temporary tables, delete, drop, execute, insert, select, update on hoam_xyz.* to xyz_user@localhost;
      In earlier versions of MySQL use the following syntax instead:
      mysql> grant create temporary tables, delete, drop, execute, insert, select, update on hoam_xyz.* to xyz_user@localhost identified by 'password';
  2. Import the initial configuration
    You'll need to use an MySQL account with greater privileges to import the default database as the HOAM account does not have create privileges only create temporary tables.
    1. Import default database:
      > mysql -u admin_user -pPassword hoam_xyx < hoam/install/default_db.sql
    2. Import stored procedures:
      > mysql -u admin_user -pPassword hoam_xyx < hoam/install/storedProcedures.sql
  3. Update the hoam-config.ini with database server connection information. This file contains the connection information for the database server that HOAM will access.
    ; HOAM configuration file with database connection settings, created
    ; automatically during the initial installation of HOAM.
    ;
    ; Note!
    ; -----
    ; The characters {}|&~![()" have a special meanings and should be avoided.
    ;
    ; Using 'localhost' for the hostname may cause problems with socket connections
    ; on some UNIX (Linux) systems. The recommended alternative is to use 127.0.0.1
    ; to force TCP/IP connections.
    
    [HOAM_DB]
    engine = mysql
    dbname = hoam_xyz
    user = xyz_user
    password = xyz_user password
    server = localhost
    port = 
    
    ; No further configuration is required
    ; ------------------------------------
    ; All additional customization is done in your web browser
    

Maintenance Script

HOAM comes with a maintenance script that it expects is run once per day. This script performs several functions including application of assessments and fees, sends reports based on the activity in the last day (for instance, invoices paid and users logged in), and checks system integrity.

It's reasonably important that the maintenance script is scheduled to run automatically once per day; we recommend scheduling it to run at midnight. There are a few safeguards built into the script in the event that a day is missed or if it aborts in the middle of a run, but this should not be used as an excuse to avoid scheduling the daily run. Should the script not be set up to run automated, you can manually run it from the Website Administraton page.

The script should be scheduled using either cron on UNIX or as a scheduled task on Windows.

On an Ubuntu 8.10 system and newer, enter create a new file, hoam in /etc/cron.d/

> sudo nano /etc/cron.d/hoam
and create the cron entry:
# Added HOAM nighly maintenance script
0 0 * * * www-data php -f /var/www/association.domain.name/hoam/scripts/diag/maintenance.php
The cron job should run as the same user account that the web server (Apache) is running as so that it has the same permissions. On most Linux-based systems, this is the www-data or apache user, on Windows it's the same user that the Apache service is running as.

Installation Troubleshooting

The remaining configuration of HOAM itself is done online. Start a web browser and point it at the location of the HOAM installation, eg, http://association.domain.name/.

If you've made it this far and you are now receiving the below (or similar) message from the web server:

Forbidden

You don't have permission to access / on this server.

Then you're likely running into a file permissions issue. The web server needs to be able to read and execute the files in the location you've chosen to install HOAM. In Windows the default filesystem permissions are usually sufficient to allow this, but you may need to check the directory permissions under the Security tab in Windows explorer. In Linux/UNIX systems, try running the following:

> sudo chmod 705 /var/www/association.domain.name/
$ sudo chown -R www-data:www-data /var/www/association.domain.name/

If you're seeing the default Apache website, then you've forgotten to restart Apache and load the new configuration. Simply restart Apache as noted above and try again.

Initial Configuration

Congratulations on installing HOAM! Several default pages have been created and configuration options have been set for you already. Please review the information below for next steps.

Default Password

A default administration account has been configured
Username "Admin", password "admin". Please note that the password is case sensitive
This account provides complete access to the site to add/remove homeowners, budget entries, user accounts, new properties, run reports, etc.

Initial Customization

It's recommended you start by performing the following steps:

Quickstart>

  1. Change the default password for the Admin account.
  2. Navigate to Website Administration ⇒ System Configuration
  3. Enter vendors used by the Association; at a minimum an account needs to be created for the Association itself as well as the management company. (HOA AdministrationFinancial AdministrationVendor AdministrationList Vendors).
  4. Review the default financial accounts and add or remove any as necessary; at a minimum Income and Expense accounts need to exist. (HOA AdministrationFinancial AdministrationAccount AdministrationList Accounts).
  5. Add new streets and lot numbers for all of the residences in your neighborhood.
  6. Add homeowners for each of the newly created addresses.
  7. Review the default budget categories and add or remove any as necessary. (HOA AdministrationFinancial AdministrationCategory AdministrationList All Categories).
  8. Create a Budget to track your expenses and income against. (HOA AdministrationFinancial AdministrationBudget AdministrationList Budgets).
  9. Review and modify the default violation categories to match the specifics of your governing documents (HOA AdministrationViolation AdministrationViolation Category AdministrationList All Categories).
  10. Edit the home page (click in the upper-right corner) to remove the welcome notice from the main page.

Step-by-Step Overview

Change the default password for the Admin account
Upon first login, you'll be required to change the password of the Admin account. Please use a secure password, as this account has permissions over any part of the system, and cannot be disabled.
Update the System Configuration
Please note, all Configuration fields are disabled by default to prevent unintentional changes. In order to make changes, click the Enable checkbox next to each individual option.
Here are the highlights of what you should review for change the first time through:
Attachments
You should generally be able to leave these all at the defaults. The exceptions are:
Maximum File Size
The default, 100Mb, should be sufficient for most uses. You'll need to make sure that your PHP configuration supports the file size listed here.
Enable Attachment Previews
If enabled, you'll need to make sure ImageMagick is installed and in the path.
Budget
There are many several areas that will need to be updated on this tab:
Association Assessment Frequency
Select how often your association collects assessments. Single-family associations are typically once per year (annual), and condominiums are typically monthly.
Calculate Dues Amount For
The vast majority of the time, this will be Single Residence. In some older condominium associations, the regular assessment amount is different for every unit based on the square footage.
This setting is dependent on the Association Assessment Amount field being set correctly.
Association Assessment Amount
The meaning of this field changes slightly depending how assessments are being calculated (set by the Calculate Dues Amount For field).
When Calculate Dues Amount For is set to Single Residence, this is the full dollar amount of the regular assessment (eg, $150.00 per month). When set to Unit Square Footage however, this is the amount to charge per square foot of the unit.
The unit square footage is set when you add lots and addresses to the system.
Assessment Date
Enter the date for HOAM to create the first assessment automatically. Once HOAM passes this date, it will create assessments automatically based on the schedule set above (ie, for annual assessments, they will be created once per year).
Use Days or Months for Assessment Calculation
This field, along with Number of Months/Days After Assessment Date Payment Due and Number of Months/Days After Assessment Date Payment Late, determine how HOAM treats assessments as being on-time, late, or delinquent.
Number of Months/Days After Assessment Date Payment Due
Number of Months/Days After Assessment Date Payment Late
In general it's a good idea to allow some grace period after assessments are due to allow for payments to be mailed to owners and for them to open and send a payment in response. For all except monthly dues, we recommend using months, with at least one month for allowing payment to be received, and a second month before charging late fees.
Administrative / Collection Fee
Optional -- if not needed, set the value to zero.

System Configuration

Virtually all aspects of HOAM can be modified via the System Configuration page (accessed via Website ConfigurationSystem Configuration). Here you will find options for controlling how HOAM handles finances, user accounts, system security, page displays, and more.

It's important to note that many of the settings in HOAM come pre-configured with default settings that work well for most installations.

In general, you should never need to modify any of the values for any of the Flags, or table Field Lengths. Doing so, especially on a system that has been in use previously, could cause significant problems.

Attachment Configuration

You can probably safely leave all options on this tab at their default values.

Maximum File Size
The default maximum file size HOAM supports is 100Mb, which should be sufficient for most needs.
Minimum Description Length
Specifies the minimum number of characters that must be provided for an attachment when it is uploaded. By default, the length is zero, meaning no description is required.
Enable Attachment Previews
Controls whether HOAM will attempt to create previews of attached files to increase the speed when viewing them later. Attachment previews are kept in a separate directory from the normal attachment.
Preview Image Height
The size in pixels of preview images.
Preview Image Width
The size in pixels of preview images.
Flags:
Attachment
Flag used to associate an attachment with Advertisements.
Budget
Flag used to associate an attachment with Budget entires.
Budget Vendor
Flag used to associate an attachment with budget Vendors.
Homeowner
Flag used to associate an attachment with Homeowners.
Insurance
Flag used to associate an attachment with Insurance policies.
Lot
Flag used to associate an attachment with physical property Lots.
Violation
Flag used to associate an attachment with deed restriction Violations.
Vote
Flag used to associate an attachment with Votes.
Work Request
Flag used to associate an attachment with Work Requests.

Budget Configuration

Email Configuration

Send Automated Emails

Please note, this is completely separate from the Email Validation configuration option under Users Configuration.

File Configuration

Group Configuration

Homeowner Configuration

Letter Configuration

Logging Configuration

Messageboard Configuration

Lot Configuration

In general, the options available under Lot Configuration should be left at their default values; the exceptions being the selection of which Association Common Areas are available (if any), and whether there is any Miscellaneous Property to track.

Common Areas

Many neighborhoods contain Common Areas that are maintained by the Association for the benefit of the property owners, such as parks, pools, clubhouses, and more.

Enabling these various items in the configuration has them show up in other portions of the system such as Work Requests, allowing owners or residents to report issues such as a park that has trash, pools with too much or little chlorine, et cetera.

Miscellaneous Property

Miscellaneous property is used to managing other items that the Association may own, such as clubhouses, parks, parking spaces, and pools. While not every Assocation has these items, those that do often allow the rental/usage of them by owners.

Enabling this option causes a new section in the HOA Administration section to appear, allowing the creation of and rental tracking various property. Items listed here may be assigned to specific owners, and the costs associated are automatically accrued to owner's accounts for the rental period specified for each item: parking spaces and storage units are generally configured monthly, while clubhouses would typically be rented for a single day.

News Configuration

Organization Configuration

Sections Configuration

Users Configuration

Email Validation

If email validation is enabled, the fields will be marked as mandatory in all user editing forms, and errors will be given if addresses are not provided. Additionally, several changes to user account creation and password resets occur:

We recommend leaving this option enabled as it allows much more secure password resets and also usually helps cut down on vandalism of the site (such as spam posts in the messageboards).

Please note, this is completely separate from the Send Automated Emails configuration option under Email Configuration.

Violation Configuration

Website Configuration

Record Installation

This setting controls whether HOAM reports back to ARP Realty Services, Inc. that it has been installed and is running. This reporting happens when the maintenance script runs, and can be disabled with this configuration option.

The information sent includes:

ARP Realty Services, Inc. is using this information right now to simply gauge the number of installs in the wild (outside of our internal customer base), as well as which versions are in use. At some point we may also use the email address obtained to send notices of HOAM version upgrades and/or security issues that have been discovered. There are no plans to use this for any sort of marketing, and no information is sold to third parties.

Wiki Configuration

Work Request Configuration

Daily Use

Advertisements

The advertising options in HOAM are extremely primitive compared to commercial offerings from Google and others -- this is meant more as a way to offer a way for neighborhood companies to receive a small amount of exposure for either free or in exchange for goods or services they've offered the Association.

For instance, you may have businesses run by homeowners, or local companies may have donated to a neighborhood event (such as National Night Out) and the Association would like to advertise their business.

At this time, only image-based advertisements can be shown (no text-only or animated ads). Also, no reformatting of images is done (to either increase or decrease the image size to fit the available space) — however, HOAM does limit the total space available via CSS to make sure page formatting is not completely broken.

Four page locations are available for advertisements to be displayed:

  1. Left Toolbar
  2. Top of Page
  3. Top of Content
  4. Bottom of Page

If more than one advertisement has been specified for a particular location, one will be picked at random to display on each page load.

The other available options are an URL to send users to when the advertisement is clicked, the first date to display the adversisement, and the last date to display the advertisement.

In order to view how many times the advertisement has been shown to users (impressions), and how many times someone has clicked (engagements), you can look at the List All Advertisements menu option.

Articles

Title
Enter the title of the article here, eg. Meeting Minutes April 13, 2018.
URL Name
This is name of the article shown in the URL bar, eg. minutes_20180413.
Groups Allowed to View
The documentation section on Groups is far more comprehensive, but in short this is how security and privacy is configured for articles. Only a member of the selected groups is able to view (or even be aware via a document tree) that the article exists.
This becomes useful for having documents private to just the Assocation Board of Directors, the Officers, committee members, or any other groups you create. For instance, you could have a document that only the Landscape committee can access but not the Social committee, or visa versa. Another example is to have documents that are only available to property owners but not renters.
Root Article ID
Root ID. This is how HOAM understands where to place and display your article on the website, as well as determining the proper position in the document tree. While eventually there may be a better way to do this, at this time it's necessary to manually determine the Article ID of the article you would like to be the parent, and then copying and pasting that ID as the Root ID if the new article.
Article Content
While you can enter and use standard HTML tags, many standard wiki-style formatting options and tags are available for use and are the preferred way to mark up content.
See Wiki Markup below for more information. Another example of all of the Markup options is available online under the HOA Administration ⇒ Form Letters ⇒ Add New Letter page, select the ZZZ Test Letter option.
Keywords
You can add additional words or phrases to a document that will be added in the HTML code to make it easier for search engines to understand the content. See https://www.w3.org/TR/2011/WD-html5-author-20110809/the-meta-element.html for more information.
Leadin
When someone performs a search on the website, the provided keywords are normally shown. However, you can provide a more detailed description that will be shown instead.
Summary
A summary of the article contents can be provided here. The document summary will be shown at the top of the page when viewing the article, and will also be shown in searches if a Leadin has not been set.
Post Start Date
If you would like an article to be only available after a certain date, enter that here.
Post End Date
If you would like an article to no longer be shown after a certain date, enter that here.
Comments Flag
Whether the article allows comments to be posted to the article. Currently this has no effect.
Draft Flag
Whether the article is currently in draft status. Currently this has no effect.
Redirect Flag
Whether the article is used for redirection to a new URL. This acts the same as an HTTP 302 redirect. This is useful if you previously sent out a notification with a misspelling or later decide to change the URL for an article but don\'t want people to be confused.
It is necessary to enter the full URL, eg: http://www.example.com/new_location/

Wiki Markup

All of the options below are hard-coded in the documentation to show specific values; in a live system they will display the information contained in the configuration.

__Underlined Text__
Underlined Text
--Line-Through Text--
Line-Through Text
''Italic Text''
Italic Text
'''Bold Text'''
Bold Text
'''''Bold and Italic Text'''''
Bold and Italic Text
__--'''''Underlined, Line-Through, Bold and Italic Text'''''--__
Underlined, Line-Through, Bold and Italic Text

{{{
Pre
    formatted
        text
test.
}}}
Pre
    formatted
        text
test.
---- (Horizontal Line)

[[email:sales@arprs.com]]
sales@arprs.com
[[email:sales@arprs.com|Email the sales department]]
Email the sales department
[[email:{{ORG_EMAIL_MANAGEMENT}}]]
management@demo.arprs.com
[[email:{{ORG_EMAIL_MANAGEMENT}}|Email the management company ]]
Email the management company
[[note:Useful for calling out information on a page. Floats left.]]
Useful for calling out information on a page. Floats Left.
[[noter:Used with an 'r', will be on the right-hand side of the page instead. Floats right.[http:privacy|Privacy Policy]]]
Used with an 'r', will be on the right-hand side of the page instead. Floats right. Privacy Policy
[[http://arprs.com/]]
http://arprs.com/
[[http://arprs.com/|ARP Realty Services, Inc.]]
ARP Realty Services, Inc.
[http:privacy|Privacy Policy]
Privacy Policy
[http:privacy]
http://demo.arprs.com/privacy/
Wiki Vars

All of the options below are hard-coded in the documentation to show specific values; in a live system they will display the information contained in the configuration.

{{FIELD_ONE}} Additional Field One
This option is only available on letters that include additional fields.
{{FIELD_TWO}} Additional Field Two
This option is only available on letters that include additional fields.
{{BUDGET_ASSESSMENT_AMOUNT}}
$200.00
{{BUDGET_FEE_COLLECTION}}
$25.00
{{BUDGET_FEE_LATE}}
$45.00
{{BUDGET_FEE_RETURNED}}
$35.00
{{BUDGET_DUE}}
$100.00
This option is only available in letters (not standard wiki pages).
{{BUDGET_DUE+175}}
$275.00
This option is only available in letters (not standard wiki pages).
{{BUDGET_DUE-10}}
$90.00
This option is only available in letters (not standard wiki pages).
{{BUDGET_INTEREST_RATE}}
18
{{BUDGET_LAST_PAYMENT}}
9/1/2012
This option is only available in letters (not standard wiki pages).
{{CURRENTDAY}}
9
{{CURRENTDAY2}} (With Leading Zeros)
09
{{CURRENTDAY3}}
9th
{{CURRENTDAYNAME}}
Wednesday
{{CURRENTDOW}}
3
{{CURRENTMONTH}}
1
{{CURRENTMONTH2}} (With Leading Zeros)
01
{{CURRENTMONTHABBR}}
Jan
{{CURRENTMONTHNAME}}
January
{{CURRENTTIME}}
09:53
{{CURRENTHOUR}}
09
{{CURRENTMINUTE}}
53
{{CURRENTWEEK}}
2
{{CURRENTYEAR}}
2013
{{CURRENTTIMESTAMP}}
2013-01-09T09:53:30-06:00
{{DATE}}
Wednesday, January 9th, 2013
{{DATE+10}}
Saturday, January 19th, 2013
{{DATE-2}}
Monday, January 7th, 2013
{{HOAM}}
HOAM Link to External Site
{{HOMEOWNER_MAILING}}
{{HOMEOWNER_MAILING}}
This option is only available in letters (not standard wiki pages).
{{HOMEOWNER_NAME}}
{{HOMEOWNER_NAME}}
This option is only available in letters (not standard wiki pages).
{{HOMEOWNER_RESIDENCE}}
{{HOMEOWNER_RESIDENCE}}
This option is only available in letters (not standard wiki pages).
{{LETTER_APPROVER}}
{{LETTER_APPROVER}}
This option is only available in letters (not standard wiki pages).
{{LETTER_FOOTER}}
{{LETTER_FOOTER}}
{{LETTER_HEAD}}
{{LETTER_HEAD}}
{{LETTER_PERSON}}
{{LETTER_PERSON}}
This option is only available in letters (not standard wiki pages).
{{LETTER_SIGNATURE}}
{{LETTER_SIGNATURE}}
{{LETTER_TOPIC}}
{{LETTER_TOPIC}}
This option is only available in letters (not standard wiki pages).
{{LOT_BLOCK}}
{{LOT_BLOCK}}
This option is only available in letters (not standard wiki pages).
{{LOT_LOT}}
{{LOT_LOT}}
This option is only available in letters (not standard wiki pages).
{{LOT_PLAT}}
{{LOT_PLAT}}
This option is only available in letters (not standard wiki pages).
{{ORG_ADDRESS}}
10455 N. Central Expwy
#109
Dallas, TX 75231
{{ORG_CITY}}
Dallas
{{ORG_COUNTY}}
Dallas
{{ORG_DOC_EXPEDITE}}
$50.00
{{ORG_DOC_REFINACE}}
$75.00
{{ORG_DOC_RESALE}}
$175.00
{{ORG_EMAIL_BOARD}}
officers@demo.arprs.com
{{ORG_EMAIL_OFFICERS}}
officers@demo.arprs.com
{{ORG_EMAIL_MANAGEMENT}}
management@demo.arprs.com
{{ORG_NAME}}
The Single-Family Community Association, Inc.
{{ORG_PROPERTY_NAME}}
Single-Family Community
{{ORG_PHONE}}
(214) 810-4626
{{ORG_PHONE_FAX}}
(817) 500-4994
{{ORG_STATE}}
Texas
{{WEBSITE_BLURB}}

Congratulations on installing HOAM!

{{WEBSITE_DOMAIN}}
demo.arprs.com
{{WEBSITE_URL}}
http://demo.arprs.com/

Attachments

Financial

Accounts

Budgets

Categories

Vendors

Form Letters

Homeowners

Lots

Miscellaneous Properties

In addition to individual residences, an association may sometimes also have other properties that it manages such as clubhouses, pools, parking spaces, and storage facilities. HOAM has the ability to keep track of these items as well, including rental periods and charges to individual owners.

Users

Violations

Violation Categories

Violation Severity

Voting

Advanced Configuration

Attachments

All file attachments stored by HOAM are kept in a directory named attachments. Thumbnails of attachments are stored in subdirectory of attachments called thumbs.

HOAM classifies attachments by the type of object they're attached to: budget entries, homeowners, violations, votes etc.

There is no security on attachments — if an attachment link is created to a sensitive file, anyone with that link can view the attachment.

Groups

Users may be members of multiple groups. By default, if not logged into the system, all users are members of the Anonymous group. Anonymous members are also members of the Everyone group.

Groups are arranged in multiple trees. For instance, in the default system configuration, the following groups are defined, and each descendant group is a considered a member of any groups it's parent is a member of. It's important to note, however, that because of permission checks HOAM runs, the System Administrators group can be considered a member of all of the groups.

In other words, all HOA Board Members are considered members of the Registered Users group. You may notice that the System Adminstrators group is listed as a member of several different groups; this gives a member of System Administratrs access to groups that they would normally be prohibited from. For instance, if an administrator were to rely solely on inheritance then only being a member of the HOA Board Members group would prevent them from accessing items restricted to Anonymous members.

As shown in this diagram, the System Administrators group does not have access to information restricted to members of HOA Social Committee.

HOAM also supports multiple trees. For example, the following group hierarchies are also configured:

While it may seem cumbersome for the same group to be listed multiple times, there is a great amount of flexibility that is allowed by this configuration. For instance, to set up a wiki-type system where everyone is allowed to edit the content of the system, you could simply add the Everyone group to the Edit Articles group. However, we don't recommend this due to the security risks inherit in this design using HOAM (currently, HOAM executes any PHP code contained within articles; allowing anyone to create and run PHP code on your system is inviting disaster!)

Messageboard

Like Articles, the theory behind the messageboard is that all messages are based off of a single tree. The first message in the system, which always exists, is assigned (by default) an id of 0 (zero). The immediate descendants of this root message are considered separate message boards, and are treated slightly different than other messages in the system. When a message with a root_id of 0 is displayed, the text of the message is displayed, and then any messages below it in the tree are displayed. In practice, there is no real difference between this and other message board systems.

Messages are listed in each board in reverse chronological order. That is, the newest messages are at the top of the page, and older are at the bottom.

Because message boards are treated the same as regular messages, the message board name is used as the id and as the root_id of other messages.

Authors of messages are allowed to edit their posted messageboard for (by default) 48 hours. Members of the System Administrators group have the ability to delete and edit existing messages (even from other users) at any time.

Plugins

HOAM supports plugins to modify and/or enhance the features available. A selection of plugins are available and come with HOAM, and others are listed on the website.

Sections

HOAM displays (by default) a list of all available down-level pages based from the article root.

Users

Users may be members of multiple groups. By default, if not logged into the system, all users are members of the Anonymous group. Anonymous members are also members of the Everyone group.

Since HOAM is designed to support and administrate homeowner associations, a good deal of the system revolves around determining whether a user has permissions to access the requested functions. You may configure user accounts so (the Association's Treasurer, for instance) they have the ability to review the budget and the various invoices, but not violations or homeowner details. Similarly, you can configure an account (someone on the Social committee) to access homeowner rosters and contact information, but not financial or violation details.

There are two default user accounts created when HOAM is installed:

The Admin account is the one you specified the password for upon installation. The HOAM System Account is used for tagging automated entries created by HOAM (for instance, when fees are automatically applied, when creating certain log entries, etc.)

Wiki / Articles

The theory behind the articles is that all articles on the site are based off of a single tree. The first article in the system, which always exists, has an URLname of "" (NULL).

When adding new articles to the system, starting from the root, you would enter the root_id for the first article in the root_id field. Subsequent articles added under this new article would reference it's root_id as their root. Generally, the articles directly off the root are already specified as Sections.

Articles can be secured such that only the specified groups can read them. Please note, however, that someone with the ability to edit or delete articles may still be able to view the contents even if they would not otherwise have the appropriate group membership.

See Also

Wiki-Style Markup Supported

HOAM supports a number of wiki-style markup tags in articles and news items. There are also a number of variables that can be entered and expanded dynamically during display.

An example of all of these options is available online under the HOA Administration ⇒ Form Letters ⇒ Add New Letter page, select the ZZZ Test Letter option.

See Also

Development

No developer ever thinks their change is going to break anything for anyone. It's the QA Law of What Could Possibly Go Wrong. ;)
Adam Williamson

If you want to download new versions, subscribe to the HOAM mailing list or even take part in the development of HOAM, we refer you to its homepage at http://hoam.arprs.com/ or on Sourceforce at https://sourceforge.net/projects/hoam/. New developers and testers are more than welcome!

If you have any bug reports, suggestions for improvement or simply want to tell us that you are using HOAM, feel free to post to the HOAM mailing list. If you have found any security problems in HOAM, please contact us directly at security@arprs.com (rather than posting on the mailing list) so we can correct it and release an update before you tell the public about it. We will pay a bounty of $50.00 for each confirmed (at our discretion) security problem.

The best place to get up to speed on the development of HOAM as well as touch base with other developers is on the mailing list.

Bug Tracker and Source Repository

At this point in time, the bug tracker and source repository are not open to the public; as it has been in use for many, many years, there are concerns that some PII may be in both right now. When we have time, a new repo and bug tracker will be migrated to and opened to the public.

Languages and Country Specific Settings

The most-developed language and country settings are for U.S. English and the United States of America. Adding new languages and regions should be as easy as creating the new reference file. If you do create customizations for HOAM, please send them to us so others can benefit.

The below translations were performed by volunteers, and may be incomplete or incorrect. Please contact us if you've found a mistake in a translation, or would like to help translate HOAM to your language.

Although HOAM has been developed and used solely in the United States, theoretically it is adaptable for usage in other regions of the world. All that should be necessary is creation of a new country file in the country directory, which will be automatically discovered. Should you run into issues, please contact us, as we'd like to make sure HOAM is usable outside the U.S.

Plugins

HOAM supports plugins to modify and/or enhance the features available. A selection of plugins are available and come with HOAM, and others are listed on the website.

If you write a plugin that adds a new database table, HOAM will automatically check it as part of the maintenance routine.

3rd Party Code

HOAM uses, or is based on several 3rd party functions, scripts, or ideas. In roughly alphabetical order:

Additionally, most of the icons used in HOAM were created by Mark James (http://www.famfamfam.com/lab/icons/) which were graciously made available under the Creative Commons Attribution 2.5 license.

About The Author

HOAM is primarily the work of one author, Robert Butler. He considers himself to be an intermediate-level PHP and beginner-level MySQL programmer at best. In fact, HOAM was originally begun in 2002 as a way to learn PHP and MySQL. That being the case, more advanced programmers will likely find various portions of HOAM that could be more elegant or efficient. However, we are simply unaware of this, or (being aware of a specific section) don't have the time to investigate further at this point.

In addition to learning PHP and MySQL, Robert couldn't find another CMS that met his needs, or that he could quickly get up to speed with. In fact, in 2002 'CMS' as a term was unknown to him, and thus he didn't even know what he wanted. He simply needed an easy way to manage to post news and help manage the homeowners association he was a part of at that time. Indeed, HOAM has already well outgrown the initial understanding he had when he began.

That being said, there are certainly portions of HOAM that are brilliant, and equally portions where you'll be awestruck at how poorly it's written (and equally amazed that it works at all). Along those lines, because Robert is not a programmer by trade, and some portions of HOAM may go months or years between revisions, the code is kept as simple as possible so it doesn't take long to get up to speed after a break.

Bug and Security Reports

If you have any bug reports, suggestions for improvement or simply want to tell us that you are using HOAM, feel free to post to the HOAM mailing list.

If you have found a security problem in HOAM, please contact us directly at security@arprs.com (rather than posting on the mailing list) so we can correct it and release an update before you tell the public about it. We will pay a bounty of $50.00 for each confirmed (at our discretion) security problem.

Bug Tracker and Source Repository

At this point in time, the bug tracker and source repository are not open to the public; as it has been in use for many, many years, there are concerns that some PII may be in both right now. When we have time, a new repo and bug tracker will be migrated to and opened to the public.

Optional Server Configuration Changes

There are several system configuration changes you can make that will increase the security of your webserver. These are general changes you can make that have nothing to do with HOAM itself; they're simply good practice. A complete discussion of the changes you can make is outside the scope of this document, but among the options are:

After any / all of the below changes are made, you will need to run the following command to make sure they take effect.

Ubuntu:
> sudo service apache2 reload
Redhat/Fedora:
> sudo systemctl restart httpd

Comment out the default Apache websites

By default, Apache creates a server that lets you know the installation is complete. Comment out (by placing a '#' at the beginning of each line) the configuration for this default site in the /etc/apache2/sites-available/000-default.conf or /etc/apache2/sites-available/default configuration file.

Minimize Apache Response Headers

You may want to minimize response headers from Apache; this will very slightly reduce the amount of traffic your server is sending (improving performance), and will also obscure the version of Apache running on your server (improving security). To do so, edit the /etc/apache2/conf-enabled/security.conf file (older versions use /etc/apache2/conf.d/security) and change these two lines:

ServerTokens Prod
ServerSignature Off

Disable mod_status for Apache

Especially When running on a shared server, one Apache feature that you will probably want to disable has to do with reporting of the server status. This is known to cause security a issue with eavesdropping on server accesses. To disable it, the recommended fix is simply disabling the feature:

> sudo a2dismod status

If removing the status module is not an option, then you'll want to add the below code to your configuration file or .htaccess file.

<Location /server-status>
  SetHandler server-status
  Order Deny,Allow
  Deny from all
</Location>

Enable mod_evasive for Apache

mod_evasive is an Apache module that provides evasive maneuvers action in the event of an HTTP DoS (Denial of Service) or DDoS (Distributed Denial of Service) attack on the web server. When potential attacks are detected, mod_evasive will block the traffic from the source for a specific duration of time, while it reports abuses via email and syslog facilities. Administrators can configure mod_evasive to talk to iptables, ipchains, firewalls, routers, and etc. to build a comprehensive DDOS prevention system for the high traffic busy web server.

> sudo apt-get install apache2-utils libapache2-mod-evasive
$ sudo mkdir /var/log/mod_evasive
$ sudo chown www-data:www-data /var/log/mod_evasive/
Make sure you adjust the thresholds in /etc/apache2/mods-enabled/evasive.conf as necessary, as you will end up with client errors (typically HTTP 403 errors) if they are set too low. Some pages, such as the HOAM Website Configuration page, will easily trigger low thresholds when loading.

Some experimentation may be necessary, but good initial values are:

DOSHashTableSize    3097
DOSPageCount        20
DOSSiteCount        50
DOSPageInterval     1
DOSSiteInterval     1
DOSBlockingPeriod   60

See https://library.linode.com/web-servers/apache/mod-evasive for more information.

Enable mod_security for Apache

ModSecurity is an open source, free web application firewall (WAF) Apache module. It provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring and real-time analysis with little or no changes to existing infrastructure.

> sudo apt-get install libapache2-mod-security2
$ sudo cp /etc/modsecurity/modsecurity.conf-recommended /etc/modsecurity/modsecurity.conf
The older name was libapache-mod-security if you can't locate the package listed above.

One of the default rules, SecRequestBodyLimit limits the page request size and limits file uploads to 128 KB by default. Change this to the size of files you would accept uploaded to the server. This settings is very important as it limits the size of all files that can be uploaded to the server. Also, by default the engine is set to detect only, not prevent issues. Edit the file /etc/modsecurity/modsecurity.conf

#SecRuleEngine DetectionOnly
SecRuleEngine On
SecRequestBodyLimit 32768000
SecRequestBodyInMemoryLimit 16384000

See http://www.thefanclub.co.za/how-to/how-install-apache2-modsecurity-and-modevasive-ubuntu-1204-lts-server for more information.

Secure MySQL

If this is an installation on a new system, it's highly recommended to run mysql_secure_installation to secure the default installation of MySQL.*

mysql_secure_installation is not available on Windows.

Enable TCP SYN Cookie Protection

On Linux servers, you can modify the file /etc/sysctl.conf. Uncomment the following line and make it look like this:

#Enable TCP SYN Cookie Protection
net.ipv4.tcp_syncookies = 1
Make the change active.
> sudo /sbin/sysctl -p

See https://en.wikipedia.org/wiki/SYN_cookies for more information.

Disble Unnecessary PHP Functions

If you have full control over the web server you plan to use HOAM on, you may want to consider modifying php.ini to disallow certain security-sensitive commands that HOAM does not use:

disable_functions=passthru,shell_exec,system,proc_open,popen,curl_exec,curl_multi_exec,show_source

Depending on how PHP was installed, it may already have several entries listed on the disable_functions line; if so, simply append the items above to the end of the existing list. Also, you'll want to make this change to both the apache2 and cli versions of php.ini (although the cli version is not as risky security-wise for our purposes).

If you do not plan on using the attachment preview functionality, you may also disable the exec function. exec is only used in HOAM to call ImageMagick.

Turn Off PHP Expose

You may also want to prevent PHP from the exposing the fact that it is installed on the server, by adding its signature to the web server header. We need to locate in php.ini the variable expose_php and turn it Off. By default expose_php is set to On. Locate the line containing "expose_php On" and set it to Off:

expose_php = Off

After making this change PHP will no longer add it's signature to the web server header. Doing this will not make your server more secure, but it will very slightly reduce the amount of data your server sends and it will prevent clients from easily seeing that you have PHP installed on the system and what version you are running.

See http://php.net/expose_php for more information.

Troubleshooting

Filesystem permission issues:

It is critical that overall file and directory permissions and ownership are set correctly! Strange and difficult to reproduce errors are possible if they are not correctly set.
I'm receiving the message from when I try to load the home page: Forbidden You don't have permission to access / on this server.
You're likely running into a file permissions issue. The web server needs to be able to read and execute the files in the location you've chosen to install HOAM. In Windows the default filesystem permissions are usually sufficient to allow this, but you may need to check the directory permissions under the Security tab in Windows explorer. In Linux/UNIX systems, try running the following:
> sudo chmod 750 /var/www/association.domain.name/
HOAM just dies, no error messages are displayed to help pinpoint the problem!
If the file permissions are incorrect HOAM may be unable to load certain critical files and will just die without displaying any errors.
I'm getting an error, session_start(): Session data file is not created by your uid [...]
PHP requires session files to be owned by the user running PHP (normally the same as is running Apache, ie, the www-data user). You can run the command php -i | grep user or ps aux | egrep '(apache|httpd)' and confirm the user running PHP.
With that information, run
> chown -R www-data:www-data /var/www/association.domain.name/
or
> chown -R apache:apache /var/www/association.domain.name/
This error can also happen if you're trying to run HOAM from a remote network share, usually when mounted via CIFS / SMB. Either mount the share as NFS or run HOAM from local storage.
I keep getting 404 errors for files that I know are there!
I keep having strange errors occur, ie, files can't be included that are clearly in the correct path!
Check to see whether the files (or the directories that contain the 'missing' files) have the group write permission. Some configurations of Apache on ISPs won't allow the files to be accessed if they are group writable. You'll need to set the permissions correctly on those files (for instance, run chmod 740 -R * from the main directory you installed HOAM into). It is occasionally necessary to also set the 'sticky' bit (eg, chmod g+s -R *).
I uploaded an attachment, it shows in the attachment list, but trying to view or download it gives me a blank (0 byte) file?
Most likely the permissions (the file and group ownership) to the attachment directory are incorrect and preventing the creation of the files. The 'attachments' directory and all subdirectories contained within should be owned by the same user the web server is running as (usually www-data on Linux) and have both read and write access. Also try modifying the permissions (eg, chmod 760 -R attachments).
I uploaded an attachment, but the previews aren't working correctly.
Make sure attachment previews are enabled, and that all of the prerequisites (eg, PHP_GD) are met. Otherwise, see the above question about file and group ownership being incorrect for the attachment preview directory as well.
Upgrade keeps failing saying Destination "xyz" for file "abc" is not writeable,
File ownership is likely incorrect. Please make sure the directories where HOAM resides are owned by the same user as Apache. ie:
> chown www-data:www-data -R /var/www/assocation.domain.name/
or
> chown -R apache:apache /var/www/association.domain.name/

Other common issues:

I can see the first page but clicking on any links fails.
You probably don't have mod-rewrite configured correctly. All website access must pass through the index.php file in order for the parsing to work correctly.
Attachment preview images aren't working for PDFs.
This is likely due to a security policy change in ImageMagick. You'll need to edit the ImageMagick policy.xml configuration file and enable read|write access for PDFs. On Linux systems, this is usually in /etc/ImageMagic-6/policy.xml. Search for PDF and change the line from
<policy domain="coder" rights="none" pattern="PDF" />
to
<policy domain="coder" rights="read|write" pattern="PDF" />
Currency isn't formatting correctly (missing commas, dollar signs, etc.)
Make sure you have set the correct locale in the website configuration. If you're using Linux, you can usually run the locale command to retrieve a list of the supported options. Also, if Linux distribution is (or derived from) Debian, see the PHP online docs,
If money_format doesn't seem to be working properly, make sure you are defining a valid locale. For example, on Debian, 'en_US' is not a valid locale - you need 'en_US.UTF-8' or 'en_US.ISO-8559-1'. This was frustrating me for a while. Debian has a list of valid locales at /usr/share/i18n/SUPPORTED; find yours there if it's not working properly.
Trying to list all of the attachments just pops up an XML error.
Make sure the latest version of the stored procedures have been installed.
The maintenance routine takes a long time to run (hours!)
It's likely the culprit is the housekeeping routine that checks the system log for missing entries. The routine attempts to use available memory, but if the value is set too low it will run on disk instead which is much slower. Check the MySQL manual for information on increasing the available memory.
I've tested, and the count of users online is sometimes off by one or two people
The determination of the number of online users is done by counting the number of "active" session cookies stored on the server. Since Windows-based systems don't support atime, and most UNIX-based servers disable atime support nowadays for performance reasons, the routine uses the last modified time. This means the count of users will sometimes be off slightly.
It takes a long time to load the page showing the existing attachments.
If attachment previews are enabled, and if the attachments have not been previously viewed, then new previews must be dynamically created for each file which will take longer. A repeat viewing of the same page will be significatly faster once the previews have been created.
It takes a long time to load system configuration page.
There are a very large number of help links and special input fields that are dynamically created with Javascript each time the page loads. There may be future optimization work done, but slow loading is considered normal.
The maintenance script stopped running with an error about the sequence_table being full?
On systems that have been running for a while with many users, the size of the temporary table created when checking for log manipulation may grow larger than the default 16Mb of RAM MySQL allows in the default configuration. You'll want to modify your my.cnf file and increase the size of the max_heap_table_size and tmp_table_size to 32M or greateer (up to a reasonable size for your web server).
At some point in the future, the log manipulation routine will be rewritten more efficiently, this is a workaround for now.

Footnotes

Date of purchase & sale for each residence
When processing information about specific events or records for a residence, HOAM makes record only of the location and date, and not the homeowner at that time. Instead, it uses the purchase & sale dates to cross-reference entries in the database, and automatically determines who the current homeowner is based on that information.
FQDN
The Fully Qualified Domain Name. See Wikipedia for more information.
HOAM Pronunciation
Since we know people will ask, HOAM is pronounced "home" and rhymes with "roam".
Management of rental properties with HOAM
You can easily use HOAM to manage individual rental properties as well. The only limiting factor right now is how the automatic assessments are applied, but manual creation of monthly rental fees is easily done. All other functions (budgeting, resident contacts, violations, etc.) are just as applicable.
mysql_secure_installation
See https://dev.mysql.com/doc/refman/5.0/en/mysql-secure-installation.html for more information.
Professional management company usage of HOAM
For now, each association managed requires it's own separate installation of HOAM; there is no support for sharing or propagating information between installations of HOAM, meaning that actions (such as adding news, generating reports, viewing vendors, et cetera) must be undertaken for each association separately. The rationale for this is that the goal of HOAM (1.0) is to manage a single Association, and do it well. Support for managing more than one Association adds a lot of complexity, and is planned for post-1.0 development, probably as a separate framework around HOAM itself.
Selection of ISPs and hosting requirements
There are many ISPs to select from around the world, and most should meet the minimum requirements necessary for hosting HOAM. If you desire, however, you may purchase hosting services for your Association from ARP Realty, Inc., and we will handle the initial installation process for you, as well as upgrades to new releases automatically. See https://arprs.com/hosting/ for more information.