Developing locally

by Chris Ullyott, Skyler Katz | Last edited: 10/26/2020

With Ekklesia 360 / MonkCMS, it's simple to set up a local development environment to test new changes to your website before making them live. A "local" site is a website that lives inside a folder on your own personal computer, where it can run just as if it were on the web.

Requirements

  1. A local server that uses Apache and PHP. For Mac OS, recommend MAMP. For Windows, see XAMPP.
  2. An FTP application like Transmit, FileZilla, or Cyberduck.
  3. An approved FTP Agreement on file with Monk Development, in case you don't yet have FTP credentials to the website. Request those here.

Setup

  1. Install MAMP (Standard or Pro). The Standard version will work adequately for this purpose but Pro offers easier management of multiple sites.
  2. After installation, the MAMP interface, choose a folder on your computer to serve as the Document Root of your site. This setting is handled differently between standard and pro versions; check the MAMP documentation for information on this if you get stuck.
  3. Download all of your site's files via FTP — except the directories/files "/monkcache", "/monkcache.db", and "/monkimage" — into your document root folder (these folders will be created automatically).
  4. Open the ".htaccess" file with a text editor. If you cannot see this file, it either was not downloaded correctly, or your application needs to have hidden or "invisible" files enabled, to be seen.
  5. In ".htaccess", delete the two lines between "RewriteEngine On" and "RewriteBase /" which perform a redirect. These lines are not necessary for local development.
  6. Also, look for the portion of htaccess that's under the heading, "# Ensure a trailing slash." Change the rewrite rule in that section to match your local development URL (e.g. http://localhost:8888).
  7. Open a web browser and visit http://localhost:8888/, or your local development URL (defined in MAMP).
  8. The website will load and a "monkcache" folder or "monkcache.db" file will be created locally (see below for more details). You're up and running!

Staying in sync

All URLs of your local site will request data directly from your Ekklesia 360 site. If any content is changed from within the Ekklesia 360 CMS, you'll need to clear your local site's cache in order to refresh your local version. Definitely check out these tools for help clearing your site's cache easily and debugging API requests.

If brand new URLs are created for your site (say if, a new Page is created in the Pages module), it is necessary to download a new copy of your site's remote ".htaccess" file and repeat Step #4 above.

Cache

Ekklesia 360 / MonkCMS automatically chooses the appropriate cache adapter for your site based on whether the PHP SQLite3 module is enabled in your hosting environment (it is by default in PHP 5.3+). This is stored in the "CACHE_ADAPTER" setting in "monkcode.txt". If SQLite3 is enabled, the value will be set to "sqlite" and the cache will be stored in a single "monkcache.db" file. Otherwise, the value will be set to "file" and the cache will be stored as individual files within a "monkcache" directory.

When developing sites locally, feel free to set the "CACHE_ADAPTER" setting to whichever you prefer. If the PHP SQLite3 module is not enabled in your local development environment, you'll quickly run into PHP exceptions that say as much. In that case, use the "file" adapter, as it works in just about any setup.

Tips

Definitely check out our snippets for neat code examples!