Developing for Aspen Discovery
Setting Up a Development Environment
Aspen uses a LAMP or WAMP stack to run. We have developers using both Windows and Mac OS X for development with success. If you plan to run on Windows, we recommend using a WAMP package like those created by XAMPP. When selecting an installer, select an installer that includes PHP 8 or later.
We recommend the following tools for Aspen development due to their ease of use and ability to debug code easily.
PhpStorm does have a small subscription fee, but we find it to be very worthwhile.
Once you have setup your LAMP/WAMP stack and your development tools, read on for instructions to install Aspen on Linux, Mac OSX, or Windows.
Note: after installing Bitnami for Windows, you will want to add the PHP runtime to your path to make running scripts from Aspen Discovery easier. After adding PHP to your path, you will need to restart Windows.
Installing Aspen on Linux or Mac OS X
Aspen can run in production in a variety of environments. We recommend CentOS, RedHat, and Debian. Other environments may need code tweaks to run properly. These instructions are designed for CentOS 7. Other environments may require some changes to commands to run.
Installation Steps
- Update the server
sudo yum check-update - Install git
sudo yum -y install git - Install the Aspen Discovery code (if you will be doing code development, you will want to create your own fork of the main git repository)
cd /usr/local
sudo git clone https://github.com/Aspen-Discovery/aspen-discovery.git
Checkout the current branch:
cd /usr/local/aspen-discovery/; sudo git pull origin 24.xx.yy - Run the installer to setup the system files
cd /usr/local/aspen-discovery/install/
sudo ./installer.sh
At the end of the installer, you will secure mariadb using a new password of your choosing
When setting timezone use one of:
America/New_York
America/Chicago
America/Denver
America/Los_Angeles - Restart the server to have SELinux changes take effect
sudo reboot now - The next step will be easier if you have connection information to your ILS. For Koha you will need ODBC and REST API connection information.
- Setup the site
cd /usr/local/aspen-discovery/install/
sudo php createSite.php - Run database updates by logging in with the aspen_admin user you created while setting up the site and then going to: System Admin > DB Maintenance > Run
Your site is now setup, but you will need to do some configuration of the site.
- Ensure all ports other than 80 and 443 (and 25 if needed for SSH access) are firewalled so they cannot be accessed by the world.
- Add the server external IP to the list of IPs as 'Allow API Access'
- Setup Initial Library and Location information
- Setup Account Profile (this is setup during the install process if you are using Koha)
- Setup Indexing Profile
- Setup Translation Maps
- Setup recaptcha
- Run a new index
- Setup cron (not needed for development installs)
- Setup SSL (not needed for development installs)
Installing Aspen on Windows
Aspen can run for development on Windows. We do not recommend using Windows for production environments. Prior to starting these steps you should setup your environment.
For Windows, we also recommend using GitHub Desktop to make working with git easier.
Cygwin will add common Linux commands to your Windows shell and is recommended for Aspen development.
Installation Steps
- Make a fork of the main Aspen Discovery Code from https://github.com/Aspen-Discovery/aspen-discovery.
- Install the Aspen Discovery code by cloning the repository to c:\web\.
- The next step will be easier if you have connection information to your ILS. For Koha you will need ODBC and REST API connection information.
- Setup the site
cd c:\web\aspen-discovery\install\
php createSite.php - Run database updates by logging in with the aspen_admin user you created while setting up the site and then going to: System Admin > DB Maintenance > Run
Your site is now setup, but you will need to do some configuration of the site.
- Ensure all ports other than 80 and 443 (and 25 if needed for SSH access) are firewalled so they cannot be accessed by the world.
- Add the hostname you want to use for aspen to c:\Windows\System32\drivers\etc\hosts
- Add the server external IP to the list of IPs as 'Allow API Access' (not needed for development installs)
- Setup Initial Library and Location information
- Setup Account Profile (this is setup during the install process if you are using Koha)
- Setup Indexing Profile
- Setup Translation Maps
- Setup recaptcha
- Run a new index
- Setup cron (not needed for development installs)
- Setup SSL (not needed for development installs)
PHP Guidelines
Settings for PHPStorm are stored in git in the root directory as PHPStormCodeStyle.xml and can be imported into PHPStorm to automatically configure your editor.
- Code should use tabs for indenting, not spaces.
- Hard wrap after 500, but try to keep comments formatted so they are readable in the editor with soft wrapping as needed.
- Function names should use camel case.
- Property names should use camel case.
- Table names in the database should be all lower case with underscores separating words.
- Arrays should be constructed using square brackets rather than array(...)
- Opening brackets for functions should be on the same line as the function name with a space after the function parameters.
- Opening brackets for class declartions should be on the same line as the class name.
- If there are empty functions / methods, place the braces on one line
- else should be on its own line
- No single line if statements without braces
- for & foreach statements should use braces
- while statments should use braces
Coming Soon!
Aspen supplies a default project for PhpStorm. Before opening the project code/web/.idea and copy and rename any files with a .default extension to the same name without the .default extension. After that is complete, you can simply open the project in PhpStorm by selecting File > Open within PhpStorm and then selecting the code/web directory. To apply the proper styling for PHP, select File > Settings and then within the settings navigate to Editor > Code Style. Click the gear icon next to the Scheme and select Import Scheme. Then choose the PHPStormCodeStyle.xml file from the code directory to import.
Similarly there is a default project for all of the Java indexers. The project is located in code/cron/.idea. You should copy and rename any fines in code/cron/.idea with an extension of .default to a file of the same name without the .default extension. Once that is complete you can open the project in IntelliJ by selecting File > Open and then selecting the code/cron directory.