Installing Animal Shelter Manager on Windows

A Guide to Shelter Manager 3 configuration

Originally published to dwighttinker.com 04-09-2012 Animal Shelter Manager is a great open source software for dog shelters and rescues. I've been keeping an eye on ASM and like what I see. Version 2 is a java based application, an open source application very similar to all the costly proprietary animal shelter software. Now a new version, v3 is out and introduces a Python web based application that is compatible with its predecessors database, but has a nice and clean HTML GUI and JQuery behavior. I've recommended ASM to my local independent Humane Society and will recommend it to any rescue group or shelter reading. Why? Because ASM is more user friendly, has all the features of expensive proprietary packages, has a dedicated team of contributors who keep it updated and whom provide technical support at https://answers.launchpad.net/sheltermanager. The ASM developers also offer low cost hosting services through http://sheltermanager.com, great value when you consider that they provide the application via the cloud, they backup your data daily, the service provides redundant drives in case of server drive failure, and they keep the software updated. Before you start, please note that you will need to be logged into windows on an administrative account. In addition, the User Account Control in Vista and Windows 7, and your Firewall may cause installation to fail. If so you may need to temporarily disable UAC by following these instructions: http://windows.microsoft.com/en-us/windows-vista/Turn-User-Account-Control-on-or-off. If Windows Firewall doesn't accept ASM you can manually allow the ASM in Windows Firewall through these steps: http://technet.microsoft.com/en-us/library/cc766312(v=ws.10).aspx. We'll illustrate 3 scenarios you may want to achieve depending on the size of your organization and its sophistication. ASM is installed as a client computer application by default, then can be configured for network use easily. It also installs what is considered a development worthy database. It's better than the Assess Jet database, but is easy to create with no additional software and can be backed up simply by copying the database file. Nonetheless, it is still a single user, desktop database that does not scale well. If several people use it at once, or you add quite a bit of data MySQL is a better choice. In fact, the developers recommend MySQL to organizations savvy enough to install it. Hear are our goals. Scenario 1: Installing ASM as a standalone computer application. Scenario 2: Configure the system to be used across a local network. Scenario 3: Installing server applications to use the more robust and efficient MySQL database.

Of course, to reach Scenario 3 all you simply need MySQL installed, but we'll be installing AMPPS. AMPPS is an application that installs, configures, and manages the Apache web server, the MySQL database server, and the PHP and Python application servers. The benefits of this includes the abilities to: Administer your ASM database through your network computers' web browser using PhpMyAdmin. Create automated database backup scripts. Replicate your ASM database on a redundant server as a disaster contingency in the case that the primary server fails. Automatically export updated information to your website. Create online forms that submit information to your database, for example; lost and found pets, volunteer sign-up, organization member sign-up and management, and charitable donations. Before beginning you'll want to prepare by doing the following: Access to a Windows administrative user. A text editor that color codes batch, python, configuration, and PHP file text. http://notepad-plus-plus.org/ is free and will do nicely. If you're going to access ASM across your network you'll need to have access to the software firewall and network router. You need a computer with internet access. Goal 1: Install ASM (For all scenarios) 1. ASM Installation: Download the applications Windows executable file from http://sheltermanager.com. The installer will install python and several python modules that it depends on. Run ASM's install application. The default install path and options are fine.

 During the ASM install you will be asked to install Python and several Python modules separately. Accepting the default options is all that is needed.

Many Windows installations don't install Python's Web module, if so you'll get a connection error when trying to brows to http://localhost:5000, such as the computer in the first image below. In this case you'll need to install the web_py module by going to the Search or Run input on Windows Start menu and typing cmd.

Above: Connection error!. Web_py is not installed so the ASM server will not run.

Solution described below: Start Command and install web_py from inside Python.

 Installing Web Py: When the Command Line Utility opens type two commands. The first moves to the proper folder (Where you installed Python), the second runs a script within it: cd c:\python27\scripts easy_install web.py

Note, some browsers get a double header error when starting ASM before the database is created, if this happens simply change the browser address to http://localhost:5000/database instead of http://localhost:5000 from there the database will be created. 2. Configuring ASM's database connection settings (If moving the default database) The application installs the SQLite database to your user folder. If you want all your Windows users to access ASM you may want to move the database to a common folder such as the program folder ASM was installed in. I. Move asm.db to the new folder, for example, from Users\YourUser\to 'Program files\ASM3\db\' II. In this case you'll edit the database location in ASM's run batch file in the ASM3\asm folder. Look update the line to the new directory: SET ASM3_DBNAME=C:\Users\YourUser\asm.db and change it to SET ASM3_DBNAME=C:\Program files\ASM3\db\asm.db

