Requirements

Grav has intentionally been designed with few requirements. You can easily run Grav on your local computer, as well as 99% of all Web hosting providers. If you have a pen handy, jot down the following Grav system requirements:

  1. Webserver (Apache, Nginx, LiteSpeed, Lightly, IIS, etc.)
  2. PHP 5.5.9 or higher
  3. hmm... that's it really, (but please look at php requirements for a smooth experience)!

Grav is built with plain text files for your content. There is no database needed.

A PHP user cache such as APC, APCu, XCache, Memcached, or Redis is highly recommended for optimal performance. Not to worry though, these are usually already part of your hosting package!

Web Servers

Grav is so simple and versatile, that you don't even need a web server to run it. You can actually run it directly off the built-in router.php PHP tool as long as you're running PHP 5.5.9 or later. This is a useful way to check a Grav install and perform some brief development, but it is not recommended for a live site or even for advanced development tasks. We've outlined how in our Installation guide.

Even though technically you do not need a standalone web server, it is better to run one, even for local development. Luckily there are many options depending on your platform:

Mac

  • OS X 10.9 Mavericks already ships with the Apache Web server and PHP 5.5, so job done!
  • MAMP/MAMP Pro comes with Apache, MySQL and of course PHP. It is a great way to get more control over which version of PHP you are running, setting up virtual hosts, plus other useful features such as automatically handling dynamic DNS.
  • AMPPS is a software stack from Softaculous enabling Apache, PHP, Perl, Python,.. . This includes everything you need (and more) for GRAV development.

Windows

  • XAMPP provides Apache, PHP, and MySQL in one simple package.
  • EasyPHP provides a personal Web hosting package as well as a more powerful developer version.
  • MAMP for Windows is a long-time Mac favorite, but now available for Windows.
  • IIS with PHP is a fast way to run PHP on Windows.
  • AMPPS is a software stack from Softaculous enabling Apache, PHP, Perl, Python,.. . This includes everything you need (and more) for GRAV development.

Linux

  • Many distributions of Linux already come with Apache and PHP built-in. If they're not, the distribution usually provides a package manager through which you can install them without much hassle. More advanced configurations should be investigated with the help of a good search engine.

Apache Requirements

Even though most distributions of Apache come with everything needed, for the sake of completeness, here is a list of required Apache modules:

  • mod_rewrite
  • mod_ssl (if you wish to run Grav under SSL)

You should also ensure you have AllowOverride All set in the <Directory> and/or <VirtualHost> blocks so that the .htaccess file processes correctly, and rewrite rules take effect.

IIS Requirements

Although IIS is considered a webserver ready to run 'out-of-the-box' there are some changes that need to be made. To get Grav to run on an IIS server you need to install URL Rewrite. This can be accomplished using Microsoft Web Platform Installer from within IIS. You can also install URL Rewrite by going to iis.net.

PHP Requirements

Most hosting providers and even local LAMP setups have PHP pre-configured with everything you need for Grav to run 'out-of-the-box'. However, some Windows setups, and even Linux distributions local or on VPS (I'm looking at you Debian!) - ship with a very minimal PHP compile. Therefore, you may need to install or enable these PHP modules:

  • gd (a graphics library used to manipulate images)
  • curl (client for URL handling used by GPM)
  • openssl (secure sockets library used by GPM)
  • zip extension support (used by GPM)
  • mbstring (multibyte string support)
  • xml (XML support)

For enabling openssl and (un)zip support you will need to find in the php.ini file of your Linux distribution for lines like:

  • ;extension=openssl.so.
  • ;extension=zip.so.

and remove the leading semicolon.

Optional Modules
  • apcu for increased cache performance
  • opcache for increased PHP performance
  • xcache alternative to apcu, not as fast, but still pretty good
  • yaml PECL Yaml provides native yaml processing and can dramatically increase performance
  • xdebug useful for debugging in a development environment

Permissions

For Grav to function properly, your webserver needs to have the appropriate file permissions in order to write logs, caches, etc. When using either the CLI or GPM, the user running PHP from the command line also needs to have the appropriate permissions to modify files.

By default, Grav will install with 644 and 755 permissions for files and folders, respectively. Most hosting providers have configurations that ensure that a webserver running PHP will allow you to create and modify files within your user account. This means that Grav runs out-of-the-box on the vast majority of hosting providers.

However, if you are running on a dedicated server, or even your local environment, you may need to adjust permissions to ensure your user and your webserver can modify files as needed. There are a couple of approaches you can take.

  1. In a local development environment, you can usually configure your webserver to run under your user profile. This way the web server will always allow you to create and modify files.

  2. Change the group permissions on all files and folders so that the webserver's group has write access to files and folders while keeping the standard permissions. This requires a few commands to make this work.

First, find out which user Apache runs with by running the following command:

ps aux | grep -v root | grep apache | cut -d\  -f1 | sort | uniq 

Now, find out which group this user belongs to by running this command (note: adjust USERNAME with the apache username you found in the previous command)

groups USERNAME

(note: adjust GROUP to be the group your apache runs under, found in the previous command. [www-data, apache, nobody, etc.]):

chgrp -R GROUP .
find . -type f | xargs chmod 664
find ./bin -type f | xargs chmod 775
find . -type d | xargs chmod 775
find . -type d | xargs chmod +s
umask 0002

If you need to invoke superuser permissions, you would run find … | sudo xargs chmod … instead.

Recommended Tools

Text Editors

Although you can get away with Notepad, Textedit, Vi, or whatever default text editor comes with your platform, we recommend using a good text editor with syntax highlighting to make things easier. Here are some recommended options:

  1. SublimeText - OS X/Windows/Linux - A commercial developer's editor, but well worth the price. Very powerful especially combined with plugins such as Markdown Extended, Pretty YAML, and PHP-Twig.
  2. Atom - OS X/Windows/Linux - A new editor developed by Github. It's free and open source. It is similar to Sublime, but does not have the sheer depth of plugins available yet.
  3. Notepad++ - Windows - A free and very popular developer's editor for Windows.
  4. Bluefish - OS X/Windows/Linux - A free, open source text editor geared towards programmers and web developers.

Markdown Editors

Another option if you primarily work with just creating content, is to use a Markdown Editor. These often are very content-centric and usually provide a live-preview of your content rendered as HTML. There are literally hundreds of these, but some good options include:

  1. MacDown - OS X - Free, a simple lightweight open source Markdown editor.
  2. LightPaper - OS X - $9.99, clean, powerful. Our markdown editor of choice on the Mac. Get 25% OFF with Discount Code: GET_GRAV_25
  3. MarkDrop - OS X - $5, but super clean and and Droplr support built-in.
  4. MarkdownPad - Windows - Free and Pro versions. Even has YAML front-matter support. A very solid solution for Windows users .

FTP Clients

Although there are many ways to deploy Grav, the simplest is to simply copy your local site to your hosting provider. The easiest way to accomplish this is with an FTP Client. There are many available, but some recommended ones include:

  1. Transmit - OS X - The de facto FTP/SFTP client on OS X. Easy to use, fast, folder-syncing and pretty much anything else you could ask for.
  2. FileZilla - OS X/Windows/Linux - Probably the best option for Windows and Linux users. Free and very powerful (but very ugly on the Mac!).
  3. Cyberduck - OS X/Windows - A decent free option for both OS X and Windows users. Not as full featured as the others.
  4. ForkLift - OS X - A solid alternative to Transmit, and slightly cheaper to boot.