III.Do the same change in the daily batch file located in the same directory. ASM uses a batch file to run daily tasks, including financial calculations, and several reports. You'll want this running. To do so you'll need to edit a line in the daily.bat file, and add the file to Windows Scheduler as a daily task. First, edit the daily.bat file by making sure it's connection settings are the same as those in run.bat, then change the line that calls the cron.py file to a windows cmd format. It looks something like this: "C:\Python27\python.exe" cron.py all It should look like this: "C:\Python27\python.exe" "C:\Program Files\ASM3\asm\cron.py" all The next thing is to add a new task to Windows Scheduler. In the general tab you'll set the task user to a system administrator, provide credentials for the task to save and use, select that you want the task to run whether the user is logged in or not, and set the task to run with the highest privileges. You'll also set a daily trigger and you'll define a new action that starts a program: "C:\Program Files\ASM3\asm\daily.bat" with the argument start "" "C:\Program Files\ASM3\asm\daily.bat".

Goal 2: Configure your network to access the ASM application. This is fairly simple, but the specific steps change depending on your computer setup. 1. The computer that will host ASM will need to be given a static IP address. Generally, you can leave Windows configured to accept a dynamic IP and you'll configure the router to provide it with a specific IP, perhaps '192.168.100.100'. This way, each computer can simply be given a web browser shortcut to 192.168.100.100:5000 that will open ASM. 2. PC Firewall Configuration: Each computer you want to use will need its firewall to allow input from ports 5000 and 80. These are the ports ASM's Python web server and the Apache runs on. Do this from within whatever Firewall application you use. 3. The computer hosting ASM will need its firewall to allow outgoing and incoming data on port 5000. 4. Your network's router will need to be configured to allow port 5000 between computers on the local network as well as an outgoing port to the internet. Goal 3: Install MySQL Database 1. Download and install AMPPS. AMPPS installs and configures the Apache web server, PHP, and MySQL, the primary resources you'll likely use to extend ASM's functionality. Since this folder will include your web server you should install it at the root of a drive rather than in the Program folder.

2. Configure AMPPS to start on log-in by checking 'Start on Session Start-up'.

3. Click AMPPS Home at the bottom of the AMPPS Control Center, then click Add Database to create an empty database named asm This will take you to MySQL's Create Database page so the database can be named and created.

4. Go to PhpMySQL's SQL menu and create an asm user, such as: GRANT ALL ON asm.* TO asmuser@'%' IDENTIFIED BY 'testing'; This would create an asm app user named asmuser with the password 'testing' that can access the database from any computer. If you want the user to only access asm from the computer it's installed on you'll replace '%' with 'localhost'.

5. Go to 'Program files/ASM3/asm' and edit the run batch file. You'll want to delete the first 2 lines, or comment them out by adding :: at the beginning of each line: SET ASM3_DBTYPE=SQLITE SET ASM3_DBNAME=C:\Users\Dwight\asm.db then add the MySQL connection information, something like this: SET ASM_DBTYPE=MYSQL SET ASM_DBHOST=localhost SET ASM_DBPORT=3306 SET ASM_DBUSERNAME=app_user SET ASM_DBPASSWORD=My-Very_5trongPasswoord!!^^ SET ASM_DBNAME=asm

6. Open the daily batch file and make the same edits. 7. In the db.py file, update MySQL's connection settings on lines 29-33.

Restart the AMPPS application from AMPPS Control Panel and logoff the ASM application if you were logged-in. When you open ASM3 it should populate the MySQL asm database. However, depending on your system setup it may not populate the asm database. The application has traditionally come with a sql file included for populating the database, but it was left out of the current version. You can download a sql file to create the asm tables and populate the lookup and configuration information from my website at http://dwighttinker.com/my/apps/tutorials/asm.sql. You can open the file from PhpMyAdmin or copy and paste the contents into the PhpMyAdmin's SQL input form. That's it. You should be able to access the asm database using PhpMyAdmin from http://localhost/phpmyadmin/ or 192.168.100.100/phpmyadmin/, stype='page-break-after:always;' replicate the database on additional installations on your network, and create PHP scripts in c:\AMPPS\www\ that are accessible via A http://192.168.100.100 across the network to manage and share ASM data. If you want to move on to database replication in order to keep a synchronized database on a backup server you can read further using other tutorials. You'll need to install ASM on the additional computer, configure it to run on MySQL, and configure the network router and the 2 servers' to allow MySQL's port, typically port 3306. Then you'll replicate the databases using the procedure in the following link: http://www.linuxjournal.com/content/database-replication-mysql.